用量限制

由於 Google Sheets API 為共用服務,因此我們會套用配額和限制,確保所有使用者都能公平使用並保護 Google Workspace 系統的整體健康狀態。

配額限制

Sheets API 沒有 API 要求的固定大小限制,但使用者可能會受到不受 Google 試算表控管的處理元件限制。 Google 建議最多使用 2 MB 的酬載,以加速處理要求。

Sheets API 有每分鐘配額,並且每分鐘會重新填入。例如,每項專案的每分鐘讀取要求數上限為 300 個。如果應用程式在一分鐘內傳送 350 個要求,額外的 50 個要求就會超過配額,並產生 429: Too many requests HTTP 狀態碼回應。在這種情況下,您應該使用指數輪詢演算法。1 分鐘後,您可以再次執行要求。使用者可以同時提交多個要求,前提是不得超出配額限制。

系統會統一套用所有試算表要求。也就是說,如果有任何要求無效,整個更新都會失敗,且不會套用任何可能的可能變更。

下表詳細說明瞭要求限制。請注意,您不會超過每分鐘配額,因此每天可發出的要求數量沒有限制。

配額
讀取要求數
每項專案每分鐘 300
每項專案每位使用者每分鐘 60
寫入要求數
每項專案每分鐘 300
每項專案每位使用者每分鐘 60

如要進一步瞭解檔案限制,請參閱 Google 雲端硬碟可儲存的檔案

解決以時間為準的配額錯誤

以時間為基礎的錯誤 (每 X 分鐘最多 N 次要求) 建議程式碼會擷取例外狀況,並使用截斷指數輪詢,確保裝置不會產生過多負載。

指數輪詢是網路應用程式的標準錯誤處理策略。指數輪詢演算法會使用指數遞增的重試要求來重試要求,最長輪詢時間則為最長。如果要求還是失敗,請務必將要求之間的延遲時間隨時間提高,直到要求成功為止。

演算法範例

指數輪詢演算法會以指數方式限制要求,並在重試之間增加等待時間,直到最長的輪詢時間為止。例如:

  1. 向 Google Sheets 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 秒重試一次。在某個時間點,用戶端應該避免無限期重試。

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

定價

使用 Google Sheets API 時,無須支付額外費用。超過配額要求限制並不會產生額外費用,您的帳戶也不會產生費用。

申請提高配額

視專案的資源用量而定,您可能需要申請提高配額。由服務帳戶使用的 API 呼叫會視為使用單一帳戶。即使申請提高配額,我們也無法保證核准。配額增加可能會比較久。

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

詳情請參閱下列資源: