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 (要求が多すぎます) を返し、要求は失敗します。 推奨される待機時間は、失敗した要求の応答ヘッダーに返されます。 調整動作は、要求の種類と数によって異なります。 たとえば、要求の量が多い場合、すべての要求の種類が調整されます。 しきい値の制限は、要求の種類によって異なります。 そのため、書き込みが調整されるが、読み取りがまだ許可されているシナリオが発生する可能性があります。
一般的な調整のシナリオ
クライアントに対して調整が発生する最も一般的な原因は次のとおりです。
- あるテナントのすべてのアプリケーションから大量の要求がある。
- すべてのテナントで、特定のアプリケーションから大量の要求がある。
応答のサンプル
調整しきい値を超えると、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 含まれます。 遅延を使用した要求の Retry-After バックオフは、クライアントの調整中に Microsoft Graph が引き続きリソースの使用状況をログに記録するため、調整から復旧する最も速い方法です。
-
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 がバッチ処理されていないときに調整した要求を自動的に再試行した場合、バッチ処理の一部であった調整された要求は自動的に再試行されません。