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

คุณควรปฏิบัติตามหลักการหลายประการเมื่อใช้ 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

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

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