Microsoft Graph 調整ガイド

調整とは、リソースの使いすぎを防ぐために、サービスの同時呼び出し数を制限することをいいます。Microsoft Graph は、大量の要求を処理できるよう設計されています。過剰な数の要求が発生した場合、調整を行うことは Microsoft Graph サービスの最適なパフォーマンスと信頼性の維持に役立ちます。

制限の調整はシナリオによって異なります。たとえば、大量の書き込みを行う際には、読み込みのみを行う場合に比べて調整が起こる可能性は高くなります。

注意

Microsoft Graphから大量のデータを抽出する必要があるソリューションでは、Microsoft Graph REST API ではなく、Microsoft Graph Data Connect を使用する必要があります。 Microsoft Graph Data Connect を使用すると、組織は調整制限の対象になることなくMicrosoft 365データを一括で抽出できます。


調整が発生すると、何が起こるのでしょうか

調整のしきい値を超えた場合、Microsoft Graph はそのクライアントの以降の要求を一定時間制限します。調整が発生した場合、Microsoft Graph は HTTP ステータス コード 429 (Too Many Requests) を返し、要求は失敗します。失敗した要求の応答ヘッダーで、推奨される待機時間を返します。調整の動作は要求の種類と数によります。たとえば、大量の要求があれば、すべての種類の要求が調整されます。しきい値は要求の種類によって異なります。そのため、書き込みは調整を受けるが、読み込みはそのままで許容されるシナリオが起こりえます。

一般的な調整のシナリオ

クライアントに対して調整が発生する最も一般的な原因は次のとおりです。

  • あるテナントのすべてのアプリケーションから大量の要求がある。
  • すべてのテナントで、特定のアプリケーションから大量の要求がある。

応答のサンプル

調整しきい値を超えると、Microsoft Graph はこのような反応を返します。

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 10

{
  "error": {
    "code": "TooManyRequests",
    "innerError": {
      "code": "429",
      "date": "2020-08-18T12:51:51",
      "message": "Please retry after",
      "request-id": "94fb3b52-452a-4535-a601-69e0a90e3aa2",
      "status": "429"
    },
    "message": "Please retry again later."
  }
}

調整に対応するためのベスト プラクティス

調整に対応するためのベスト プラクティスには、次のようなものがあります。

  • 要求あたりの操作の数を減らす。
  • 呼び出しの頻度を減らす。
  • すべての要求が使用量の制限に計上されるため、即時の再試行を避ける。

エラー処理を実装する場合は、HTTP エラー コード 429 を使用して調整の発生を検出します。失敗した要求には、Retry-After 応答ヘッダーが含まれています。Microsoft Graph はクライアントが調整による制限を受けている間でもリソースの使用量を記録しています。そのため、Retry-After の指示に従って要求を遅延させることが最も迅速に調整を解消できる方法です。

  1. Retry-After ヘッダーに指定された秒数だけ待機してください。
  2. 要求を再試行してください。
  3. 要求が再度エラーコード 429 で失敗した場合は、依然として調整を受けています。推奨された Retry-After 遅延に引き続き従い、成功するまで再試行してください。

特に明記されていない限り、[サービス固有の制限] セクションで説明されているすべてのリソースと API が Retry-After ヘッダーを提供します。

Microsoft Cloud における調整についてのより幅広い議論については「調整パターン」を参照してください。

注意

応答によって Retry-After ヘッダーが提供されない場合は、指数バックオフ再試行ポリシーを実装することをお勧めします。 大規模アプリケーションを構築する場合は、 より高度なパターンを実装することもできます。

Microsoft Graph SDK は、Retry-After ヘッダーに依存するハハンドラー、または既定の指数バックオフ再試行ポリシーがすでに実装されています。

調整を回避するためのベスト プラクティス

リソースを継続的にポーリングして更新プログラムを確認したり、リソース コレクションを定期的にスキャンして新しいリソースや削除されたリソースをチェックしたりするなどのプログラミング パターンは、アプリケーションが調整され、全体的なパフォーマンスが低下する可能性が高くなります。代わりに、追跡の変更通知の変更を利用する必要があります。

注意

ファイルの探索とスケールでの変更の検出に関するベストプラクティスでは、ベスト プラクティスについて詳しく説明しています。

調整とバッチ処理

JSON のバッチ処理を使用すると、複数の要求を単一の JSON オブジェクトに統合することにより、アプリケーションを最適化することができます。 バッチ内の要求は、調整した制限に対して個別に評価されます。また、要求が制限を超えると、429statusで失敗し、上記のようなエラーが表示されます。 バッチ自体は、424の状態コードで失敗します (依存エラー)。 1 つのバッチ内で複数の要求を調整できます。 JSON コンテンツから、 retry-after 応答ヘッダーに準備された値を使用して、失敗したバッチの要求を順番に再実行する必要があります。 最長のretry-after値が出た後は、新しいバッチで失敗した要求をすべて再試行します。

SDK がバッチ処理されていないときに調整した要求を自動的に再試行した場合、バッチ処理の一部であった調整された要求は自動的に再試行されません。

次の手順

各 Microsoft Graph リソースに適用される [制限の調整] を特定します。