使用 JSON 批处理可将多个请求 (最多 20) 合并到单个 JSON 对象中来优化应用程序。 例如,客户端可能希望撰写不相关的数据的视图,例如:

  • 存储在 OneDrive 中的图像
  • 计划任务列表
  • 将三个单独请求合并到一个单独的批处理请求中可以使应用程序不受重大网络延迟的影响。

    Microsoft Graph 实现 $batch OData 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"
    

    对批处理的请求的响应可能会以不同的顺序显示。 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 对象组成: 请求requests 属性是单个请求的集合。 对于每个单独的请求,可以传递以下属性。

    必需项。 单个请求通常会发送到的相对资源 URL。 因此,尽管绝对 URL 为 https://graph.microsoft.com/v1.0/users,但此 URL 为 /users。 可选,但在指定 正文 时是必填的。 具有标头的键/值对的 JSON 对象。 例如,当需要 ConsistencyLevel 标头时,此属性将表示为 "headers": {"ConsistencyLevel": "eventual"}。 提供 正文 时,必须包含 Content-Type 标头。 可选。 可以是 JSON 对象或 base64 URL 编码的值,例如,当正文是图像时。 当请求中包含 正文 时,标头 对象必须包含 Content-Type 的值。

    JSON 批处理请求的响应格式类似于请求格式。 以下是主要区别:

  • 主 JSON 对象中的属性命名为 响应 而不是 请求
  • 单独响应可能会按与请求不同的顺序显示。
  • 单个响应具有 status 属性,而不是方法和urlstatus 的值是表示 HTTP 状态代码的数字。
  • 每个响应中的 headers 属性表示服务器返回的标头,例如 Cache-ControlContent-Type 标头。
  • 批处理响应中的状态代码通常为 200400。 如果批处理请求本身格式不正确,则状态代码为 400。 如果批处理请求可解析,则状态代码为 200。 批处理响应中的 200 状态代码并不表示批处理中的单独请求已成功。 这就是 responses 属性中的每个单个响应都有状态代码的原因。

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

    可以使用 dependsOn 属性以指定的顺序执行单个请求。 此属性是引用不同单个请求的 ID 的字符串数组。 因此, 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
  • 有关详细信息,请参阅 限制和批处理

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

    关于JSON批量请求/响应格式的更多信息,请参见OData JSON Format 4.01版规范 ,章节Batch Requests and Responses