documents.batchUpdate 메서드를 한 번 호출할 때 색인 위치를 내림차순으로 요청을 정렬합니다. 이렇게 하면 삽입 및 삭제로 인한 색인 변경사항을 계산할 필요가 없습니다.
공동작업 계획
문서 상태가 변경될 것으로 예상합니다. 한 메서드 호출과 다른 메서드 호출 사이에 다른 공동작업자가 문서를 업데이트할 수 있습니다. 다음 다이어그램을 참고하세요.
색인이 잘못되면 오류가 발생할 수 있습니다. 여러 사용자가 UI를 사용하여 문서를 수정하는 경우 Google Docs에서 이를 투명하게 처리합니다. 하지만 API 클라이언트로서 앱에서 이를 관리해야 합니다. 문서에 대한 공동작업을 예상하지 않더라도 방어적으로 프로그래밍하고 문서 상태가 일관되게 유지되도록 하는 것이 중요합니다. 일관성을 유지하는 한 가지 방법은 WriteControl 섹션을 검토하는 것입니다.
WriteControl로 상태 일관성 설정
문서를 읽은 후 업데이트할 때 documents.batchUpdate 메서드의 WriteControl 필드를 사용하여 경합하는 변경사항이 처리되는 방식을 제어할 수 있습니다. WriteControl는 쓰기 요청이 실행되는 방식에 대한 권한을 제공합니다.
requiredRevisionId 필드는 쓰기 요청이 적용되는 문서의 revisionId로 설정됩니다. API 읽기 요청 이후 문서가 수정된 경우 쓰기 요청이 처리되지 않고 오류가 반환됩니다.
targetRevisionId 필드는 쓰기 요청이 적용되는 문서의 revisionId로 설정됩니다. API 읽기 요청 이후 문서가 수정된 경우 쓰기 요청 변경사항이 공동작업자 변경사항에 적용됩니다. 쓰기 요청의 결과는 쓰기 요청 변경사항과 공동작업자 변경사항을 모두 문서의 새 버전으로 통합합니다. Docs 서버는 콘텐츠 병합을 담당합니다.
WriteControl를 사용하여 일괄 요청을 구성하는 방법의 예는 이 일괄 요청 예를 참고하세요.
[[["이해하기 쉬움","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"]],["최종 업데이트: 2025-08-29(UTC)"],[],[],null,["# Best practices for best results\n\nThere are several principles you should follow when using the Google Docs API.\nThese include:\n\n- Edit backwards for efficiency\n- Plan for collaboration\n- Ensure state consistency using the [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) field\n- Take tabs into account\n\nThe following sections explain these principles.\n\nEdit backwards for efficiency\n-----------------------------\n\nWithin a single call to the\n[`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate)\nmethod, order your requests in\n*descending order* of index location. This eliminates the need to compute the\nindex changes due to insertions and deletions.\n\nPlan for collaboration\n----------------------\n\nExpect the document state to change. Between one method call and another, other\ncollaborators might update the document, as shown in the following diagram:\n\nThis can lead to errors if your indexes are wrong. With multiple users editing a\ndocument using the UI, Google Docs takes care of this transparently. However,\nas an API client your app must manage this. Even if you don't anticipate\ncollaboration on the document, it's important to program defensively and make\nsure the document state remains consistent. For one way to ensure consistency,\nreview the [`WriteControl`](#establish-state-consistency) section.\n\nEstablish state consistency with WriteControl\n---------------------------------------------\n\nWhen you read and then update a document, you can control the behavior of how\ncompeting changes are handled using the\n[`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol)\nfield in the `documents.batchUpdate` method. `WriteControl` provides authority\nover how write requests are executed.\n\nHere's how you use it:\n\n1. Get the document using the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method and save the [`revisionId`](/workspace/docs/api/reference/rest/v1/documents#Document.FIELDS.revision_id) from the returned `documents` resource.\n2. Compose your update requests.\n3. Include an optional [`WriteControl`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate#writecontrol) object with one of two options:\n 1. The `requiredRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request isn't processed and it returns an error.\n 2. The `targetRevisionId` field is set to the `revisionId` of the document the write request is applied to. If the document was modified since the API read request, the write request changes are applied against the collaborator changes. The result of the write request incorporates both the write request changes and the collaborator changes into a new revision of the document. The Docs server is responsible for merging the content.\n\nFor an example of how to construct a batch request using `WriteControl`, see\nthis [batch request example](/workspace/docs/api/how-tos/batch#example).\n\nTake tabs into account\n----------------------\n\nA single document can contain multiple [tabs](/workspace/docs/api/how-tos/tabs),\nwhich require specific handling in your API requests.\n\nHere's what to remember:\n\n1. Set the `includeTabsContent` parameter to `true` in the [`documents.get`](/workspace/docs/api/reference/rest/v1/documents/get) method to retrieve the content from all tabs in a document. By default, not all tab contents are returned.\n2. Specify the ID(s) of the tab(s) to apply each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) to in the [`documents.batchUpdate`](/workspace/docs/api/reference/rest/v1/documents/batchUpdate) method. Each [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) includes a way to specify the tabs to apply the update to. By default, if a tab is not specified, the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request) will in most cases be applied to the first tab in the document. Refer to the [`Request`](/workspace/docs/api/reference/rest/v1/documents/request#request)s documentation for specifics.\n\nRelated topics\n--------------\n\n- [Batch requests](/workspace/docs/api/how-tos/batch)\n- [Requests and responses](/workspace/docs/api/concepts/request-response)\n- [Work with tabs](/workspace/docs/api/how-tos/tabs)"]]
