JSON バッチ処理を使用して複数の HTTP 要求を結合する
JSON バッチ処理を使用すると、複数の要求 (最大 20 個) を 1 つの JSON オブジェクトに結合することで、アプリケーションを最適化できます。
次の無関係なデータのビューを作成するクライアントを考えてみましょう。
- OneDrive に保存されているイメージ
- Planner タスクのリスト
- グループの予定表
これらの 3 つの要求を 1 つのバッチ要求にまとめることで、ネットワーク待機時間を大きく削減できます。
Microsoft Graph では、JSON バッチ処理をサポートするために、 $batchOData URL パス セグメント が実装されています。
例 - 最初の JSON バッチ要求
まず、シナリオ例の JSON バッチ要求を作成します。 このシナリオでは、個々の要求は相互に依存しないため、任意の順序でバッチ要求に配置できます。
POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/me/drive/root:/{file}:/content"
},
{
"id": "2",
"method": "GET",
"url": "/me/planner/tasks"
},
{
"id": "3",
"method": "GET",
"url": "/groups/{id}/events"
},
{
"id": "4",
"url": "/me",
"method": "PATCH",
"body": {
"city" : "Redmond"
},
"headers": {
"Content-Type": "application/json"
}
},
{
"id": "5",
"url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
"method": "GET",
"headers": {
"ConsistencyLevel": "eventual"
}
}
]
}
バッチ要求形式の説明
バッチ要求は常に POST を使用して /$batch エンドポイントに送信されます。
JSON バッチ要求本文は、要求という 1 つの必須プロパティを持つ 1 つの JSON オブジェクトで構成 されます。 requests プロパティは、個々の要求のコレクションです。 個々の要求ごとに、次のプロパティを渡すことができます。
| プロパティ | 説明 |
|---|---|
| id | 必須。 文字列。 個々の応答を要求に関連付ける相関値。 この値を使用すると、サーバーはバッチ内の要求を最も効率的な順序で処理できます。 大文字と小文字は区別されません。 バッチ内で一意である必要があります。 |
| メソッド | 必須です。 HTTP メソッド。 |
| url | 必須です。 個々の要求の相対リソース URL。 したがって、絶対 URL はhttps://graph.microsoft.com/v1.0/usersであるのに対し、この URL は/usersです。 |
| ヘッダー | オプションですが、 本文 を指定した場合は必須です。 ヘッダーのキーと値のペアを持つ JSON オブジェクト。 たとえば、 ConsistencyLevel ヘッダーが必要な場合、このプロパティは "headers": {"ConsistencyLevel": "eventual"}として表されます。
本文 を指定する場合は、 Content-Type ヘッダーを含める必要があります。 |
| body | 省略可能。 JSON オブジェクトまたは base64 URL でエンコードされた値 (本文がイメージの場合など) の場合があります。 本文 が要求に含まれている場合、ヘッダー オブジェクトには、Content-Type の値を含める必要があります。 |
例 - 最初の JSON バッチ応答
バッチ要求への応答は、異なる順序で返されることがあります。 id プロパティを使用して、個々の要求と応答を関連付けることができます。
HTTP/1.1 200 OK
Content-Type: application/json
{
"responses": [
{
"id": "1",
"status": 302,
"headers": {
"location": "https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi"
}
},
{
"id": "3",
"status": 401,
"body": {
"error": {
"code": "Forbidden",
"message": "..."
}
}
},
{
"id": "5",
"status": 200,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"OData-Version": "4.0",
"Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
},
"body": {
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,userPrincipalName)",
"@odata.count": 12,
"value": [
{
"id": "071cc716-8147-4397-a5ba-b2105951cc0b",
"displayName": "Adele Vance",
"userPrincipalName": "AdeleV@Contoso.com"
}
]
}
},
{
"id": "2",
"status": 200,
"body": {
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
"value": []
}
},
{
"id": "4",
"status": 204,
"body": null
}
]
}
バッチ応答形式の説明
JSON バッチ要求の応答形式は、次のように要求形式とは異なります。
- メイン JSON オブジェクトのプロパティには、要求 ではなく、応答 と命名されています。
- 個々の応答は、要求と異なる順序で返されることがある。
- 個々の応答には、 メソッド と URL ではなく status プロパティがあります。 status の値は HTTP 状態コードです。
- 個々の応答の ヘッダー プロパティは、サーバーによって返されるヘッダーを表します。 たとえば、Cache-Control および Content-Type ヘッダーなどです。
バッチ応答の状態コードは、通常 200 または 400 です。 バッチ要求自体が正しい形式でない場合、状態コードは 400 になります。 バッチ要求が解析可能であれば、状態コードは 200 になります。 バッチ応答ヘッダーの 200 状態コードは、バッチ内の個々の要求が成功したことを示すわけではありません。 これが、 responses プロパティの個々の応答に状態コードがある理由です。
dependsOn プロパティによる要求の順序指定
dependsOn プロパティを使用して、指定した順序で実行するバッチ内の要求を指定できます。 このプロパティは、異なる個々の要求の ID を 参照する文字列の配列です。 たとえば、次の要求では、クライアントは、要求を注文要求 1 で実行し、要求 2、要求 4、要求 3 で実行する必要があることを指定しています。
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "..."
},
{
"id": "2",
"dependsOn": [ "1" ],
"method": "GET",
"url": "..."
},
{
"id": "4",
"dependsOn": [ "2" ],
"method": "GET",
"url": "..."
},
{
"id": "3",
"dependsOn": [ "4" ],
"method": "GET",
"url": "..."
}
]
}
個々の要求が失敗した場合、その要求に依存するすべての要求が失敗し、ステータス コードは 424 (Failed Dependency) になります。
ヒント
バッチは、完全シーケンシャルまたは完全パラレルである必要があります。
バッチ処理による URL 長さ制限の回避
JSON バッチ処理のもう 1 つのユース ケースは、URL の長さの制限をバイパスすることです。 フィルター句が複雑な場合、URL の長さは、ブラウザーやその他の HTTP クライアントに組み込まれている制限を超える可能性があります。 長い URL は単に要求ペイロードの一部になるため、これらの要求を実行するための回避策として JSON バッチ処理を使用できます。
バッチ サイズの制限
- 現段階では、JSON バッチ要求は 20 個までの個別要求に限られています。
- バッチ要求の一部である API に応じて、 基になるサービス は、Microsoft Graph を使用してそれらにアクセスするアプリケーションに影響を与える独自の調整制限を課します。
- バッチ内の要求は、該当する調整制限に対して個別に評価され、要求が制限を超えると、
429の状態で失敗します。
詳細についてはThrottling and batchingを参照してください。
既知の問題
バッチ処理に関連する現在の制限事項の一覧は「既知の問題」を参照してください。