批处理请求

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

概览

客户端建立的每个连接都会产生一定的开销。Google 表格 API 支持批处理，这样您的客户端就可以将多个请求对象放入单个批处理请求中，每个对象指定一种要执行的请求类型。批处理请求可以通过将多个子请求组合为对服务器的单个调用来检索单个响应，从而提升性能。

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

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

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

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

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

批量详情

批量请求包含一个 batchUpdate 方法调用，其中包含多个子请求，例如添加电子表格以及设置电子表格的格式。

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

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

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

批量请求的格式

请求是指包含多个嵌套子请求的单个 JSON 请求，该子请求具有一个必需属性：requests。这些请求是在单个请求的数组中构造的。每个请求都使用 JSON 来表示请求对象并包含其属性。

批量响应的格式

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

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

示例

以下示例展示了如何通过 Sheets API 使用批处理。

请求

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

通过在请求中添加工作表 ID，用户可以在同一 API 调用中针对其他子请求使用该工作表 ID。这样可以避免写-读-写循环，从而提高性能。

如需按不同类别分组的批量更新请求类型列表，请参阅批量更新操作下的表格。

{
   "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
            }
         }
      }
   }
]