批处理请求
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本文档介绍了如何对 API 调用进行批处理,以减少客户端必须建立的连接数。批处理可以通过减少网络往返次数和提高吞吐量来提高应用效率。
概览
客户端建立的每个连接都会产生一定的开销。
Google Docs API 支持批处理,让您的客户端可以将多个请求对象(每个对象指定要执行的单个请求类型)放入单个批量请求中。通过将多个子请求合并为对服务器的单个调用,并检索单个响应,批处理请求可以提高性能。
我们建议用户始终将多个请求一起进行批处理。以下是一些可以使用批处理的情况示例:
-
您刚开始使用该 API,并且需要上传大量数据。
-
您需要更新多个对象的元数据或属性(例如格式)。
- 您需要删除多个对象。
限制、授权和依赖项注意事项
以下是采用批量更新时需要考虑的其他事项:
-
每个批处理请求(包括所有子请求)都算作一次 API 请求,计入您的用量限额。
-
批量请求只需进行一次身份验证。此单一身份验证适用于请求中的所有批量更新对象。
-
服务器会按子请求在批处理请求中出现的顺序处理这些子请求。后面的子请求可以依赖于在前面的子请求期间采取的操作。例如,在同一批处理请求中,用户可以将文本插入现有文档,然后设置其样式。
批量详情
批处理请求包含一个 batchUpdate
方法调用,其中包含多个子请求,例如添加文档,然后设置文档格式。
每项请求都会在应用之前进行验证。批处理更新中的所有子请求均以原子方式应用。也就是说,如果任何请求无效,则整个更新都会失败,并且不会应用任何(可能相关的)更改。
某些请求会提供包含有关已应用请求的信息的响应。
例如,所有用于添加对象的批量更新请求都会返回响应,以便您访问新添加对象的元数据,例如 ID 或标题。
借助此方法,您可以使用一个包含多个子请求的 API 批量更新请求来构建整个 Google 文档。
请求是一个包含多个嵌套子请求的 JSON 请求,其中包含一个必需属性:requests
。请求是在单个请求的数组中构建的。每个请求都使用 JSON 来表示请求对象并包含其属性。
批量请求的响应格式与请求格式类似。服务器的响应包含单个响应对象的完整答复。
主要 JSON 对象的属性名为 replies
。响应以数组形式返回,其中每个响应都与相应请求的索引顺序相同。某些请求没有响应,因此相应数组索引处的响应为空。
示例
以下代码示例展示了如何将批处理与 Docs API 搭配使用。
请求
此批量请求示例演示了如何执行以下操作:
{
"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`
}
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-29。
[null,null,["最后更新时间 (UTC):2025-08-29。"],[],[],null,["# Batch requests\n\nThis document shows how to batch API calls together to reduce the number of\nconnections your client has to make. Batching can improve an application's\nefficiency by decreasing network round trips and increasing throughput.\n\nOverview\n--------\n\n\nEach connection your client makes results in a certain amount of overhead.\nThe Google Docs API supports batching to let your client place multiple\nrequest objects, each one specifying a single type of request to perform,\ninto a single batch request. A batch request can boost performance by\ncombining multiple subrequests into a single call to the server, retrieving\na single response back.\n\n\nWe encourage users to always batch multiple requests together. Here are some\nexamples of situations where you can use batching:\n\n- You've just started using the API and you have lots of data to upload.\n- You need to update metadata or properties, such as formatting, on multiple objects.\n- You need to delete many objects.\n\nLimits, authorization, \\& dependency considerations\n---------------------------------------------------\n\nHere's a list of other items to consider when employing batch updating:\n\n- Each batch request, including all subrequests, is counted as one API request toward your [usage limit](/workspace/docs/api/limits).\n- A batch request is authenticated once. This single authentication applies to all batch update objects in the request.\n- The server processes the subrequests in the same order they appear in the batch request. Latter subrequests can depend on actions taken during earlier subrequests. For example, in the same batch request, users can insert text into an existing document and then style it.\n\nBatch details\n-------------\n\n\nA batch request consists of one [batchUpdate](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method call\nwith multiple subrequests to, for example, add and then format a document.\n\n\nEach request is validated before being applied. All subrequests in the batch\nupdate are applied atomically. That is, if any request is not valid then the\nentire update is unsuccessful and none of the (potentially dependent)\nchanges are applied.\n\n\nSome requests provide responses with information about the applied requests.\nFor example, all batch update requests to add objects return responses so\nyou can access the metadata of the newly added object, such as the ID or\ntitle.\n\n\nWith this approach, you can build an entire Google document using one API\nbatch update request with multiple subrequests.\n\n### Format of a batch request\n\n\nA [request](/workspace/docs/api/reference/rest/v1/documents/request) is a single JSON request containing multiple,\nnested subrequests with one required property: `requests`. The\nrequests are constructed in an array of individual requests. Each request uses\nJSON to represent the request object and to contain its properties.\n\n### Format of a batch response\n\n\nThe [response](/workspace/docs/api/reference/rest/v1/documents/response) format for a batch request is similar to the\nrequest format. The server's response contains a complete reply of the single\nresponse object.\n\n\nThe main JSON object's property is named `replies`. The responses\nare returned in an array, with each response to one of the requests occupying\nthe same index order as the corresponding request. Some requests don't have\nresponses and the response at that array index is empty.\n\nExample\n-------\n\nThe following code sample shows the use of batching with the Docs API.\n\n### Request\n\nThis example batch request demonstrates how to:\n\n- Insert \"Hello World\" text into the start of an existing document, with an\n index `location` of `1`, using the\n [`InsertTextRequest`](/workspace/docs/api/reference/rest/v1/documents/request#inserttextrequest).\n\n- Update the word \"Hello\" using the\n [`UpdateTextStyleRequest`](/workspace/docs/api/reference/rest/v1/documents/request#updatetextstylerequest).\n The `startIndex` and `endIndex` define the `range` of formatted text within\n the segment.\n\n- Using `textStyle`, set the font style to bold and the color to blue for just\n the word \"Hello\".\n\n- Using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\n field, you can control how write requests are executed. For more\n information, see [Establish state consistency with\n WriteControl](/workspace/docs/api/how-tos/best-practices#establish-state-consistency).\n\n```verilog\n{\n \"requests\":[\n {\n \"insertText\":{\n \"location\":{\n \"index\":1,\n \"tabId\":TAB_ID\n },\n \"text\":\"Hello World\"\n }\n },\n {\n \"updateTextStyle\":{\n \"range\":{\n \"startIndex\":1,\n \"endIndex\":6\n },\n \"textStyle\":{\n \"bold\":true,\n \"foregroundColor\":{\n \"color\":{\n \"rgbColor\":{\n \"blue\":1\n }\n }\n }\n },\n \"fields\":\"bold,foreground_color\"\n }\n }\n ],\n \"writeControl\": {\n \"requiredRevisionId\": \"\u003cvar translate=\"no\"\u003eREQUIRED_REVISION_ID\u003c/var\u003e\"\n }\n}\n```\n\nReplace \u003cvar translate=\"no\"\u003eTAB_ID\u003c/var\u003e and \u003cvar translate=\"no\"\u003eREQUIRED_REVISION_ID\u003c/var\u003e with\nthe tab ID and the revision ID, respectively, of the document the write request\nis applied to.\n\n### Response\n\nThis example batch response displays information on how each subrequest within\nthe batch request was applied. Neither the\n[`InsertTextRequest`](/workspace/docs/api/reference/rest/v1/documents/request#InsertTextRequest)\nor the\n[`UpdateTextStyleRequest`](/workspace/docs/api/reference/rest/v1/documents/request#updatetextstylerequest)\ncontain a response, so the index values of the array at \\[0\\] and \\[1\\] consist\nof empty curly braces. The batch request displays the `WriteControl` object,\nwhich shows how the requests were executed. \n\n```mysql\n{\n \"replies\":[\n {},\n {}\n ],\n \"writeControl\":{\n \"requiredRevisionId\":`\u003cvar translate=\"no\"\u003eREQUIRED_REVISION_ID\u003c/var\u003e`\n },\n \"documentId\":`\u003cvar translate=\"no\"\u003eDOCUMENT_ID\u003c/var\u003e`\n}\n```\n\nRelated topics\n--------------\n\n- [Best practices for best results](/workspace/docs/api/how-tos/best-practices)"]]