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

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

คำนึงถึงแท็บต่างๆ

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

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

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