用量限制

由於 Google Chat API 是共用服務,我們會套用配額和限制,確保所有使用者都能公平使用這項服務,並保護 Google Workspace 的整體效能。

如果您超出配額,就會收到 429: Too many requests HTTP 狀態碼回應。Chat 後端的額外速率限制檢查也可能會產生相同的錯誤回應。如果發生這個錯誤,您應使用指數輪詢演算法,然後再試一次。只要不超過下表中列出的每分鐘配額,則沒有每天可提出的要求數量限制。

Chat API 方法適用兩種配額類型:每個聊天室配額和每個專案配額。

聊天室配額

每個聊天室配額會限制特定聊天室的查詢頻率,並由在該聊天室中執行的所有 Chat 應用程式共用,呼叫每個配額的 Chat API 方法。

下表詳細說明每個空間的查詢限制:

每個空間配額

Chat API 方法

限制 (每 60 秒,與聊天室中所有 Chat 擴充應用程式
共用)

每分鐘讀取數

media.download

spaces.get

spaces.members.get

spaces.members.list

spaces.messages.get

spaces.messages.list

spaces.messages.attachments.get

spaces.messages.reactions.list

900

每分鐘寫入數

media.upload

spaces.delete

spaces.patch

spaces.messages.create (也適用於連入的 Webhook)

spaces.messages.delete

spaces.messages.patch

spaces.messages.reactions.create

spaces.messages.reactions.delete

60

每項專案的配額

每個專案的配額會限制 Google Cloud 專案的查詢頻率,因此會套用至針對每個配額呼叫指定 Chat API 方法的單一 Chat 應用程式。

下表詳細說明每個專案的查詢限制。您也可以在「配額」頁面找到這些限制。

每個專案的配額

Chat API 方法

限制 (每 60 秒)

每分鐘訊息寫入數

spaces.messages.create

spaces.messages.patch

spaces.messages.delete

3000

每分鐘訊息讀取數

spaces.messages.get

spaces.messages.list

3000

每分鐘會員寫入數

spaces.members.create

spaces.members.delete

300

每分鐘成員資格讀取數

spaces.members.get

spaces.members.list

3000

每分鐘的聊天室寫入數

spaces.setup

spaces.create

spaces.patch

spaces.delete

60

每分鐘的聊天室讀取數

spaces.get

spaces.list

spaces.findDirectMessage

3000

每分鐘連結寫入數

media.upload

600

每分鐘連結讀取數

spaces.messages.attachments.get

media.download

3000

每分鐘回應寫入數

spaces.messages.reactions.create

spaces.messages.reactions.delete

600

每分鐘的回應讀取數

spaces.messages.reactions.list

3000

額外用量限制

建立 GROUP_CHATSPACE 類型的聊天室時,必須遵守額外的配額限制 (使用 spaces.createspaces.setup 方法)。此類類型每分鐘應建立不到 35 個空格,每小時建立不到 800 個空格。DIRECT_MESSAGE 類型的聊天室不適用這些額外配額限制。

指定相同空間的 API 流量過高,可能會觸發額外的內部限制,而這些限制不會顯示在「配額」頁面中。

解決以時間為依據的配額錯誤

針對所有時間相關錯誤 (每 X 分鐘最多 N 個要求),建議您在程式碼中擷取例外狀況,並使用截斷的指數型延遲,確保裝置不會產生過多負載。

指數輪詢是網路應用程式的標準錯誤處理策略。指數輪詢演算法會以指數方式逐漸增加每次重試之間的等待時間,直到達到最大輪詢時間為止。如果要求仍無法成功,請務必讓要求之間的延遲時間隨著時間增加,直到要求成功為止。

演算法範例

指數輪詢演算法會以指數方式重試要求,將每次重試之間的等待時間增加至最長輪詢時間。例如:

  1. 向 Google Chat API 提出要求。
  2. 如果要求失敗,請等待 1 + random_number_milliseconds 後再重試要求。
  3. 如果要求失敗,請等待 2 + random_number_milliseconds,然後重試要求。
  4. 如果要求失敗,請等待 4 + random_number_milliseconds 秒後再重試要求。
  5. 依此類推,時間上限為 maximum_backoff
  6. 繼續等待及重試,直到重試次數達特定上限,但不再增加每次重試之間的等待時間。

其中:

  • 等待時間為 min(((2^n)+random_number_milliseconds), maximum_backoff)n 會在每次疊代 (要求) 時增加 1。
  • random_number_milliseconds 是小於或等於 1,000 的隨機毫秒數。這種設定有助於避免多個用戶端在特定情況下全部同步進行處理並同時重試,導致同步傳送每一波要求。每次重試要求後,系統會重新計算 random_number_milliseconds 的值。
  • maximum_backoff 通常是 32 或 64 秒,適合的值視用途而定。

用戶端可在達到 maximum_backoff 時間後繼續重試。之後的重試就不需繼續增加輪詢時間。舉例來說,如果用戶端使用的 maximum_backoff 時間上限是 64 秒,達到這個值之後,用戶端就可以維持在每 64 秒重試一次的頻率。在某些情況下,應避免用戶端無限期重試。

重試之間的等待時間和重試次數,取決於您的用途和網路狀況。

要求提高每項專案的配額

視專案的資源用量而定,您可能會想要申請提高配額。服務帳戶的 API 呼叫視為使用單一帳戶。我們不保證一定能核准您提出的配額增加要求。不過如要增加大量配額,可能會需要更長的核准程序處理時間。

並非所有專案的配額都相同。隨著 Google Cloud 的使用量隨時間增加,您可能需要提高配額。如果您預期用量將大幅攀升,可以透過 Google Cloud 控制台的「配額」頁面主動要求調整配額

如要進一步瞭解相關內容,請參閱下列資源: