批处理请求

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

概览

客户端建立的每个连接都会产生一定的开销。 Google 文档 API 支持批处理,这样您的客户端就可以将多个请求对象(每个对象指定一种要执行的请求)放入单个批量请求中。批量请求可以将多个子请求合并为对服务器的单次调用,从而检索单个响应,从而提升性能。

我们建议用户始终将多个请求一起进行批处理。以下是使用批处理的一些示例:

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

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

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

  • 每个批量请求(包括所有子请求)都将计为 1 次 API 请求,计入您的用量限额
  • 系统会对批量请求进行一次身份验证。此一次性身份验证会应用于请求中的所有批量更新对象。
  • 服务器会按子请求在批量请求中的显示顺序处理这些子请求。后面的子请求可以依赖于在较早的子请求期间执行的操作。例如,在同一批量请求中,用户可以将文本插入现有文档,然后设置其样式。

批量详情

批量请求包含一个 batchUpdate 方法调用,该调用包含多个子请求,例如添加文档、设置文档格式。

每个请求都会经过验证,然后才能应用。批量更新中的所有子请求均以原子方式应用。也就是说,如果任何请求无效,则整个更新都将失败,并且系统不会应用任何(可能依赖的)更改。

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

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

批量请求的格式

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

批量响应的格式

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

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

示例

以下代码示例显示了如何将批量处理与 Google 文档 API 配合使用。

请求

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

  • 使用 InsertTextRequest 将“Hello World”文本插入现有文档的开头(索引 location1)。

  • 使用 UpdateTextStyleRequest 更新“Hello”一词。startIndexendIndex 用于定义相应段落中设置了格式的文本的 range

  • 使用 textStyle,仅将“Hello”一词的字体样式设为粗体,并将其颜色设为蓝色。

  • 您可以使用 WriteControl 字段来控制写入请求的执行方式。如需了解详情,请参阅使用 WriteControl 建立状态一致性

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

TAB_IDREQUIRED_REVISION_ID 分别替换为写入请求所应用到的文档的标签页 ID 和修订版本 ID。

响应

此示例批量响应显示了如何应用批量请求中的每个子请求的信息。InsertTextRequestUpdateTextStyleRequest 均不包含响应,因此数组 [0] 和 [1] 的索引值由空大括号组成。批量请求会显示 WriteControl 对象,该对象会显示请求的执行方式。

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}