Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Bạn nên tuân thủ một số nguyên tắc khi sử dụng Google Docs API.
bao gồm:
Chỉnh sửa ngược để tăng hiệu quả
Lập kế hoạch cộng tác
Đảm bảo tính nhất quán về trạng thái bằng cách sử dụng trường WriteControl
Tính đến các thẻ
Các phần sau đây giải thích những nguyên tắc này.
Chỉnh sửa ngược để tăng hiệu quả
Trong một lệnh gọi duy nhất đến phương thức documents.batchUpdate, hãy sắp xếp các yêu cầu theo thứ tự giảm dần của vị trí chỉ mục. Điều này giúp bạn không cần phải tính toán các thay đổi về chỉ mục do các thao tác chèn và xoá.
Lập kế hoạch cộng tác
Dự kiến trạng thái tài liệu sẽ thay đổi. Giữa một lệnh gọi phương thức và một lệnh gọi phương thức khác, những cộng tác viên khác có thể cập nhật tài liệu, như minh hoạ trong sơ đồ sau:
Điều này có thể dẫn đến lỗi nếu chỉ mục của bạn không chính xác. Khi nhiều người dùng chỉnh sửa một tài liệu bằng giao diện người dùng, Google Tài liệu sẽ xử lý việc này một cách minh bạch. Tuy nhiên, với tư cách là một ứng dụng API, ứng dụng của bạn phải quản lý việc này. Ngay cả khi không dự đoán được việc cộng tác trên tài liệu, bạn vẫn cần lập trình một cách thận trọng và đảm bảo trạng thái của tài liệu luôn nhất quán. Để đảm bảo tính nhất quán, hãy xem phần WriteControl.
Thiết lập tính nhất quán về trạng thái bằng WriteControl
Khi đọc rồi cập nhật một tài liệu, bạn có thể kiểm soát hành vi xử lý các thay đổi cạnh tranh bằng cách sử dụng trường WriteControl trong phương thức documents.batchUpdate. WriteControl cung cấp quyền kiểm soát cách thực hiện các yêu cầu ghi.
Sau đây là cách sử dụng:
Lấy tài liệu bằng phương thức documents.get và lưu revisionId từ tài nguyên documents được trả về.
Soạn yêu cầu cập nhật.
Thêm một đối tượng WriteControl không bắt buộc bằng một trong hai lựa chọn:
Trường requiredRevisionId được đặt thành revisionId của tài liệu mà yêu cầu ghi được áp dụng. Nếu tài liệu đã được sửa đổi kể từ yêu cầu đọc API, thì yêu cầu ghi sẽ không được xử lý và trả về lỗi.
Trường targetRevisionId được đặt thành revisionId của tài liệu mà yêu cầu ghi được áp dụng. Nếu tài liệu đã được sửa đổi kể từ yêu cầu đọc API, thì các thay đổi trong yêu cầu ghi sẽ được áp dụng cho các thay đổi của cộng tác viên. Kết quả của yêu cầu ghi kết hợp cả các thay đổi của yêu cầu ghi và các thay đổi của cộng tác viên thành một phiên bản mới của tài liệu. Máy chủ Tài liệu chịu trách nhiệm hợp nhất nội dung.
Một tài liệu có thể chứa nhiều thẻ, bạn cần xử lý cụ thể trong các yêu cầu API.
Sau đây là những điều cần nhớ:
Đặt tham số includeTabsContent thành true trong phương thức documents.get để truy xuất nội dung từ tất cả các thẻ trong một tài liệu. Theo mặc định, không phải tất cả nội dung thẻ đều được trả về.
Chỉ định(các) mã nhận dạng của(các) thẻ để áp dụng từng Request trong phương thức documents.batchUpdate. Mỗi Request đều có cách chỉ định các thẻ để áp dụng bản cập nhật. Theo mặc định, nếu bạn không chỉ định thẻ, thì Request sẽ được áp dụng cho thẻ đầu tiên trong tài liệu trong hầu hết các trường hợp. Tham khảo tài liệu về Request để biết thông tin cụ thể.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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)"]]
