批处理请求

本文档介绍了如何对 API 调用进行批处理以减少 您需要建立的网络连接批处理可以减少网络往返次数并提高吞吐量，从而提高应用的效率。

概览

客户端建立的每个连接都会产生一定的开销。 Google 文档 API 支持批处理，这样您的客户端就可以放置多个 每个请求对象都指定一种要执行的请求 转换为单个批处理请求批量请求可以通过以下方式提升性能： 将多个子请求合并为对服务器的单个调用，从而检索 返回单个响应。

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

  • 您刚开始使用该 API，需要上传大量数据。
  • 您需要更新多个 对象的操作。
  • 您需要删除许多对象。

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

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

  • 每个批量请求（包括所有子请求）都计为一个 API 用量限额请求。
  • 一个批量请求需经过一次身份验证。此一次性身份验证会应用于请求中的所有批量更新对象。
  • 服务器会按照子请求在 批量请求。后面的子请求可能取决于 先前的子请求例如，在同一批量请求中，用户可以将文本插入现有文档，然后为其设置样式。

批量详情

一个批量请求包含一个 batchUpdate 方法调用 来处理多个子请求，例如添加文档以及设置文档格式。

每个请求都会经过验证，然后才能应用。批次中的所有子请求 update 以原子方式应用更新。也就是说，如果任何请求无效，则 整个更新都失败，并且没有任何（可能依赖的） 更改。

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

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

批量请求的格式

“请求”是指包含多个、 具有一个必需属性的嵌套子请求：requests。通过 请求都是在单个请求的数组中构造而成的。每个请求都使用 JSON，用于表示请求对象并包含其属性。

批量响应的格式

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

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

示例

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

请求

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

  • 插入“Hello World”置于现有文档的开头，并附上 1 的索引 location，使用 InsertTextRequest。

  • 使用 UpdateTextStyleRequest 更新“Hello”一词。startIndex 和 endIndex 用于定义 range 细分。

  • 使用 textStyle，将字体样式设置为 bold，将颜色设置为蓝色， “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_ID 和 REQUIRED_REVISION_ID 替换为 分别是写入请求的文档的标签页 ID 和修订版本 ID 。

响应

此示例批量响应显示了以下信息： 已应用该批量请求。既不是 InsertTextRequest 或 UpdateTextStyleRequest 包含响应，因此位于 [0] 和 [1] 处的数组的索引值由 大量空花括号。批量请求会显示 WriteControl 对象， 其中显示了请求的执行方式

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