本文档介绍了如何一起批量处理 API 调用，以减少客户端必须建立的连接数。批处理可以通过减少网络往返并提高吞吐量来提高应用的效率。
概览
客户端建立的每个连接都会产生一定的开销。Google 文档 API 支持批处理，这样您的客户端就可以将多个请求对象放入一个批量请求，每个请求对象指定要执行的单一请求类型。批量请求可以通过将多个子请求合并到对服务器的单次调用并检索单个响应来提升性能。
我们鼓励用户始终将多个请求一起处理。下面是一些可以使用批处理的情况示例：
- 您刚开始使用该 API，并且有大量数据需要上传。
- 您需要更新多个对象的元数据或属性，例如格式。
- 您需要删除多个对象。
限制、授权和依赖项注意事项
下面列出了使用批量更新时需要考虑的其他事项：
- 每个批量请求（包括所有子请求）都将计为一个用量限额 API 请求。
- 批量请求通过一次身份验证。这种单一身份验证适用于请求中的所有批量更新对象。
- 服务器会按照其在批量请求中出现的顺序来处理子请求。后续子请求可能取决于前面的子请求期间执行的操作。例如，在同一批量请求中，用户可以将文本插入现有文档，然后设置其样式。
批量详情
批处理请求包含一个 batchUpdate 方法调用和多个子请求，例如添加和设置文档格式。
系统会在应用之前验证每个请求。批量更新中的所有子请求均以原子方式应用。也就是说，如果任何请求无效，则整个更新不会成功，也不会应用任何（可能相关的）更改。
某些请求会提供响应，其中包含已应用请求的相关信息。例如，所有添加对象的批量更新请求都会返回响应，因此您可以访问新添加的对象的元数据，例如 ID 或标题。
如果使用此方法，您可以使用包含多个子请求的一个 API 批量更新请求来构建整个 Google 文档。
批量请求的格式
请求 是包含多个嵌套子请求（具有一个必需属性 requests）的单个 JSON 请求。这些请求都是在单个请求数组中构造的。每个请求都使用 JSON 来表示请求对象并包含其属性。
批量响应的格式
批量请求的 response 格式与请求格式类似。服务器的响应包含对单个响应对象的完整回复。
主 JSON 对象的属性名为 replies。这些响应在一个数组中返回，其中每个请求的每个响应都会占用与相应索引对应的索引顺序。某些请求没有响应，并且该数组索引上的响应为空。
示例
以下示例展示了如何通过文档 API 使用批处理功能。
请求
此示例批量请求演示了如何执行以下操作：
- 使用
InsertTextRequest将“Hello World”文本插入现有文档的开头，索引Location为 1。 - 使用
UpdateTextStyleRequest更新“Hello”一词。startIndex和endIndex用于定义该段中带格式的文本的range。 - 使用
textStyle，将字体样式设置为粗体，将颜色设置为蓝色。
{
"requests":[
{
"insertText":{
"location":{
"index":1
},
"text":"Hello World"
}
},
{
"updateTextStyle":{
"range":{
"startIndex":1,
"endIndex":6
},
"textStyle":{
"bold":true,
"foregroundColor":{
"color":{
"rgbColor":{
"blue":1
}
}
}
},
"fields":"bold,foreground_color"
}
}
]
}
响应
此示例批量响应显示了批处理请求中的每个子请求如何应用的相关信息。请注意，InsertTextRequest 和 UpdateTextStyleRequest 均不包含响应，因此 [0] 和 [1] 处的数组的索引值由空花括号组成。该批量请求会显示 WriteControl，说明写入请求的执行方式。
{
"replies":[
{
},
{
}
],
"writeControl":{
"requiredRevisionId":`REVISION_ID`
},
"documentId":`DOCUMENT_ID`
}