คุณควรปฏิบัติตามหลักการหลายประการเมื่อใช้ Google เอกสาร API ซึ่งได้แก่
- แก้ไขย้อนหลังเพื่อเพิ่มประสิทธิภาพ
- วางแผนสําหรับการทำงานร่วมกัน
- ตรวจสอบความสอดคล้องของสถานะโดยใช้ช่อง
WriteControl
- คำนึงถึงแท็บ
ส่วนต่อไปนี้จะอธิบายหลักการเหล่านี้
แก้ไขย้อนหลังเพื่อเพิ่มประสิทธิภาพ
ภายในการเรียกใช้วิธี documents.batchUpdate
ครั้งเดียว ให้จัดเรียงคำขอตามลําดับจากน้อยไปมากของตําแหน่งดัชนี ซึ่งจะช่วยลดความจำเป็นในการคํานวณการเปลี่ยนแปลงดัชนีเนื่องจากการแทรกและการลบ
วางแผนสําหรับการทำงานร่วมกัน
โปรดทราบว่าสถานะเอกสารจะเปลี่ยนแปลง ระหว่างการเรียกใช้เมธอดหนึ่งกับอีกเมธอดหนึ่ง ผู้ทำงานร่วมกันคนอื่นๆ อาจอัปเดตเอกสารได้ ดังที่แสดงในแผนภาพต่อไปนี้
ซึ่งอาจทำให้เกิดข้อผิดพลาดหากดัชนีไม่ถูกต้อง เมื่อผู้ใช้หลายคนแก้ไขเอกสารโดยใช้ UI ทาง Google เอกสารจะจัดการเรื่องนี้อย่างโปร่งใส อย่างไรก็ตาม ในฐานะไคลเอ็นต์ API แอปของคุณต้องจัดการเรื่องนี้ แม้ว่าคุณจะไม่ได้คาดหวังการทำงานร่วมกันในเอกสาร แต่คุณก็ควรเขียนโปรแกรมเพื่อการป้องกันและตรวจสอบว่าสถานะเอกสารยังคงสอดคล้องกัน ตรวจสอบส่วน WriteControl
เพื่อดูวิธีตรวจสอบความสอดคล้อง
สร้างความสอดคล้องของสถานะด้วย WriteControl
เมื่ออ่านและอัปเดตเอกสาร คุณจะควบคุมลักษณะการประมวลผลการเปลี่ยนแปลงที่ทับซ้อนกันโดยใช้ฟิลด์ WriteControl
ในเมธอด documents.batchUpdate
ได้ WriteControl
ให้สิทธิ์ในการควบคุมวิธีดำเนินการกับคำขอเขียน
วิธีใช้มีดังนี้
- รับเอกสารโดยใช้เมธอด
documents.get
และบันทึกrevisionId
จากแหล่งข้อมูลdocuments
ที่แสดงผล - เขียนคำขออัปเดต
- รวมออบเจ็กต์
WriteControl
(ไม่บังคับ) ที่มีตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้- ระบบตั้งค่าช่อง
requiredRevisionId
เป็นrevisionId
ของเอกสารที่มีการใช้คำขอเขียน หากมีการแก้ไขเอกสารตั้งแต่ที่มีคำขออ่าน API ระบบจะไม่ประมวลผลคำขอเขียนและจะแสดงข้อผิดพลาด - ระบบตั้งค่าช่อง
targetRevisionId
เป็นrevisionId
ของเอกสารที่ใช้กับคำขอเขียน หากมีการแก้ไขเอกสารนับตั้งแต่คำขออ่าน API การเปลี่ยนแปลงในคำขอเขียนจะมีผลกับการเปลี่ยนแปลงของผู้ทำงานร่วมกัน ผลลัพธ์ของคำขอเขียนจะรวมทั้งการเปลี่ยนแปลงคำขอเขียนและการเปลี่ยนแปลงของผู้ทำงานร่วมกันไว้ในเอกสารฉบับแก้ไขใหม่ เซิร์ฟเวอร์เอกสารจะรับผิดชอบในการผสานเนื้อหา
- ระบบตั้งค่าช่อง
ดูตัวอย่างวิธีสร้างคําขอแบบกลุ่มโดยใช้ WriteControl
ได้ที่ตัวอย่างคําขอแบบกลุ่มนี้
คำนึงถึงแท็บ
เอกสารเดียวอาจมีแท็บได้หลายแท็บ ซึ่งต้องใช้การจัดการที่เฉพาะเจาะจงในคําขอ API
สิ่งที่ควรทราบมีดังนี้
- ตั้งค่าพารามิเตอร์
includeTabsContent
เป็นtrue
ในเมธอดdocuments.get
เพื่อดึงข้อมูลจากแท็บทั้งหมดในเอกสาร โดยค่าเริ่มต้น ระบบจะไม่แสดงเนื้อหาแท็บทั้งหมด - ระบุรหัสของแท็บที่จะใช้
Request
แต่ละรายการในเมธอดdocuments.batchUpdate
Request
แต่ละรายการจะมีวิธีระบุแท็บที่จะใช้การอัปเดต โดยค่าเริ่มต้น หากไม่ได้ระบุแท็บ ในกรณีส่วนใหญ่Request
จะนำไปใช้กับแท็บแรกในเอกสาร โปรดดูรายละเอียดในเอกสารประกอบของRequest