JSON バッチ処理を使用した複数要求の単一 HTTP 呼び出しへの統合

JSON のバッチ処理を使用すると、複数 (最大 20 件) の要求を単一の 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"
      }
    }
  ]
}

バッチ要求への応答は、異なる順序で返されることがあります。id プロパティを使い、各要求と応答を対応させることができます。

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": {
        "OData-Version": "4.0",
      },
      "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
    }
  ]
}

要求の形式

バッチ要求は常に POST を使用して /$batch エンドポイントに送信されます。

JSON バッチ要求本文は必須のプロパティ 要求 をもつ単一の JSON オブジェクトです。要求 プロパティは個別要求の配列です。各個別要求には、それぞれ、以下のプロパティーを渡すことができます。

プロパティ 説明
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 バッチ要求への応答の形式は、要求の形式と似ています。主な違いを以下に示します。

  • メイン JSON オブジェクトのプロパティには、要求 ではなく、応答 と命名されています。
  • 個々の応答は、要求と異なる順序で返されることがある。
  • メソッドURL ではなく、個々の応答には 状態 プロパティがあります。状態 の値は、HTTP 状態コードを表す数値です。
  • 個々の応答の ヘッダー プロパティは、サーバーによって返されるヘッダーを表します。 たとえば、Cache-Control および Content-Type ヘッダーなどです。

バッチ応答のステータス コードは、通常 200 または 400 です。バッチ要求自体が正しい形式でない場合、状態コードは 400 になります。バッチ要求が解析可能であれば、状態コードは 200 になります。バッチ応答のステータス コード 200 はバッチ内の個々の要求が成功したことを示すものではありません。そのため、 応答 プロパティの個々の応答に状態 コードがあります。

dependsOn プロパティによる要求の順序指定

dependsOn プロパティを使い、個別の要求の実行順序を指定できます。このプロパティは個別の要求の id を参照する文字列の配列です。このため、id の値は一意である必要があります。たとえば、次の要求で、クライアントは、要求 1、次に要求3、それから要求 2 その後に要求 4 の順に実行するよう指定しています。

{
  "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 長さ制限の回避

他にも、URL の長さの制限を回避するために JSON バッチ処理を利用できます。フィルター句が複雑な場合、URL の長さがブラウザーまたはその他の HTTP クライアントによる制限を超えることがあります。JSON バッチ処理を使うと、長い URL は単純に要求のペイロードとなるため、制限を回避できます。

バッチ サイズの制限

現在、JSON バッチ要求は、次の制限に加えて、20 個の個々の要求に制限されています:

  • バッチ要求の 一部であるAPI 部分に応じて、基盤となるサービスは、Microsoft Graph を使用してそれらにアクセスするアプリケーションに影響を与える独自の調整制限を適用します。
  • バッチ内の要求は調整制限に対して個別に評価され、いずれかの要求が制限を超えた場合、 429状態で失敗します。
  • Outlook リソース (メール/カレンダーなど) を対象とするバッチには、同じメールボックスを対象とする要求を 4 つだけ含めることができます。 詳細についてはOutlook サービスの制限を参照してください。

詳細についてはThrottling and batchingを参照してください。

既知の問題

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

関連項目

JSON のバッチ要求/応答形式の詳細については「OData JSON 形式バージョン 4.01 仕様」のセクション「バッチ要求と応答」を参照してください。