แนวทางปฏิบัติแนะนำเพื่อให้ได้ผลลัพธ์ที่ดีที่สุด

คุณควรปฏิบัติตามหลักการหลายประการเมื่อใช้ Google เอกสาร API ซึ่งได้แก่

• ตัดต่อย้อนหลังเพื่อประสิทธิภาพ
• วางแผนการทำงานร่วมกัน
• ตรวจสอบความสอดคล้องของสถานะโดยใช้ฟิลด์ WriteControl
• พิจารณาแท็บ

ส่วนต่อไปนี้จะอธิบายหลักการเหล่านี้

ตัดต่อย้อนหลังเพื่อประสิทธิภาพ

ในการเรียกใช้เมธอด documents.batchUpdate ครั้งเดียว ให้จัดเรียงคำขอตามลำดับจากมากไปน้อยของตำแหน่งดัชนี จึงไม่จำเป็นต้องคำนวณ การเปลี่ยนแปลงดัชนีเนื่องจากการแทรกและการลบ

วางแผนการทำงานร่วมกัน

คาดว่าสถานะเอกสารจะมีการเปลี่ยนแปลง ระหว่างการเรียกใช้เมธอดหนึ่งกับการเรียกใช้เมธอดอื่น ผู้ร่วมแก้ไขคนอื่นๆ อาจอัปเดตเอกสาร ดังที่แสดงในไดอะแกรมต่อไปนี้

ซึ่งอาจทำให้เกิดข้อผิดพลาดหากดัชนีไม่ถูกต้อง เมื่อผู้ใช้หลายคนแก้ไขเอกสารโดยใช้ UI นั้น Google เอกสารจะจัดการเรื่องนี้อย่างโปร่งใส อย่างไรก็ตาม ในฐานะไคลเอ็นต์ API แอปของคุณต้องจัดการเรื่องนี้ แม้ว่าคุณจะไม่คาดหวัง การทำงานร่วมกันในเอกสาร แต่ก็ควรเขียนโปรแกรมอย่างรอบคอบและตรวจสอบ ว่าสถานะของเอกสารยังคงสอดคล้องกัน หากต้องการดูวิธีหนึ่งในการรับประกันความสอดคล้อง โปรดดูส่วนWriteControl

สร้างความสอดคล้องของสถานะด้วย WriteControl

เมื่ออ่านและอัปเดตเอกสาร คุณจะควบคุมลักษณะการทำงานของวิธีจัดการการเปลี่ยนแปลงที่ขัดแย้งกันได้โดยใช้ฟิลด์ WriteControl ในเมธอด documents.batchUpdate WriteControl ให้สิทธิ์ ในการดำเนินการคำขอเขียน

วิธีใช้มีดังนี้

1. รับเอกสารโดยใช้เมธอด documents.get และบันทึก revisionId จากทรัพยากร documents ที่ส่งคืน
2. เขียนคำขออัปเดต
3. รวมออบเจ็กต์ WriteControl ที่ไม่บังคับพร้อมตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้
   1. ระบบจะตั้งค่าฟิลด์ requiredRevisionId เป็น revisionId ของ เอกสารที่ใช้คำขอเขียน หากมีการแก้ไขเอกสารตั้งแต่ส่งคำขออ่าน API ระบบจะไม่ประมวลผลคำขอเขียนและจะแสดงข้อผิดพลาด
   2. ระบบจะตั้งค่าฟิลด์ targetRevisionId เป็น revisionId ของเอกสาร ที่ใช้คำขอเขียน หากมีการแก้ไขเอกสารตั้งแต่ส่งคำขออ่าน API ระบบจะใช้การเปลี่ยนแปลงคำขอเขียนกับการเปลี่ยนแปลงของผู้ทำงานร่วมกัน ผลลัพธ์ของคำขอเขียนจะรวมทั้ง การเปลี่ยนแปลงคำขอเขียนและการเปลี่ยนแปลงของผู้ทำงานร่วมกันไว้ในการแก้ไข เอกสารฉบับใหม่ เซิร์ฟเวอร์เอกสารมีหน้าที่ ผสานเนื้อหา

ดูตัวอย่างวิธีสร้างคำขอแบบกลุ่มโดยใช้ WriteControl ได้ที่ตัวอย่างคำขอแบบกลุ่มนี้

พิจารณาแท็บ

เอกสารเดียวอาจมีแท็บหลายแท็บ ซึ่งต้องมีการจัดการเฉพาะในคำขอ API

สิ่งที่ควรจดจำมีดังนี้

1. ตั้งค่าพารามิเตอร์ includeTabsContent เป็น true ในเมธอด documents.get เพื่อดึงเนื้อหาจากแท็บทั้งหมดในเอกสาร โดยค่าเริ่มต้น ระบบจะไม่แสดงเนื้อหาแท็บทั้งหมด
2. ระบุรหัสของแท็บที่จะใช้กับ Request แต่ละรายการในเมธอด documents.batchUpdate แต่ละ Request รายการจะมีวิธีระบุแท็บที่จะใช้การอัปเดต โดยค่าเริ่มต้น หากไม่ได้ระบุแท็บ ระบบจะใช้Request กับแท็บแรกในเอกสารในกรณีส่วนใหญ่ ดูรายละเอียดได้ที่เอกสารประกอบของ Request

หัวข้อที่เกี่ยวข้อง

• คำขอแบบกลุ่ม
• คำขอและการตอบกลับ
• ทำงานกับแท็บ