限制和配額可避免自動化程序以不當方式使用 Directory API，保護 Google 基礎架構。API 提出過多要求可能是因為無害的筆誤，也可能是因為系統設計效率不彰，導致不必要的 API 呼叫。無論原因為何，一旦特定來源的流量達到一定程度，就必須封鎖該來源的流量，才能確保 Google Workspace 系統的整體健康狀態。確保一位開發人員的行為不會對整個社群造成負面影響。
如果 API 要求失敗 (機率很低)，API 會傳回 HTTP 狀態碼和錯誤原因。此外，回應主體會詳細說明導致錯誤的原因。
下表列出因達到配額上限而可能發生的錯誤代碼、原因、相應說明和建議做法。
| 程式碼 | 原因 | 說明 | 建議做法 |
|---|---|---|---|
| 403 | userRateLimitExceeded | 表示使用者超出速率限制。Google Cloud 控制台預設值為每位使用者每分鐘每個 Google Cloud 專案 2,400 個查詢。 | 在 Google Cloud 專案的 Admin SDK API 配額頁面中提高每位使用者的限制，或使用指數輪詢減緩傳送要求的速率。 |
| 403 | quotaExceeded | 表示特定作業的並行要求已達上限。 | 使用指數輪詢重試。您需要降低要求傳送速率。 |
| 429 | rateLimitExceeded | 表示特定作業的並行要求已達上限。 | 使用指數輪詢重試。您必須降低要求傳送頻率。 這項限制適用於每個 Google Workspace 帳戶，而非每個 API 用戶端或使用者。 這項上限無法提高。 |
實行指數輪詢
指數輪詢 是指用戶端定期重試失敗的要求，並逐漸增加重試次數。這是網路應用程式的標準錯誤處理策略。使用指數輪詢可提升頻寬使用效率、減少取得成功回應所需的要求數，並在並行環境中盡量提高要求總處理量。
下列是簡單的指數輪詢實作流程。
- 對 API 提出要求
- 收到含有可重試錯誤代碼的錯誤回應
- 等待 1 秒 +
random_number_milliseconds秒 - 重試要求
- 收到含有可重試錯誤代碼的錯誤回應
- 等待 2 秒 +
random_number_milliseconds秒 - 重試要求
- 收到含有可重試錯誤代碼的錯誤回應
- 等待 4 秒 +
random_number_milliseconds秒 - 重試要求
- 收到含有可重試錯誤代碼的錯誤回應
- 等待 8 秒 +
random_number_milliseconds秒 - 重試要求
- 收到含有可重試錯誤代碼的錯誤回應
- 等待 16 秒 +
random_number_milliseconds秒 - 重試要求
- 如果仍會發生錯誤，請停止並記錄錯誤。
在以上流程中，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 位使用者。 |
| 群組已新增為其他群組的成員 | 下層群組成員最多可能要過 10 分鐘，才會顯示為上層群組成員。這項限制可能會視系統容量而異。 |
| 行動裝置 |
使用 Directory API 時，您最多可以執行：
|
| 重新命名使用者 | 最多可能需要 10 分鐘，才能在所有服務中生效。建議您先將使用者登出所有瀏覽器工作階段和服務，再重新命名使用者。詳情請參閱「更新使用者」。 |
| 建立/更新機構單位 |
|
| API 配額類別 | 配額 |
Chrome 裝置 annotatedLocation，最多字元數 |
裝置位置資訊的字元數上限為 200 個。 |
Chrome 裝置 notes，最多字元數 |
裝置備註資訊的字元數上限為 500 個。 |
Chrome 裝置，最多 user 個字元 |
裝置使用者名稱的字元數上限為 100 個。 |
| 網域別名 (上限) | 網域別名數量上限為 20 個。 |
| 群組、說明 | 說明最多可輸入 4,096 個字元。 |
| 每個帳戶的群組數量 | 如果使用舊版 G Suite (免費版) 帳戶，群組數量上限為 10 個。其他版本則沒有群組數量限制。 |
| 群組、每個群組的成員 | 如果使用舊版 G Suite (免費版) 帳戶，群組最多可有 100 名成員。其他版本則沒有群組成員人數上限。 如要瞭解每位使用者的群組成員資格限制，請參閱「瞭解網路論壇政策與使用限制」一文。 |
| maxResults 查詢字串 | API 會傳回：
|
| 多個網域，帳戶中允許的網域數量上限 | 600 個 (1 個主網域 + 599 個額外網域) |
| 機構單位，一次可移動的使用者人數上限 | 一次最多可移動 20 位使用者。且帳戶中必須已有使用者的主要電子郵件地址。 |
| 使用者別名 | 每個使用者帳戶最多可有 30 個別名。 |
| 使用者別名，使用已刪除的別名 | 刪除的使用者別名可立即重複使用。 |
| 其他類型的限制 | 限制和規範 |
|---|---|
| 帳單和建立使用者 | 如果使用者採用 Google Workspace 彈性方案，使用這個 API 建立使用者會產生費用，並計入客戶帳單帳戶。舉例來說，如果您採用 Google Workspace 彈性方案，建立 10 位使用者後，系統會從建立完成的時間起，按比例計算並向您的帳戶收取 10 個 Google Workspace 授權的費用。如果您採用年約方案，表示您已預先承諾支付特定數量的授權費用，因此只能建立承諾數量的使用者。如要進一步瞭解帳單方案和帳單帳戶，請參閱管理說明中心。 |
| 姓名 | 名字和姓氏的長度上限為 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)、連字號 (-)、底線 (_) 和半形句號 (.)，但這與 Gmail 不同。使用者名稱不得包含等號 (=)、括號 (<、>) 或連續多個半形句號 (.)。詳情請參閱管理說明中心。 |
| 使用者名稱、重新命名 | 重新命名後，Google Hangouts 會捨棄所有已記憶的即時通訊邀請。使用者必須再次要求與好友對話的權限。舊使用者名稱會保留做為電子郵件別名，確保郵件轉寄設定不會中斷，但無法做為新使用者名稱。如要瞭解重新命名使用者帶來的重大影響，請參閱管理說明中心。重新命名後，請使用「刪除使用者的別名」作業移除電子郵件別名。 |
| 多個網域中的使用者 | Google Workspace 帳戶可以包含任何網域。在多網域帳戶中，一個網域的使用者可以與其他帳戶網域的使用者共用服務。多個網域元件如下：
|
| 警告、群組成員 | GROUP_CANNOT_CONTAIN_CYCLE：API 不允許群組成員資格出現週期。舉例來說，如果 group1 是 group2 的成員，group2 就不能是 group1 的成員。 |