JSON バッチ処理を使用して複数の HTTP 要求を結合する

  • [アーティクル]

JSON バッチ処理を使用すると、複数の要求 (最大 20 個) を 1 つの JSON オブジェクトに結合することで、アプリケーションを最適化できます。

次の無関係なデータのビューを作成するクライアントを考えてみましょう。

  • OneDrive に保存されているイメージ
  • Planner タスクのリスト
  • グループの予定表

これらの 3 つの要求を 1 つのバッチ要求にまとめることで、ネットワーク待機時間を大きく削減できます。

Microsoft Graph では、JSON バッチ処理を$batchサポートするために OData 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を参照してください。

既知の問題

バッチ処理に関連する現在の制限事項の一覧は「既知の問題」を参照してください。

関連コンテンツ