上限と割り当てを設定すると、Directory API を不適切な方法で使用する自動プロセスから Google インフラストラクチャを保護できます。API からの過剰なリクエストとしては、入力ミスがないのが問題です。また、非効率な設計のシステムで、不必要な API 呼び出しが行われることもあります。原因にかかわらず、特定のソースからのトラフィックが一定のレベルに達したら、Google Workspace システム全体の健全性を保つために、そのようなトラフィックをブロックする必要があります。これにより、あるデベロッパーの操作によってコミュニティに悪影響が及ぶ事態を防ぐことができます。
万一、API リクエストが失敗した場合、API は HTTP ステータス コードとエラーの理由を返します。また、レスポンス本文にエラーの原因についての詳しい説明が記述されます。
以下に、割り当ての上限に達したことが原因で発生する可能性のあるエラーコード、理由、対応する説明、推奨される対応策を示します。
| コード | Reason | 説明 | 推奨される対応 |
|---|---|---|---|
| 403 | userRateLimitExceeded | ユーザー レートの上限を超えていることを示します。Google Developers Console に設定されたデフォルト値は、IP アドレスごとに 100 秒あたり 3,000 クエリです。この上限は Google Developers Console で増やすことができます。 | Google Developers Console でユーザーごとの上限を引き上げるか、指数バックオフを使用してリクエストを送信する速度を遅くします。 |
| 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 分ほどかかることがあります。この上限は、システムの容量によって変わる可能性があります。 |
| ユーザー名の変更 | すべてのサービスに反映されるまでに最大 10 分かかります。ユーザー名を変更する前に、ユーザーをブラウザのすべてのセッションやサービスからログアウトさせることをおすすめします。詳しくは、ユーザーを更新するをご覧ください。 |
| 組織部門の作成/更新 |
|
| API 割り当てカテゴリ | 割り当て |
Chrome デバイス annotatedLocation、最大文字数 |
デバイスの位置情報の最大文字数は 200 文字です。 |
Chrome デバイス notes、最大文字数 |
デバイスのメモ情報の最大文字数は 500 文字です。 |
Chrome デバイス、最大 user 文字 |
デバイス ユーザー名の最大文字数は 100 文字です。 |
| ドメイン エイリアス（上限） | ドメイン エイリアスの最大数は 20 です。 |
| グループ、説明 | 説明の最大文字数は 4,096 文字です。 |
| アカウント（グループ単位） | 従来の無償版 G Suite アカウントをご利用の場合、グループの数は 10 に制限されています。他のエディションの場合、グループの数に制限はありません。 |
| グループ、グループごとのメンバー | 従来の無償版 G Suite アカウントの場合、1 つのグループに最大 100 人のメンバーを含めることができます。他のエディションでは、グループに含まれるメンバーの数に制限はありません。 ユーザーごとのグループ メンバーシップの制限については、Google グループのポリシーと制限をご参照ください |
| 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 にメールアドレスの変更が自動的に反映されます。 |
| グループ、設定 | グループのアクセス設定、共有オプション、モニタリング、ディスカッション アーカイブは管理コンソールを使用して管理します。グループの設定について詳しくは、管理者向けヘルプセンターをご覧ください。 |
| グループ、メッセージの送信 | 迷惑メールやメールの不正使用を防止するため、一度に外部の宛先に送信できるメールの数が制限されています。グループにメッセージを送信する場合、各外部メンバーは 1 人の受信者としてカウントされます。詳しくは、メールの送信制限と Gmail ユーザーへのメールがブロックまたは迷惑メール扱いされないようにするをご覧ください。 |
| グループ、NDR メッセージの送信 | 配信されなかった領収書（NDR）をグループに送信したり転送したりすることはできません。 |
| ユーザーが作成したグループ、制限事項 | ユーザーが作成したグループの上限については、管理者向けヘルプセンターをご覧ください |
| 組織部門、サービスの有効化/無効化 | 管理コンソールを使用して、組織部門のサービスを有効または無効にすることができます。 |
| パスワード | 任意の組み合わせの文字を含めることができます。8 文字以上で入力してください。最大長は 100 文字です。 |
| 写真 | このバージョンの API では、写真とは、Gmail のチャット機能で使用するユーザーの最新のプロフィール写真です。これは Google のプロフィール写真とは異なります。 |
| ユーザー名 | ユーザー名には文字（a ～ z）、数字（0 ～ 9）、ダッシュ（-）、アンダースコア（_）を使用できます。Google Workspace ではドットまたはピリオド（.）が認識されます。これは Gmail とは異なります。ユーザー名には、等号（=）、山かっこ（<、>）、連続した複数のピリオド（.）を含めることはできません。詳しくは、管理者向けヘルプセンターをご覧ください。 |
| ユーザー名、名前の変更 | 名前を変更すると、Google ハングアウトは記憶したチャットの招待状をすべて破棄します。ユーザーは、友だちともう一度チャットする権限をリクエストする必要があります。メールの転送設定がある場合に配信を継続できるように、以前のユーザー名はメール エイリアスとして保持され、新しいユーザー名として使用することはできません。ユーザー名を変更した場合の影響に関する重要な詳細については、管理者向けヘルプセンターをご覧ください。名前の変更後にメール エイリアスを削除するには、ユーザーのエイリアスを削除する操作を使用します。 |
| 複数のドメインのユーザー | Google Workspace アカウントには、どのドメインでも含めることができます。複数のドメイン アカウントの場合、1 つのドメインのユーザーは他のアカウント ドメインのユーザーとサービスを共有できます。複数のドメイン コンポーネントは次のとおりです。
|
| 警告、グループ メンバー | GROUP_FAILED_CONTAIN_CYCLE – API は、グループ メンバーシップのサイクルを許可しません。たとえば、group1 が group2 のメンバーの場合、group2 を group1 のメンバーにすることはできません。 |