使用 JSON 批处理在一个 HTTP 调用中合并多个请求Combine multiple requests in one HTTP call using JSON batching

JSON 批处理使你能够通过将多个请求合并为一个单一的 JSON 对象优化应用程序。例如,客户可能希望撰写一个无关的数据视图,例如:JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. For example, a client might want to compose a view of unrelated data such as:

  1. 存储在 OneDrive 中的图像An image stored in OneDrive
  2. 计划任务列表A list of Planner tasks
  3. 组日历The calendar for a group

将三个单独请求合并到一个单独的批处理请求中可以使应用程序不受重大网络延迟的影响。Combining these three individual requests into a single batch request can save the application significant network latency.

第一个 JSON 批处理请求First JSON batch request

首先,为之前的示例构建 JSON 批处理请求。在这种情况下,单个请求不会以任何方式互相依赖,因此可以按任意顺序放入批处理请求中。First you construct the JSON batch request for the previous example. In this scenario, the individual requests are not interdependent in any way and therefore can be placed into the batch request in any order.

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 属性可用于关联各个请求和响应。Responses to the batched requests might appear in a different order. The id property can be used to correlate individual requests and responses.

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": "2",
      "status": 200,
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
        "value": []
      }
    },
    {
      "id": "4",
      "status": 204,
      "body": null
    }
  ]
}

请求格式Request format

批处理请求始终使用 POST 发送到 /$batch 终结点。Batch requests are always sent using POST to the /$batch endpoint.

JSON 批处理请求正文包含具有一个必需的属性 requests 的单个 JSON 对象。requests 属性是一组单独请求。对于每个单独请求而言, idmethodurl 属性是必需的。A JSON batch request body consists of a single JSON object with one required property: requests. The requests property is an array of individual requests. For each individual request, the id, method, and url properties are required.

id 属性主要用作关联单个响应和请求的相关值。这使服务器可以最高效的顺序处理批处理中的请求。The id property functions primarily as a correlation value to associate individual responses with requests. This allows the server to process requests in the batch in the most efficient order.

methodurl 正是你在任何给定的 HTTP 请求开头看到的属性。该方法是 HTTP 方法,且 URL 是通常会向其发送单独请求的资源 URL。The method and url properties are exactly what you would see at the start of any given HTTP request. The method is the HTTP method, and the URL is the resource URL the individual request would typically be sent to.

单独请求还可以视需要包含 headers 属性和 body 属性。Individual requests can optionally also contain a headers property and a body property. 这两种属性通常都是 JSON 对象,如上一示例所示。Both of these properties are typically JSON objects, as shown in the previous example. 在某些情况下,body 可能是经过 base64 URL 编码的值,而不是 JSON 对象(例如,当正文为图像时)。In some cases, the body might be a base64 URL-encoded value rather than a JSON object - for example, when the body is an image. 如果 body 包含在该请求中,headers 对象必须包含 Content-Type 的值。When a body is included with the request, the headers object must contain a value for Content-Type.

响应格式Response format

JSON 批处理请求的响应格式与请求格式类似。主要区别如下:The response format for JSON batch requests is similar to the request format. The following are the key differences:

  • 主 JSON 对象的中属性被命名为 responses,与 requests 相反。The property in the main JSON object is named responses as opposed to requests.
  • 单独响应可能会按与请求不同的顺序显示。Individual responses might appear in a different order than the requests.
  • 单独响应包含的是 status 属性,而不是 methodurl 属性。status 的值是表示 HTTP 状态代码的数字。Rather than method and url, individual responses have a status property. The value of status is a number that represents the HTTP status code.

批处理响应中的状态代码通常为 200400。如果批处理请求本身格式不正确,则状态代码为 400。如果批处理请求可分析,则状态代码为 200。批处理响应中的 200 状态代码并不表示批处理中的单独请求已成功。这就是为什么 responses 属性中的每个单独响应都有状态代码。The status code on a batch response is typically 200 or 400. If the batch request itself is malformed, the status code is 400. If the batch request is parseable, the status code is 200. A 200 status code on the batch response does not indicate that the individual requests inside the batch succeeded. This is why each individual response in the responses property has a status code.

使用 dependsOn 属性对请求进行排序Sequencing requests with the dependsOn property

通过使用 dependsOn 属性可按指定顺序执行单独请求。此属性是引用不同的单独请求的 id 的字符串数组。出于这个原因,id 的值必须唯一。例如,在下面的请求中,客户端指定请求 1 和 3 应该先运行,然后是请求 2,然后是请求 4。Individual requests can be executed in a specified order by using the dependsOn property. This property is an array of strings that reference the id of a different individual request. For this reason, the values for id must be unique. For example, in the following request, the client is specifying that requests 1 and 3 should be run first, then request 2, then request 4.

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "..."
    },
    {
      "id": "2",
      "dependsOn": [ "1" ],
      "method": "GET",
      "url": "..."
    },
    {
      "id": "3",
      "method": "GET",
      "url": "..."
    },
    {
      "id": "4",
      "dependsOn": [ "2" ],
      "method": "GET",
      "url": "..."
    }
  ]
}

如果单独请求失败,任何依赖此请求的请求都会失败,且状态代码为 424(依赖项失败)。If an individual request fails, any request that depends on that request fails with status code 424 (Failed Dependency).

使用批处理绕过 URL 长度限制Bypassing URL length limitations with batching

JSON 批处理的其他用例是绕过 URL 长度限制。如果筛选子句太复杂,URL 长度可能会超越浏览器或其他 HTTP 客户端中内置的限制。你可以使用 JSON 批处理作为运行这些请求的解决方法,因为长 URL 只能成为请求有效负载的一部分。An additional use case for JSON batching is to bypass URL length limitations. In cases where the filter clause is complex, the URL length might surpass limitations built into browsers or other HTTP clients. You can use JSON batching as a workaround for running these requests because the lengthy URL simply becomes part of the request payload.

已知问题Known issues

有关与批处理相关的当前限制列表,请参阅已知问题For a list of current limitations related to batching, see known issues.

另请参阅See also

关于JSON批量请求/响应格式的更多信息,请参见 OData JSON Format 4.01版规范 ,章节 Batch Requests and ResponsesFor more information about the JSON batch request/response format, see the OData JSON Format Version 4.01 specification, section Batch Requests and Responses.