批处理请求

本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的连接数。批处理可以减少网络往返次数和提高吞吐量,从而提高应用的效率。

概览

客户端建立的每个连接都会产生一定的开销。Google 幻灯片 API 支持批处理,这样您的客户可以在单个批处理请求中放置多个请求对象,每个对象指定一种要执行的请求类型。批量请求可以通过将多个子请求合并到对服务器的单个调用中并检索单个响应来提高性能。

我们建议用户始终一起批量处理多个请求。以下是一些可以使用批处理的情况示例:

  • 您刚开始使用 API,有大量数据需要上传。
  • 您需要更新多个对象的元数据或属性,例如格式设置。
  • 您需要删除许多对象。

限制、授权和依赖项注意事项

下面列出了采用批量更新时需要考虑的其他事项:

  • 每个批量请求(包括所有子请求)都会计为一个 API 请求,并计入您的用量限额
  • 批量请求通过身份验证一次。这一单一身份验证适用于请求中的所有批量更新对象。
  • 服务器会按照子请求在批量请求中出现的顺序,来处理这些子请求。后续子请求可能依赖于在较早的子请求期间执行的操作。例如,在同一批量请求中,用户可以将文本插入现有文档中,然后设置其样式。

批量详情

批量请求包含一个 batchUpdate 方法调用,其中包含多个子请求,例如添加演示文稿并为其设置格式。

每个请求在应用之前都会先进行验证。批量更新中的所有子请求均以原子方式应用。也就是说,如果任何请求无效,则整个更新都将失败,并且不会应用任何(可能相关的)更改。

某些请求会在响应中提供关于已应用请求的信息。例如,所有添加对象的批量更新请求都会返回响应,因此您可以访问新添加对象的元数据(例如 ID 或标题)。

通过这种方法,您可以使用一个包含多个子请求的 API 批量更新请求来构建整个 Google 文档。

批量请求的格式

请求是包含多个嵌套子请求的单个 JSON 请求,其中包含一个必需属性:requests。这些请求是在单个请求的数组中构建的。每个请求都使用 JSON 来表示请求对象并包含其属性。

批量响应的格式

批量请求的响应格式与请求格式类似。服务器的响应包含单个响应对象的完整回复。

主 JSON 对象的属性名为 replies。这些响应会以数组形式返回,其中对其中一个请求的每个响应将占用与相应请求相同的索引顺序。某些请求没有任何响应,并且该数组索引处的响应为空。

示例

以下代码示例展示了如何通过滑动 API 使用批处理。

请求

此示例批量请求演示了如何执行以下操作:

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

响应

此示例批量响应显示了有关如何应用批量请求中的每个子请求的信息。请注意,InsertTextRequest 方法不包含响应,因此 [2] 处数组的索引值由空大括号组成。批量请求会显示 WriteControl 属性,该属性会显示写入请求的执行方式。

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}