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

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

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

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

แก้ไขย้อนหลังเพื่อเพิ่มประสิทธิภาพ

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

วางแผนสําหรับการทำงานร่วมกัน

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

วิธีที่เอกสารจะเปลี่ยนแปลงระหว่างการเรียกใช้เมธอด

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

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

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

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

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

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

คำนึงถึงแท็บ

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

สิ่งที่ต้องจดจำมีดังนี้

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