Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

用量限制

Google 日曆 API 設有配額，確保所有使用者都能公平使用。使用 Calendar API 時，請注意以下三項重要限制：

API 用量配額：依專案和使用者強制執行。詳情請參閱「Calendar API 用量配額類型」。
Google 日曆一般用量限制：Google Calendar API 是一項共用服務，設有限制以保護 Google Workspace 系統的整體效能。詳情請參閱「避免達到日曆使用限制」。
作業限制：這些限制隨時可能變動。例如，如果您嘗試快速連續寫入單一日曆，就會發生這種情況。

Calendar API 配額

系統會強制執行兩種配額：

每項專案每分鐘：Google Cloud 雲端專案一分鐘內可提出的要求數量。
每分鐘每位使用者每項專案：這是任何一位特定使用者在雲端專案中可提出的要求數量。這項限制旨在確保使用者公平分配用量。

配額是以滑動區間為單位，每分鐘計算一次。如果流量在一分鐘內快速激增，超過每分鐘配額，系統會在下一個時間範圍內限制頻率，確保平均用量不超過配額。

下表詳細列出這些限制：

用量限制類型	限制
每項專案每分鐘	10,000 項要求
每項專案每位使用者每分鐘	600 項要求

每日結算最低曝光次數門檻

這項每日每專案限制，定義了 Google Cloud 專案在 24 小時內可使用的要求數量上限，超過這個上限就會產生費用。

用量低於這個門檻不會產生額外費用，您的 Google Cloud 帳戶也不會產生帳單。我們會在 2026 年稍晚提供完整的帳單詳細資料，並在任何異動生效前至少 90 天通知您。

您無法要求提高這項每日門檻上限。

下表詳細列出限制：

門檻限制類型	限制
每項專案每天	1,000,000 項要求

詳情請參閱「Google Workspace 標準化模型：代理工具和 API」。

解決時間配額錯誤

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

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

演算法範例

指數輪詢演算法會以指數方式重試要求，並增加重試之間的等待時間，直到達到最大輪詢時間。例如：

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

其中：

等待時間為 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 日曆 API 的所有標準用途皆無須額外付費。預計在 2026 年稍晚，如果超出配額要求限制，Google Cloud 帳單帳戶將產生費用。詳情請參閱「Google Workspace 標準化模型：代理工具和 API」。

申請提高配額

視專案的資源用量而定，您可能需要要求調整配額。服務帳戶發出的 API 呼叫會視為使用單一帳戶。我們不保證一定能核准您提出的配額調整要求。如果配額調整要求會大幅提高配額值，可能需要較長時間才能獲得核准。

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

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

疑難排解

如果超過任一配額，系統就會受到頻率限制，並傳回 403 usageLimits 狀態碼或 429 usageLimits 狀態碼，做為查詢的回應。

遇到這種問題時，建議按照以下步驟處理：

請務必遵循所有最佳做法：使用指數輪詢、隨機化流量模式，以及使用推播通知。
如果專案規模擴大，使用者人數增加，可以要求提高配額。
如果達到個別使用者配額上限，可以採取下列做法：
- 如果您使用服務帳戶，請將負載分配給使用者，或分配給多個服務帳戶。
- 雖然您可以要求提高每位使用者的配額，但一般來說，不建議將配額提高到預設值以上，因為應用程式可能會開始達到其他類型的限制，例如一般日曆用量限制或作業限制。
如要測試配額限制，請註冊一個與正式環境專案設定相似的獨立測試專案。詳情請參閱「測試配額限制處理方式」。

隨機流量模式

日曆用戶端容易因多個用戶端同時執行作業，而出現流量激增的情況。舉例來說，日曆用戶端常見的不良做法是在午夜執行完整同步作業。這幾乎肯定會導致超過每分鐘配額，並造成頻率限制和退避。

為避免這種情況，請盡可能將流量分散到全天。如果用戶端需要每天同步處理，請讓用戶端決定隨機時間 (每個用戶端的時間不同)。如需定期執行作業，請將間隔時間調整為 +/- 25%。這樣一來，流量會更平均分配，使用者體驗也會大幅提升。

使用推播通知

常見的用途是在使用者日曆發生變更時執行動作。這裡的反模式是重複輪詢每個感興趣的日曆。這會很快用完所有配額。舉例來說，如果應用程式有 5,000 名使用者，且每分鐘輪詢每位使用者的日曆一次，則每分鐘配額至少需要 5,000，甚至在完成任何工作之前。

伺服器端應用程式可以註冊推播通知，以便在發生您感興趣的事件時通知您。雖然設定較為繁複，但能大幅提升配額使用效率，並提供更優質的使用者體驗。請務必指定要接收通知的 eventType。詳情請參閱「推播通知」。

妥善分配服務帳戶

如果應用程式使用全網域委派執行要求，系統預設會根據「每分鐘每位使用者每項專案」配額向服務帳戶收費，而非您模擬的使用者。這表示服務帳戶可能會用盡配額，並受到頻率限制，即使該帳戶可能在多位使用者的日曆上運作。

如要避免這種情況，您可以使用 quotaUser 網址參數 (或 x-goog-quota-user HTTP 標頭) 指定任意字串 (最多 40 個字元)，用來識別每位不重複的使用者。Calendar API 只會使用這個值計算配額。

如要使用 quotaUser 對不同使用者強制執行每位使用者頻率限制，要求必須符合下列條件：

加入受 IP 限制的 API 金鑰：在 key 查詢參數中傳遞 API 金鑰，並為該金鑰設定 IP 位址限制，指定後端伺服器的公開 IP 位址。如果省略 API 金鑰或未設定 IP 位址限制，Calendar API 會忽略 quotaUser，並向已驗證的帳戶 (例如服務帳戶) 收取配額費用。
省略 X-Goog-User-Project 標頭：請勿在使用 quotaUser 的要求中傳送 X-Goog-User-Project HTTP 標頭。提供使用者專案會覆寫配額歸因的 API 金鑰，因此 Calendar API 會忽略 quotaUser。

詳情請參閱「限制每位使用者的要求數量」。

測試配額限制處理

為確保應用程式在實際情況下，能妥善處理達到配額限制的問題 (例如使用指數輪詢重試)，並盡可能減少對使用者造成的干擾，強烈建議您在實際環境中測試情境。

為避免干擾實際應用程式的使用，建議您在 Google Cloud 控制台中註冊獨立的測試專案，然後按照與正式版專案類似的方式設定 OAuth 同意畫面。接著，您可以為這項專案設定人為偏低的配額限制，並觀察應用程式的行為。

日曆 MCP 伺服器配額

日曆 MCP 伺服器會使用查詢成本分配指標。下表依區段詳細列出各個 Calendar MCP 伺服器方法的查詢費用：

Calendar MCP 配額