為確保所有使用者都能公平使用 Google Calendar API,Google Calendar API 設有配額。使用 Calendar API 有三個重要限制需要考量:
- 系統會對每個專案和每位使用者強制執行 API 用量配額。詳情請參閱下一節的說明。
- 一般日曆用量限制:避免日曆使用限制。
- 作業限制:系統可能會隨時限制頻率。舉例來說,如果您嘗試快速連續寫入單一日曆。
Calendar API 用量配額類型
系統會強制執行兩種類型的配額:
- 每項專案每分鐘:這是指 Google Cloud 專案發出的要求數量。
- 每位使用者每項專案每分鐘:這是 Cloud 專案中任何特定使用者提出的要求數量。這項限制旨在協助您確保所有使用者的用量都能公平分配。
配額是以滑動區間的每分鐘計算,因此如果一分鐘內快速爆發超過每分鐘配額的流量,系統會在下一個期間內限制您達到的平均用量,以確保您的用量不會超出配額。
如果超過任一配額,系統就會限制頻率,並在查詢中收到 403 usageLimits
狀態碼或 429 usageLimits
狀態碼。如果發生這種情況,您可以採取以下做法:
要求提高配額
如要查看或變更專案的用量限制,或是想申請更多配額,請進行以下步驟:
- 確認您的專案已設有帳單帳戶。如果沒有,請先建立一個。
- 開啟 API 控制台並前往 API 程式庫「已啟用的 API」頁面,從清單中選取 API。
- 如要查看及變更配額相關設定,請點選「配額」。如要查看用量統計資料,請點選「用量」。
採用指數輪詢
我們想要減緩要求的速率時,會傳回 403「usageLimits」回應或 429 回應 (請參閱完整錯誤說明文件)。這並非嚴重錯誤,我們預期您在短暫的間隔後重試要求。如果要求抵達的速度太快,我們將再次提出要求,以此類推。為了讓上述情況順利運作,要求之間的延遲時間必須隨時間增加。
一般來說,您應使用截斷指數輪詢。Cloud Storage 說明文件已詳細說明此機制的運作方式,以及您偏好的演算法。如果您使用的是 Google 用戶端程式庫,系統通常會為您處理;請參閱程式庫說明文件。一般而言,您應使用程式庫實作,而非自行編寫。
隨機的流量模式
日曆用戶端容易因多個用戶端同時執行多項作業而出現突發的流量模式。舉例來說,日曆用戶端的常見錯誤做法是在午夜執行完整的同步處理。在大部分的情況下,這往往會導致超出每分鐘配額,導致頻率限制和輪詢。
為了避免發生這個問題,請確保流量會盡可能分散在一整天內進行。如果您的用戶端需要執行每日同步處理,請讓用戶端決定隨機時間 (每個用戶端的時間不同)。如果您需要定期執行作業,請變更間隔 +/- 25%。這樣可更平均地分配流量,提供更優質的使用者體驗。
使用推播通知
常見的用途是想要在使用者日曆出現異動時執行操作。這裡的反模式是重複輪詢每個感興趣的日曆。如此一來,即使您的應用程式有 5,000 位使用者,而且每位使用者每分鐘會輪詢一次,那麼在應用程式完成作業之前,每分鐘至少需要 5,000 次的配額。
伺服器端應用程式可註冊推播通知,以便我們在發生重要事件時通知您。這類工具需要投入更多心力設定,不過配額可以大幅提高使用效率,並提供更優質的使用者體驗。請務必指定要接收通知的 eventType
。詳情請參閱「推播通知」。
使用服務帳戶妥善進行會計作業
如果您的應用程式使用全網域委派功能執行要求,根據預設,系統會依「每位使用者每項專案每分鐘」的配額,而非您模擬的使用者,向服務帳戶計費。也就是說,即使服務帳戶可能在多名使用者的行事曆上作業,該服務帳戶仍可能用盡配額,並有頻率限制。您可以使用 quotaUser
網址參數 (或 x-goog-quota-user
HTTP 標頭) 指出要向哪位使用者收費,以避免發生此情況。這項服務只會用於計算配額。詳情請參閱 Cloud 說明文件中的「限制每位使用者的要求」一節。
測試配額限制處理
為了確保應用程式能妥善處理達到配額限制 (例如使用指數輪詢重試),並盡量減少對使用者的潛在幹擾,強烈建議您在實際環境中測試本情境。
為了讓這類測試不會幹擾您的實際應用程式使用情況,建議您在 Google API 控制台中另外註冊僅供測試用的專案,並以類似實際工作環境專案的方式設定專案。接著,您就可以為這項專案設定以蓄意低的配額,並觀察應用程式行為。
定價
Google Calendar API 的所有功能皆可免費使用。超出配額要求限制不會產生額外費用,且帳戶也不會產生費用。