制限と割り当ては、Directory API を不適切な方法で使用する自動プロセスから Google のインフラストラクチャを保護するための仕組みです。API からの過剰なリクエストは、無害な入力ミスが原因である場合もあれば、不要な API 呼び出しを行う非効率に設計されたシステムが原因である場合もあります。原因にかかわらず、特定の送信元からのトラフィックが一定のレベルに達したときにブロックすることは、Google Workspace システム全体の健全性を維持するために必要です。これにより、1 人のデベロッパーの行動がコミュニティ全体に悪影響を及ぼすことがなくなります。
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 は、最初はゼロとして定義され、その後単調に増加する整数です。n は、反復処理（リクエスト）のたびに 1 ずつ増えます。
このアルゴリズムは、n が 5 になると終了するように設定されています。この上限は、クライアントが無限に再試行を繰り返すことを防ぐためにのみ設定されています。総遅延時間が約 32 秒に達すると、リクエストは「修復不可能なエラー」と判断されます。API クライアントは、必要に応じて試行回数を増やすことができます。
API の上限と割り当て
| API の上限カテゴリ | 上限 |
|---|---|
| ユーザーの作成 | Directory API を使用して、ドメインごとに 1 秒あたり 10 人を超えるユーザーを作成することはできません。 |
| ユーザーの削除 | Directory API を使用して、ドメインごとに 1 秒あたり最大 5 人のユーザーを削除できます。これはドメインごとのバックエンド サービスの上限であり、Google Cloud コンソールのプロジェクト割り当てでは調整できません。バッチ リクエストを送信する際は、バッチ全体のオペレーション数が 1 秒あたり 5 秒間クエリ数（QPS）未満になるようにしてください。 |
| グループ メンバーの削除 | Directory API を使用すると、1 ドメインあたり 1 秒間に最大 30 人のグループ メンバーを削除できます。これはドメインごとのバックエンド サービスの上限であり、Google Cloud コンソールのプロジェクト割り当てでは調整できません。バッチ リクエストを送信する際は、バッチ全体のオペレーション数が 30 QPS（秒間クエリ数）未満になるようにしてください。 |
| グループが別のグループのメンバーとして追加されました | 子グループのメンバーが親グループのメンバーとして表示されるまでに、最大 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 は次の値を返します。
|
| 複数のドメイン、アカウントで許可されるドメインの最大数 | 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 では外部の受信者に一度に送信できるメールの数が制限されています。グループにメールを送信する場合、外部メンバーはそれぞれ 1 人の受信者としてカウントされます。詳しくは、メール送信制限と Gmail ユーザーへのメールがブロックまたは迷惑メール扱いされないようにするをご覧ください。 |
| グループ、NDR メッセージの送信 | グループに未配信レポート（NDR）（「バウンスメール」とも呼ばれます）を送信または転送することはできません。 |
| ユーザーが作成したグループ、制限 | ユーザーが作成したグループの上限については、管理ヘルプセンターをご覧ください。 |
| 組織部門、サービスの有効化 / 無効化 | Google 管理コンソールを使用して、組織部門のサービスの有効 / 無効を切り替えることができます。 |
| パスワード | 任意の文字の組み合わせを含めることができます。8 文字以上で入力してください。最大で 100 文字です。 |
| 写真 | このバージョンの API では、写真はユーザーの最新の Google プロフィール写真です。 |
| ユーザー名 | ユーザー名には、アルファベット（a ～ z）、数字（0 ～ 9）、ダッシュ（-）、アンダースコア（_）を使用できます。また、Google Workspace ではドットまたはピリオド（.）も認識されます。これは Gmail とは異なります。ユーザー名には、等号（=）、山かっこ（<、>）、連続した複数のピリオド（.）は使用できません。詳しくは、管理ヘルプセンターをご覧ください。 |
| ユーザー名、名前の変更 | Google ハングアウトでは、名前を変更すると、記憶されているチャットの招待がすべて破棄されます。ユーザーは、友だちとチャットするための権限を再度リクエストする必要があります。以前のユーザー名は、メール転送設定の場合にメールが継続的に配信されるように、メール エイリアスとして保持されます。新しいユーザー名としては使用できません。ユーザー名の変更による影響について詳しくは、管理者用ヘルプセンターをご覧ください。名前を変更した後にメール エイリアスを削除するには、ユーザーのエイリアスを削除するオペレーションを使用します。 |
| 複数のドメインにユーザーが存在する | Google Workspace アカウントには、任意のドメインを含めることができます。複数ドメイン アカウントでは、あるドメインのユーザーが、アカウント内の他のドメインのユーザーとサービスを共有できます。複数のドメイン コンポーネントは次のとおりです。
|
| 警告、グループ メンバー | GROUP_CANNOT_CONTAIN_CYCLE – API では、グループ メンバーシップの循環は許可されません。たとえば、group1 が group2 のメンバーである場合、group2 は group1 のメンバーになることはできません。 |