为什么更改 maxResults 会导致 Google API / Gmail API 中的结果总数发生变化？

Question

为什么更改 maxResults 参数会导致 resultSizeEstimate 在调用 gmail.users.messages.list() 时急剧变化？

Google API 文档将 resultSizeEstimate 列为：估计的总数结果。

...这意味着不应仅通过更改每页返回的项目数来更改此最终结果集。

示例 A：maxResults: 1 ... resultSizeEstimate: 8

{
  "config": {
    "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9&maxResults=1",
    "method": "GET",
    "headers": {
      "Accept-Encoding": "gzip",
      "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)",
      "Authorization": "Bearer [snip]",
      "Accept": "application/json"
    },
    "params": {
      "q": "before:2021/1/9",
      "maxResults": 1
    },
    "responseType": "json"
  },
  "data": {
    "messages": [ ... ],
    "nextPageToken": "14911817971227869758",
    "resultSizeEstimate": 8
  },
  "headers": {
    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"",
    "cache-control": "private",
    "connection": "close",
    "content-encoding": "gzip",
    "content-type": "application/json; charset=UTF-8",
    "date": "Sun, 09 Jan 2022 12:59:48 GMT",
    "server": "ESF",
    "transfer-encoding": "chunked",
    "vary": "Origin, X-Origin, Referer",
    "x-content-type-options": "nosniff",
    "x-frame-options": "SAMEORIGIN",
    "x-xss-protection": "0"
  },
  "status": 200,
  "statusText": "OK"
}

示例 B：maxResults: 2 ... resultSizeEstimate: 12

{
  "config": {
    "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9&maxResults=2",
    "method": "GET",
    "headers": {
      "Accept-Encoding": "gzip",
      "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)",
      "Authorization": "Bearer [snip]",
      "Accept": "application/json"
    },
    "params": {
      "q": "before:2021/1/9",
      "maxResults": 2
    },
    "responseType": "json"
  },
  "data": {
    "messages": [ ... ],
    "nextPageToken": "16903415066875011466",
    "resultSizeEstimate": 12
  },
  "headers": {
    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"",
    "cache-control": "private",
    "connection": "close",
    "content-encoding": "gzip",
    "content-type": "application/json; charset=UTF-8",
    "date": "Sun, 09 Jan 2022 13:10:48 GMT",
    "server": "ESF",
    "transfer-encoding": "chunked",
    "vary": "Origin, X-Origin, Referer",
    "x-content-type-options": "nosniff",
    "x-frame-options": "SAMEORIGIN",
    "x-xss-protection": "0"
  },
  "status": 200,
  "statusText": "OK"
}

示例 C：maxResults: (not set) ... resultSizeEstimate: 412

{
  "config": {
    "url": "https://www.googleapis.com/gmail/v1/users/me/messages?q=before%3A2021%2F1%2F9",
    "method": "GET",
    "headers": {
      "Accept-Encoding": "gzip",
      "User-Agent": "google-api-nodejs-client/0.7.2 (gzip)",
      "Authorization": "Bearer [snip]",
      "Accept": "application/json"
    },
    "params": {
      "q": "before:2021/1/9"
    },
    "responseType": "json"
  },
  "data": {
    "messages": [ ... ],
    "nextPageToken": "16942818266524948378",
    "resultSizeEstimate": 412
  },
  "headers": {
    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000,h3-Q050=\":443\"; ma=2592000,h3-Q046=\":443\"; ma=2592000,h3-Q043=\":443\"; ma=2592000,quic=\":443\"; ma=2592000; v=\"46,43\"",
    "cache-control": "private",
    "connection": "close",
    "content-encoding": "gzip",
    "content-type": "application/json; charset=UTF-8",
    "date": "Sun, 09 Jan 2022 13:09:05 GMT",
    "server": "ESF",
    "transfer-encoding": "chunked",
    "vary": "Origin, X-Origin, Referer",
    "x-content-type-options": "nosniff",
    "x-frame-options": "SAMEORIGIN",
    "x-xss-protection": "0"
  },
  "status": 200,
  "statusText": "OK"
}

Answer 1

这之前已在问题跟踪器中报告过，Google 认为这是有意为之的行为，因为 resultSizeEstimate 预计不准确；这是一个“估计”：

the reason why resultSizeEstimate shows differents values is due to its estimation. As mentioned in the documentation resultSizeEstimate is just an estimated total number of results but not the exact number of results.

参考：

users.messages.list method returns different amount of messages when using “maxResults” parameter

为什么更改 maxResults 会导致 Google API / Gmail API 中的结果总数发生变化？

Why does changing maxResults cause the total number of results to change in Google API / Gmail API?

google-api

gmail-api

参考：