แนวทางปฏิบัติแนะนำเพื่อให้ได้ผลลัพธ์ที่ดีที่สุด
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
คุณควรปฏิบัติตามหลักการหลายประการเมื่อใช้ Google เอกสาร API
ซึ่งได้แก่
- ตัดต่อย้อนหลังเพื่อประสิทธิภาพ
- วางแผนการทำงานร่วมกัน
- ตรวจสอบความสอดคล้องของสถานะโดยใช้ฟิลด์
WriteControl
- พิจารณาแท็บ
ส่วนต่อไปนี้จะอธิบายหลักการเหล่านี้
ตัดต่อย้อนหลังเพื่อประสิทธิภาพ
ในการเรียกใช้เมธอด
documents.batchUpdate
ครั้งเดียว ให้จัดเรียงคำขอตามลำดับจากมากไปน้อยของตำแหน่งดัชนี จึงไม่จำเป็นต้องคำนวณ
การเปลี่ยนแปลงดัชนีเนื่องจากการแทรกและการลบ
วางแผนการทำงานร่วมกัน
คาดว่าสถานะเอกสารจะมีการเปลี่ยนแปลง ระหว่างการเรียกใช้เมธอดหนึ่งกับการเรียกใช้เมธอดอื่น ผู้ร่วมแก้ไขคนอื่นๆ อาจอัปเดตเอกสาร ดังที่แสดงในไดอะแกรมต่อไปนี้
ซึ่งอาจทำให้เกิดข้อผิดพลาดหากดัชนีไม่ถูกต้อง เมื่อผู้ใช้หลายคนแก้ไขเอกสารโดยใช้ UI นั้น Google เอกสารจะจัดการเรื่องนี้อย่างโปร่งใส อย่างไรก็ตาม
ในฐานะไคลเอ็นต์ API แอปของคุณต้องจัดการเรื่องนี้ แม้ว่าคุณจะไม่คาดหวัง
การทำงานร่วมกันในเอกสาร แต่ก็ควรเขียนโปรแกรมอย่างรอบคอบและตรวจสอบ
ว่าสถานะของเอกสารยังคงสอดคล้องกัน หากต้องการดูวิธีหนึ่งในการรับประกันความสอดคล้อง
โปรดดูส่วนWriteControl
สร้างความสอดคล้องของสถานะด้วย WriteControl
เมื่ออ่านและอัปเดตเอกสาร คุณจะควบคุมลักษณะการทำงานของวิธีจัดการการเปลี่ยนแปลงที่ขัดแย้งกันได้โดยใช้ฟิลด์ WriteControl
ในเมธอด documents.batchUpdate WriteControl ให้สิทธิ์
ในการดำเนินการคำขอเขียน
วิธีใช้มีดังนี้
- รับเอกสารโดยใช้เมธอด
documents.get
และบันทึก
revisionId
จากทรัพยากร documents ที่ส่งคืน
- เขียนคำขออัปเดต
- รวมออบเจ็กต์
WriteControl
ที่ไม่บังคับพร้อมตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้
- ระบบจะตั้งค่าฟิลด์
requiredRevisionId เป็น revisionId ของ
เอกสารที่ใช้คำขอเขียน หากมีการแก้ไขเอกสารตั้งแต่ส่งคำขออ่าน API ระบบจะไม่ประมวลผลคำขอเขียนและจะแสดงข้อผิดพลาด
- ระบบจะตั้งค่าฟิลด์
targetRevisionId เป็น revisionId ของเอกสาร
ที่ใช้คำขอเขียน หากมีการแก้ไขเอกสารตั้งแต่ส่งคำขออ่าน API ระบบจะใช้การเปลี่ยนแปลงคำขอเขียนกับการเปลี่ยนแปลงของผู้ทำงานร่วมกัน ผลลัพธ์ของคำขอเขียนจะรวมทั้ง
การเปลี่ยนแปลงคำขอเขียนและการเปลี่ยนแปลงของผู้ทำงานร่วมกันไว้ในการแก้ไข
เอกสารฉบับใหม่ เซิร์ฟเวอร์เอกสารมีหน้าที่
ผสานเนื้อหา
ดูตัวอย่างวิธีสร้างคำขอแบบกลุ่มโดยใช้ WriteControl ได้ที่ตัวอย่างคำขอแบบกลุ่มนี้
พิจารณาแท็บ
เอกสารเดียวอาจมีแท็บหลายแท็บ
ซึ่งต้องมีการจัดการเฉพาะในคำขอ API
สิ่งที่ควรจดจำมีดังนี้
- ตั้งค่าพารามิเตอร์
includeTabsContent เป็น true ในเมธอด
documents.get
เพื่อดึงเนื้อหาจากแท็บทั้งหมดในเอกสาร โดยค่าเริ่มต้น ระบบจะไม่แสดงเนื้อหาแท็บทั้งหมด
- ระบุรหัสของแท็บที่จะใช้กับ
Request แต่ละรายการในเมธอด documents.batchUpdate แต่ละ
Request
รายการจะมีวิธีระบุแท็บที่จะใช้การอัปเดต โดยค่าเริ่มต้น หากไม่ได้ระบุแท็บ ระบบจะใช้Request กับแท็บแรกในเอกสารในกรณีส่วนใหญ่ ดูรายละเอียดได้ที่เอกสารประกอบของ
Request
เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-08-29 UTC
[null,null,["อัปเดตล่าสุด 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)"]]
