[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-01。"],[],[],null,["This 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\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\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\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\nFormat 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\nFormat 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\nThe following code sample shows the use of batching with the Docs API.\n\nRequest\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\nResponse\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- [Best practices for best results](/workspace/docs/api/how-tos/best-practices)"]]
