制限と割り当てにより、不適切な方法で Directory API を使用する自動プロセスから Google のインフラストラクチャが保護されます。API から過剰なリクエストが発生する原因としては、無害なタイプミスや、非効率的な設計のシステムで不要な API 呼び出しが行われることが考えられます。原因にかかわらず、特定のソースからのトラフィックが一定のレベルに達した場合は、Google Workspace システムの全体的な健全性のために、そのソースからのトラフィックをブロックする必要があります。あるデベロッパーの行為が、より大きなコミュニティに悪影響を与えることがないようにします。
万が一 API リクエストが失敗すると、API は HTTP ステータス コードとエラーの理由を返します。また、レスポンスの本文にはエラーの原因の詳細な説明が含まれています。
次の一覧に、考えられるエラーコード、理由、対応する説明、割り当て上限に達したことによるエラーの推奨される対応を示します。
| コード | 理由 | 説明 | 推奨される対応 |
|---|---|---|---|
| 403 | userRateLimitExceeded | ユーザーのレート制限を超えたことを示します。Google Cloud コンソールで設定されるデフォルト値は、Google Cloud プロジェクトごとにユーザーごとに 1 分あたり 2,400 件のクエリです。 | Google Cloud プロジェクトの Admin SDK API の [割り当て] ページからユーザーごとの上限を引き上げるか、指数バックオフを使用してリクエストの送信レートを遅くします。 |
| 403 | quotaExceeded | 特定のオペレーションの同時リクエスト数の上限に達したことを示します。 | 指数バックオフを使用して再試行してください。リクエストの送信レートを下げる必要があります。 |
| 429 | rateLimitExceeded | 特定のオペレーションの同時リクエスト数の上限に達したことを示します。 | 指数バックオフを使用して再試行してください。リクエストの送信レートを下げる必要があります。この上限は API クライアント単位やユーザー単位ではなく、Google Workspace アカウント単位で適用されます。 この上限を引き上げることはできません。 |
指数バックオフの実装
指数バックオフは、失敗したリクエストをクライアントが再試行する際、失敗するごとに次の再試行までの待ち時間を増やしていく処理です。これは、ネットワーク アプリケーションに使われる標準的な エラー処理方法です。指数バックオフを使用すると、帯域幅の使用効率が向上し、正常なレスポンスを受け取るために必要なリクエスト数が減り、同時実行環境におけるリクエストのスループットが最大化されます。
単純な指数バックオフを実装するフローを次に示します。
- API に対してリクエストを行います。
- 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
- 1 秒 +
random_number_milliseconds秒待ちます - リクエストを再試行します。
- 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
- 2 秒 +
random_number_milliseconds秒待ちます - リクエストを再試行します。
- 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
- 4 秒 +
random_number_milliseconds秒待ちます - リクエストを再試行します。
- 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
- 8 秒 +
random_number_milliseconds秒待ちます - リクエストを再試行します。
- 再試行可能なエラーコードを含むエラー レスポンスを受け取ります。
- 16 秒 +
random_number_milliseconds秒待ちます - リクエストを再試行します。
- まだエラーが発生する場合は、停止してエラーを記録します。
上記のフローで、random_number_milliseconds は 1, 000 以下のミリ秒数の乱数です。これは、一部の同時実装で起こる特定のロックエラーを回避するために必要です。
待機のたびに random_number_milliseconds を再定義する必要があります。
注: 待機時間は常に (2 ^ n) + random_number_milliseconds です。ここで、n は単調増加する整数で、最初は 0 と定義されていました。n は、反復（リクエストごとに）のたびに 1 ずつ増加します。
上記のアルゴリズムは、n が 5 に達したら停止するように設定されています。この上限は、クライアントが無限に再試行することを防ぐために設けられており、合計で約 32 秒の遅延が発生してリクエストが「回復不能なエラー」と判断されることもあります。API クライアントでは、必要に応じてより多くの試行回数を実装できます。
API の制限と割り当て
| API の制限のカテゴリ | 上限 |
|---|---|
| ユーザーの作成 | Directory API を使用して、ドメインあたり 1 秒あたり 10 人を超えるユーザーを作成することはできません。 |
| グループをメンバーとして別のグループに追加しました | 子グループのメンバーが親グループのメンバーとして表示されるまで、最長で 10 分ほどかかる場合があります。この上限は、システムの容量に応じて変わる可能性があります。 |
| モバイル デバイス |
Directory API を使用すると、次の処理を実行できます。
|
| ユーザー名の変更 | すべてのサービスに反映されるまでに最長で 10 分ほどかかる場合があります。ユーザーの名前を変更する前に、ユーザーをすべてのブラウザ セッションとサービスからログアウトすることをおすすめします。詳しくは、ユーザーを更新するをご覧ください。 |
| 組織部門の作成/更新 |
|
| API 割り当てのカテゴリ | 割り当て |
Chrome デバイス annotatedLocation、最大文字数
|
デバイスの位置情報に入力できる最大文字数は 200 文字です。 |
Chrome デバイス notes、最大文字数
|
デバイスのメモ情報の最大文字数は 500 文字です。 |
Chrome デバイス、最大 user 文字
|
デバイスのユーザー名に入力できる最大文字数は 100 文字です。 |
| ドメイン エイリアス数（最大） | ドメイン エイリアスの最大数は 20 です。 |
| グループ、説明 | 説明文の最大文字数は 4,096 文字です。 |
| アカウントごとのグループ | 従来の無償版 G Suite アカウントでは、グループの数が 10 に制限されています。その他のエディションでは、グループの数に制限はありません。 |
| グループ、グループあたりのメンバー数 | 従来の無償版 G Suite アカウントの場合、グループには最大 100 人のメンバーを含めることができます。他のエディションでは、グループのメンバー数の上限はありません。 ユーザーあたりのグループ メンバー数の上限については、Google グループのポリシーと制限についてをご覧ください。 |
| maxResults クエリ文字列 | API は次のものを返します。
|
| 複数のドメイン、1 つのアカウントで許可されるドメインの最大数 | 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 では外部の受信者に一度に送信できるメールの数を制限しています。グループにメールを送信した場合、各外部メンバーが 1 人の受信者としてカウントされます。詳しくは、メール送信の制限と Gmail ユーザーへのメールがブロックされたり迷惑メール扱いされたりしないようにする をご覧ください。 |
| グループ、NDR メッセージの送信 | 「バウンスメッセージ」とも呼ばれる配信不能（NDR）メールをグループに送信または転送することはできません。 |
| ユーザーによって作成されたグループ、制限事項 | ユーザーが作成したグループの上限については、管理者向けヘルプセンターをご覧ください。 |
| 組織部門、サービスの有効/無効 | 管理コンソールを使用して、組織部門に対するサービスの有効 / 無効を管理できます。 |
| パスワード | 文字を組み合わせることができます。8 文字以上で入力してください。最大長は 100 文字です。 |
| フォト | このバージョンの API では、写真はユーザーの最新の Google プロフィール写真です。 |
| ユーザー名 | ユーザー名には英字（a ～ z）、数字（0 ～ 9）、ダッシュ（-）、アンダースコア（_）を使用できます。Google Workspace ではドットまたはピリオド（.）を認識します。これは Gmail とは異なります。ユーザー名には、等号（=）、角かっこ（<、>）、または複数のピリオド（.）を含めることはできません。詳しくは、管理者向けヘルプセンターをご覧ください。 |
| ユーザー名、名前の変更 | 名前を変更すると、記憶されているチャットの招待状はすべて破棄されます。ユーザーは、友だちとチャットする権限を再度リクエストする必要があります。以前のユーザー名は、メール転送設定の場合にメールが引き続き配信されるよう、メール エイリアスとして保持され、新しいユーザー名として使用できなくなります。ユーザー名の変更による影響に関する重要な詳細については、管理者向けヘルプセンターをご覧ください。名前を変更した後にメール エイリアスを削除するには、ユーザーのエイリアスを削除する操作を使用します。 |
| 複数のドメインのユーザー | Google Workspace アカウントには、どのドメインも含めることができます。複数ドメイン アカウントでは、1 つのドメインのユーザーは他のアカウント ドメインのユーザーとサービスを共有できます。複数のドメイン コンポーネントは次のとおりです。
|
| 警告、グループ メンバー | GROUP_CANNOT_CONTAIN_CYCLE – API は、グループ メンバーシップの循環を許可しません。たとえば、group1 が group2 のメンバーである場合、group2 を group1 のメンバーにすることはできません。 |