限制和配額可避免 Google 基礎架構在自動化流程中以不當方式使用 Directory API。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 服務前變更群組的電子郵件地址。您可以使用管理控制台變更群組成員的電子郵件地址。變更後，API 會自動反映電子郵件地址變更。 |
| 群組、設定 | 您可以透過管理控制台管理群組存取權設定、共用選項、監控和討論內容封存。如要進一步瞭解群組設定，請參閱管理說明中心。 |
| 群組、傳送訊息 | 為了杜絕垃圾郵件和電子郵件濫用情形，Google 會限制您一次可傳送給外部收件者的郵件數量。如果您傳送訊息給群組，每位外部成員都會計為一位收件者。詳情請參閱「電子郵件傳送限制」和「避免寄給 Gmail 使用者的郵件遭到封鎖或歸類為垃圾郵件 」。 |
| 群組、傳送 NDR 郵件 | 您無法將未送達回條 (NDR，也稱為「退回郵件」) 傳送或轉寄給群組。 |
| 使用者建立的群組和限制 | 如要瞭解使用者建立的群組限制，請參閱管理說明中心 |
| 機構單位，開啟/關閉服務 | 您可以使用管理控制台管理機構單位的服務開啟/關閉。 |
| 密碼 | 可包含任何字元組合。至少須輸入 8 個半形字元。長度上限為 100 個半形字元。 |
| 相片 | 在這個 API 版本中，相片是使用者的最新 Google 個人資料相片。 |
| 使用者名稱 | 使用者名稱可以包含英文字母 (a-z)、數字 (0-9)、連字號 (-)、底線 (_)，Google Workspace 也支援點號 (.)，這與 Gmail 不同。使用者名稱不得包含等號 (=)、角括號 (<、>)，或是連續使用半形句號 (.)。詳情請參閱管理說明中心。 |
| 使用者名稱、重新命名 | 重新命名後，Google Hangouts 會捨棄所有已記住的即時通訊邀請。使用者必須再次要求權限，才能與好友聊天。舊使用者名稱會保留做為電子郵件別名，以確保在電子郵件轉寄設定的情況下，郵件能持續送達，但無法做為新使用者名稱使用。如要進一步瞭解變更使用者名稱的影響，請參閱管理說明中心。使用「Delete a user's alias」作業，即可在重新命名後移除電子郵件別名。 |
| 多個網域中的使用者 | Google Workspace 帳戶可以包含任何網域。在多網域帳戶中，一個網域的使用者可以與其他帳戶網域中的使用者共用服務。多重網域元件如下：
|
| 警告、群組成員 | GROUP_CANNOT_CONTAIN_CYCLE – API 不允許群組成員有循環。舉例來說，如果群組 1 是群組 2 的成員，群組 2 就不能是群組 1 的成員。 |