本文档介绍了如何对 API 调用进行批处理以减少 您需要建立的网络连接批处理可以提高应用的 减少网络往返次数,提高吞吐量。
概览
客户端建立的每个连接都会产生一定的开销。 Google Sheets API 支持批处理,让您的客户端可以放置多个 每个请求对象都指定一种要执行的请求 转换为单个批处理请求批量请求可以通过以下方式提升性能: 将多个子请求合并为对服务器的单个调用,从而检索 返回单个响应。
我们建议用户始终批量处理多个请求。以下是一些 以下是可以使用批处理的情况示例:
- 您刚开始使用该 API,需要上传大量数据。
- 您需要更新多个 对象的操作。
- 您需要删除许多对象。
限制、授权和依赖项注意事项
下面列出了采用批量更新时需要注意的其他事项:
- 每个批量请求(包括所有子请求)都计为一个 API 用量限额请求。
- 一个批量请求需经过一次身份验证。此单一身份验证适用 请求中的所有批量更新对象。
- 服务器会按照子请求在 批量请求。后面的子请求可能取决于 先前的子请求例如,在同一批量请求中,用户可以 将文本插入现有文档,然后设置其样式。
批量详情
一个批量请求包含一个 batchUpdate
方法调用
来处理多个子请求,例如添加电子表格和设置电子表格的格式。
每个请求都会经过验证,然后才能应用。批次中的所有子请求 update 以原子方式应用更新。也就是说,如果任何请求无效,则 整个更新都失败,并且没有任何(可能依赖的) 更改。
有些请求会在响应中提供与所应用请求相关的信息。 例如,所有用于添加对象的批量更新请求都会返回响应, 您可以访问新添加对象的元数据,如 ID 或 标题。
通过这种方法,您可以使用一个 API 构建整个 Google 文档 使用多个子请求的批量更新请求。
批量请求的格式
“请求”是指包含多个、
具有一个必需属性的嵌套子请求:requests
。通过
请求都是在单个请求的数组中构造而成的。每个请求都使用
JSON,用于表示请求对象并包含其属性。
批量响应的格式
批量请求的 response 格式类似于 请求格式。服务器的响应包含单个 响应对象。
主 JSON 对象的属性名为 replies
。响应
以数组的形式返回,其中对其中一个请求的响应
索引顺序相同。某些请求没有
且该数组索引处的响应为空。
示例
以下示例展示了如何通过 Sheets API 使用批处理。
请求
此示例批量请求演示了如何执行以下操作:
- 使用
AddSheetRequest
向现有电子表格添加一个工作表,并将sheetId
的值设为 12345。 - 使用
UpdateCellsRequest
向新工作表中添加从单元格 A1 开始的数据。 - 向新工作表添加
namedRange
或过滤视图。
通过在请求中添加工作表 ID,用户可以将工作表 ID 用于同一 API 调用中的其他子请求。这样可以避免写入-读写周期,从而提高性能。
如需查看按不同类别分组的批量更新请求类型列表,请参阅批量更新操作下的表格。
{ "requests":[ { "addSheet":{ "properties":{ "sheetId":123456 } } }, { "updateCells":{ "start":{ "sheetId":123456 }, "rows":[ { "values":[ { "userEnteredValue":{ "stringValue":"hello" } } ] }, { "values":[ { "userEnteredValue":{ "stringValue":"world" } } ] } ], "fields":"userEnteredValue" } }, { "addNamedRange":{ "namedRange":{ "name":"newRange", "range":{ "sheetId":123456, "endRowIndex":2 } } } } ] }
响应
此示例批量响应显示有关如何应用批量请求中的每个子请求的信息。请注意,UpdateCellsRequest
不包含响应,因此位于 [1] 的数组的索引值由空花括号组成。
"replies":[ { "addSheet":{ "properties":{ "sheetId":123456, "title":"Sheet3", "index":2, "sheetType":"GRID", "gridProperties":{ "rowCount":1000, "columnCount":26 } } } }, { }, { "addNamedRange":{ "namedRange":{ "namedRangeId":"2104325079", "name":"newRange", "range":{ "sheetId":123456, "startRowIndex":0, "endRowIndex":2, "startColumnIndex":0, "endColumnIndex":26 } } } } ]