Microsoft Graph 調整ガイド
調整とは、リソースの使いすぎを防ぐために、サービスの同時呼び出し数を制限することをいいます。 Microsoft Graph サービスでは、サービスの可用性と信頼性を確保するために調整制限が実装されています。
制限の調整はシナリオによって異なります。 たとえば、大量の書き込みを実行している場合、読み取りのみを実行している場合よりも調整の可能性が高くなります。
注:
Microsoft Graphから大量のデータを抽出する必要があるソリューションでは、Microsoft Graph REST API ではなく、Microsoft Graph Data Connect を使用する必要があります。 Microsoft Graph Data Connect を使用すると、組織は調整制限の対象になることなくMicrosoft 365データを一括で抽出できます。
調整が発生すると、何が起こるのでしょうか
調整のしきい値を超えると、Microsoft Graph は次の手順を実行します。
- そのクライアント アプリからのそれ以上の要求を一定期間制限します。
- HTTP 状態コード 429 要求が多すぎると要求 が失敗します。
- 失敗した要求の応答ヘッダーで推奨される待機時間を返します。
調整動作は、要求の種類と数によって異なります。 たとえば、要求の量が多い場合、すべての要求の種類が調整されます。 しきい値の制限は、要求の種類によって異なります。 そのため、書き込みが調整されるが、読み取りがまだ許可されているシナリオが発生する可能性があります。
一般的な調整のシナリオ
クライアントに対して調整が発生する最も一般的な原因は次のとおりです。
- あるテナントのすべてのアプリケーションから大量の要求がある。
- すべてのテナントで、特定のアプリケーションから大量の要求がある。
応答のサンプル
調整しきい値を超えると、Microsoft Graph はこのような反応を返します。
HTTP/1.1 429 Too Many Requests
Content-Length: 312
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 遅延を使用して要求をバックオフすることが、調整から復旧する最も速い方法です。
-
Retry-Afterヘッダーに指定された秒数だけ待機してください。 - 要求を再試行してください。
- 要求が 429 エラー コードで再び失敗した場合、引き続き調整されます。 推奨される
Retry-After遅延を引き続き使用し、成功するまで要求を再試行します。
サービス固有の制限で説明されているすべてのリソースと API は、示されている場合を除き、Retry-After ヘッダーを提供します。
Microsoft Cloud における調整についてのより幅広い議論については「調整パターン」を参照してください。
注:
応答によって Retry-After ヘッダーが提供されない場合は、指数バックオフ再試行ポリシーを実装することをお勧めします。 大規模アプリケーションを構築する場合は、 より高度なパターンを実装することもできます。
Microsoft Graph SDK は、Retry-After ヘッダーに依存するハハンドラー、または既定の指数バックオフ再試行ポリシーがすでに実装されています。
調整を回避するためのベスト プラクティス
リソースを継続的にポーリングして更新を確認したり、リソース コレクションを定期的にスキャンして新規または削除されたリソースを確認したりするようなプログラミング パターンは、アプリケーションが抑制され、全体的なパフォーマンスが低下する可能性が高くなります。 代わりに、 変更追跡 と 変更通知 ( 使用可能な場合) を使用する必要があります。
注:
ファイルの探索とスケールでの変更の検出に関するベストプラクティスでは、ベスト プラクティスについて詳しく説明しています。
調整とバッチ処理
JSON のバッチ処理を使用すると、複数の要求を単一の JSON オブジェクトに統合することにより、アプリケーションを最適化することができます。 バッチ内の要求は調整制限に対して個別に評価され、要求が制限を超えると、 429 の状態コードと 、前のサンプル応答のようなエラーで失敗します。 バッチ自体は、 200 (OK) の状態コードで成功します。 1 つのバッチで複数の要求を調整できます。 JSON コンテンツから、 retry-after 応答ヘッダーに準備された値を使用して、失敗したバッチの要求を順番に再実行する必要があります。 最長のretry-after値が出た後は、新しいバッチで失敗した要求をすべて再試行します。
SDK がバッチ処理されていないときに調整された要求を自動的に再試行する場合、バッチの一部であった調整された要求は自動的に再試行されません。