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

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