Directory API：限制與配額

限制和配額可避免 Google 基礎架構在自動化流程中，以不當方式使用 Directory API。API 要求過多可能是因為無害的錯字，也可能是因為系統設計不佳，導致不必要的 API 呼叫。無論原因為何，只要來自特定來源的流量達到一定程度，就必須封鎖，以確保 Google Workspace 系統整體運作正常。這項機制可確保個別開發人員的行為不會對整個社群造成負面影響。

如果 API 要求失敗 (這種情況很少發生)，API 會傳回 HTTP 狀態碼和錯誤原因。此外，回應主體也會詳細說明錯誤原因。

下表列出可能的錯誤代碼、原因、對應說明，以及因達到配額限制而發生錯誤時的應變措施建議。

Code 原因 說明 應變措施建議
403 userRateLimitExceeded 表示已超過使用者頻率限制。在 Google Cloud 控制台中，預設值為每位使用者每分鐘 2,400 項查詢 (每個 Google Cloud 專案)。 請前往 Google Cloud 專案的 Admin SDK API 配額頁面提高每位使用者的上限，或使用指數輪詢降低傳送要求的頻率。
403 quotaExceeded 表示某項作業的並行要求數量已達上限。 請使用指數輪詢重試。您必須降低傳送要求的頻率。
429 rateLimitExceeded 表示某項作業的並行要求數量已達上限。 請使用指數輪詢重試。您必須降低傳送要求的頻率。 這項限制是針對每個 Google Workspace 帳戶，而非每個 API 用戶端或每位使用者。 這項上限無法提高。

實行指數輪詢

指數輪詢是指用戶端定期重試失敗的要求，並逐漸增加重試次數。這是網路應用程式的標準錯誤處理策略。使用指數輪詢可以提升頻寬使用的效率，減少取得成功回應所需的要求數，並最大化並行環境中的要求總處理量。

下列是簡單的指數輪詢實作流程：

  1. 對 API 提出要求
  2. 收到含有可重試錯誤代碼的錯誤回應
  3. 等待 1 秒 + random_number_milliseconds 秒
  4. 重試要求
  5. 收到含有可重試錯誤代碼的錯誤回應
  6. 等待 2 秒 + random_number_milliseconds 秒
  7. 重試要求
  8. 收到含有可重試錯誤代碼的錯誤回應
  9. 等待 4 秒 + random_number_milliseconds 秒
  10. 重試要求
  11. 收到含有可重試錯誤代碼的錯誤回應
  12. 等待 8 秒 + random_number_milliseconds 秒
  13. 重試要求
  14. 收到含有可重試錯誤代碼的錯誤回應
  15. 等待 16 秒 + random_number_milliseconds 秒
  16. 重試要求
  17. 如果仍發生錯誤，請停止並記錄錯誤。

在上述流程中，random_number_milliseconds 是小於或等於 1000 的隨機毫秒數。這是為了避免在某些並行實作中發生特定鎖定錯誤。每次等待後，都必須重新定義 random_number_milliseconds。

注意：等待時間一律是 (2 ^ n) + random_number_milliseconds，其中 n 是一開始定義為 0 的單調遞增整數。對於每個疊代 (每次要求)，n 會遞增 1。

演算法已設定為會在 n 等於 5 時終止。這個上限只是為了防止用戶端無限重試，導致要求在總延遲時間達到約 32 秒之後，才會被視為「無法復原的錯誤」。如有需要，API 用戶端可以實作更多次嘗試。

API 限制和配額

API 限制類別 限制
建立使用者 使用 Directory API 時，每個網域每秒最多只能建立 10 位使用者。
刪除使用者 使用 Directory API 時，每個網域每秒最多可刪除 5 位使用者。這是每個網域的後端服務限制，無法在 Google Cloud 控制台專案配額中調整。傳送批次要求時，請確保所有批次的作業總數不超過每秒查詢次數 (QPS) 5 次。
刪除群組成員 使用 Directory API 時，每個網域每秒最多可刪除 30 位群組成員。這是每個網域的後端服務限制，無法在 Google Cloud 控制台專案配額中調整。傳送批次要求時，請確保所有批次的作業總數不超過每秒查詢次數 (QPS)。
群組已新增為其他群組的成員 子群組成員最多可能需要 10 分鐘，才會顯示為上層群組成員。這項限制可能會因系統容量而異。
行動裝置

使用 Directory API 時，您最多可以執行：

  • 每秒 20 個動作要求。
  • 每秒 20 項刪除要求。
  • 每秒 10 項 GET 要求。
  • 每秒 10 項清單要求。
重新命名使用者 最多可能需要 10 分鐘，才會在所有服務中生效。建議您先將使用者登出所有瀏覽器工作階段和服務，再重新命名。詳情請參閱「更新使用者」。
建立/更新組織單位
  • 使用 Directory API 時，每位客戶每秒最多只能建立/更新 1 個組織單位。
  • 客戶的組織單位階層最多只能有 35 層。
  • 每位客戶的組織單位總數不得超過 40,000 個。
API 配額類別 配額
Chrome 裝置 annotatedLocation，字元數上限 裝置位置資訊的字元數上限為 200。
Chrome 裝置 notes，字元數上限 裝置附註資訊的字元數上限為 500。
Chrome 裝置，最多 user 個字元 裝置使用者名稱的長度上限為 100 個字元。
網域別名數量上限 網域別名數量上限為 20 個。
群組，說明 說明長度上限為 4,096 個字元。
每個帳戶的群組數量 如果使用舊版免費 G Suite 帳戶，群組數量上限為 10 個。其他版本則沒有群組數量限制。
群組、每個群組的成員 如果使用舊版免費 G Suite 帳戶，群組最多可包含 100 位成員。其他版本則沒有群組成員人數限制。 如要瞭解每位使用者的群組成員資格限制，請參閱「瞭解網路論壇政策與使用限制」。
maxResults 查詢字串 API 會傳回：
  • Chrome 和行動裝置：預設值和每頁最多 100 個項目。
  • 群組和群組成員：預設和上限為每頁 200 個項目。
  • 使用者：預設為 100 個項目，每頁最多 500 個項目。
使用者別名和組織單位資源不使用回應分頁。所有使用者的主要電子郵件地址都會依字母順序傳回，且回應順序不區分大小寫。
多個網域，帳戶允許的網域數量上限 600 個 (1 個主網域 + 599 個額外網域)
組織單位，一次可移動的使用者人數上限 一次可移動 20 位使用者。而且使用者的主要電子郵件地址必須已存在於帳戶中。
使用者別名 每個使用者帳戶最多可有 30 個別名。
使用者別名，使用已刪除的別名 刪除的使用者別名可以立即再次使用。

其他類型的限制 限制和規範
計費和建立使用者 如果使用者採用 Google Workspace 彈性方案，透過這個 API 建立使用者會產生費用，並計入客戶帳單帳戶。舉例來說，如果您採用 Google Workspace 彈性方案，建立 10 位使用者後，系統會根據建立時間按比例計算，向您的帳戶收取 10 份 Google Workspace 授權的費用。如果您採用年繳方案，代表您已預先承諾支付一定數量的授權費用，因此只能建立約定數量的使用者。如要進一步瞭解計費方案和帳單帳戶，請造訪管理員說明中心。
First and Last Names 名字和姓氏最多 40 個字元。支援 Unicode/UTF-8 字元，可包含空格、英文字母 (a-z)、數字 (0-9)、連字號 (-)、正斜線 (/) 和半形句號 (.)。如要進一步瞭解字元使用規則，請參閱管理說明中心。
群組，刪除 刪除群組並不會刪除群組成員的使用者帳戶。
群組和群組成員、電子郵件地址變更 在這個版本的 API 中，您可以在啟用 Google Workspace 服務前變更群組的電子郵件地址。請使用 Google 管理控制台變更群組成員的電子郵件地址。變更後，API 會自動反映電子郵件地址變更。
群組、設定 您可以使用 Google 管理控制台，管理網路論壇的存取權設定、共用選項、監控和討論封存。如要進一步瞭解群組設定，請造訪管理員說明中心。
群組、傳送訊息 為防範垃圾郵件和電子郵件濫用行為，Google 限制了您一次可傳送給外部收件者的郵件數量。如果您傳送郵件給群組，每位外部成員都會計為一位收件者。詳情請參閱「電子郵件傳送上限」和「避免寄給 Gmail 使用者的郵件遭到封鎖或歸類為垃圾郵件」。
網路論壇，傳送 NDR 郵件 您無法將無法送達回條 (NDR，又稱「退信通知」) 傳送或轉寄給群組。
使用者建立的群組，限制 如要瞭解使用者建立的群組限制，請參閱管理說明中心
組織單位、開啟/關閉服務 您可以使用 Google 管理控制台，為組織單位開啟或關閉服務。
密碼 可以包含任何字元組合。至少須有 8 個字元。長度上限為 100 個半形字元。
相片 在這個版本的 API 中，相片是指使用者最新的 Google 個人資料相片。
使用者名稱 使用者名稱可以包含英文字母 (a-z)、數字 (0-9)、連字號 (-)、底線 (_)，Google Workspace 也能辨識點號或句號 (.)。這與 Gmail 不同。使用者名稱不得包含等號 (=)、角括號 (< 和 >) 或連續多個點號 (.)。詳情請參閱管理說明中心。
使用者名稱、重新命名 Google Hangouts 會在重新命名後捨棄所有記住的即時通訊邀請。使用者必須再次要求權限，才能與好友聊天。舊的使用者名稱會保留為電子郵件別名，確保電子郵件轉寄設定能持續傳送郵件，且無法做為新的使用者名稱。如要進一步瞭解重新命名使用者帶來的影響，請參閱管理員說明中心。重新命名後，請使用「刪除使用者別名」作業移除電子郵件別名。
使用者位於多個網域 Google Workspace 帳戶可以包含您的任何網域。在多網域帳戶中，某個網域的使用者可以與其他帳戶網域的使用者共用服務。多個網域元件如下：
  • 主網域：帳戶的主網域是接受《Google Workspace 服務條款》協議的管理員網域。這個網域位於頂層組織單位的帳戶層級。申請 Google Workspace 帳戶時，建議您使用公司網域做為主網域，並保留其他網域做為特殊用途，例如前測和測試。
    • 所有超級管理員都能管理整個帳戶。
    • API 無法變更或移動 Google Workspace 帳戶的主網域。不過，API 可以重新命名使用者帳戶，將電子郵件地址從一個網域變更為另一個網域。
    • 如果是 Google Workspace 帳戶，您必須在 21 天內驗證主網域擁有權。如要將額外網域設為使用者的主要電子郵件地址，必須先驗證網域擁有權。在這種情況下，21 天寬限期不適用。
    • 在這個版本的 API 中，主網域的設定會套用至與帳戶相關聯的所有網域，但使用者對 Google Workspace 服務的存取權除外。
  • 其他帳戶網域：建立主網域並設定帳戶後，您可以將其他網域新增至帳戶。如果是額外網域，請在設定網域時驗證擁有權，然後再將網域用於使用者的主要電子郵件地址。
  • 使用者的主網域：使用者主要電子郵件地址所用的網域，就是使用者的主網域。這個網域可以是帳戶中的任何網域，包括主網域。
如要瞭解最新的多重網域限制，請參閱多重網域限制。包括網域別名、帳戶合併等資訊。
警告、群組成員 GROUP_CANNOT_CONTAIN_CYCLE：API 不允許群組成員資格出現循環。舉例來說，如果群組 1 是群組 2 的成員，群組 2 就不能是群組 1 的成員。