使用 JSON 批处理合并多个 HTTP 请求

项目
02/14/2024

使用 JSON 批处理可将多个请求 (最多 20) 合并到单个 JSON 对象中来优化应用程序。

请考虑一个客户端，该客户端希望撰写以下不相关数据的视图：

存储在 OneDrive 中的图像
计划任务列表
组日历

将三个单独请求合并到一个单独的批处理请求中可以使应用程序不受重大网络延迟的影响。

Microsoft Graph 实现 $batchOData URL 路径段以支持 JSON 批处理。

示例 - 第一个 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 批处理请求正文由具有一个必需属性的单个 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 对象中的属性命名为响应而不是请求。
单独响应可能会按与请求不同的顺序显示。
单个响应具有 status 属性，而不是方法和url。 status 的值是 HTTP 状态代码。
每个响应中的 headers 属性表示服务器返回的标头，例如 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（依赖项失败）。

提示

批处理应是完全有序的或完全并行的。

使用批处理绕过 URL 长度限制

JSON 批处理的另一个用例是绕过 URL 长度限制。如果 filter 子句很复杂，URL 长度可能会超过浏览器或其他 HTTP 客户端内置的限制。可以使用 JSON 批处理作为运行这些请求的解决方法，因为冗长的 URL 只是请求有效负载的一部分。

批大小限制

JSON 批处理请求目前限定为 20 个单独请求。
根据批处理请求的 API，基础服务会施加自己的限制，这些限制会影响使用 Microsoft Graph 访问它们的应用程序。
将针对适用的限制单独评估批处理中的请求，如果任何请求超出限制，则失败，状态 429为。

有关详细信息，请参阅限制和批处理。

已知问题

有关与批处理相关的当前限制列表，请参阅已知问题。

使用 Microsoft Graph SDK 批处理请求

使用 JSON 批处理合并多个 HTTP 请求

示例 - 第一个 JSON 批处理请求

批处理请求格式的说明

示例 - 第一个 JSON 批处理响应

批处理响应格式的说明

使用 dependsOn 属性对请求进行排序

使用批处理绕过 URL 长度限制

批大小限制

已知问题

反馈

反馈

其他资源

使用 JSON 批处理合并多个 HTTP 请求

示例 - 第一个 JSON 批处理请求

批处理请求格式的说明

示例 - 第一个 JSON 批处理响应

批处理响应格式的说明

使用 dependsOn 属性对请求进行排序

使用批处理绕过 URL 长度限制

批大小限制

已知问题

相关内容

反馈

反馈

其他资源