เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API ไว้ด้วยกันเพื่อลดจำนวนการเชื่อมต่อที่ไคลเอ็นต์ต้องทำ โหมดแบบกลุ่มจะช่วยเพิ่มประสิทธิภาพของแอปพลิเคชันโดยการลดการรับส่งข้อมูลไปกลับของเครือข่ายและเพิ่มอัตราการส่งข้อมูล
ภาพรวม
การเชื่อมต่อแต่ละครั้งที่ไคลเอ็นต์ทำให้เกิดค่าใช้จ่ายในการดำเนินการหนึ่งๆ Google เอกสาร API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์วางออบเจ็กต์คำขอหลายรายการ โดยแต่ละรายการจะระบุคำขอประเภทเดียวที่จะดำเนินการลงในคำขอกลุ่มเดียว คำขอแบบกลุ่มช่วยเพิ่มประสิทธิภาพได้โดยการรวมคำขอย่อยหลายรายการไว้ในการเรียกไปยังเซิร์ฟเวอร์ครั้งเดียว แล้วดึงข้อมูลการตอบกลับครั้งเดียว
เราขอแนะนำให้ผู้ใช้รวบรวมคำขอหลายรายการไว้ด้วยกันเสมอ ต่อไปนี้คือตัวอย่างสถานการณ์ที่คุณสามารถใช้การจัดกลุ่ม
- คุณเพิ่งเริ่มใช้ API และมีข้อมูลที่ต้องอัปโหลดจำนวนมาก
- คุณต้องอัปเดตข้อมูลเมตาหรือพร็อพเพอร์ตี้ เช่น การจัดรูปแบบ บนออบเจ็กต์หลายรายการ
- คุณต้องลบออบเจ็กต์หลายรายการ
ข้อควรพิจารณาเกี่ยวกับขีดจำกัด การให้สิทธิ์ และการอ้างอิง
ต่อไปนี้เป็นรายการอื่นๆ ที่ควรพิจารณาเมื่อใช้การอัปเดตเป็นกลุ่ม
- คำขอกลุ่มแต่ละรายการ รวมถึงคำขอย่อยทั้งหมด จะนับเป็นคำขอ API 1 รายการในขีดจำกัดการใช้งาน
- คำขอแบบกลุ่มจะได้รับการตรวจสอบสิทธิ์ครั้งเดียว การตรวจสอบสิทธิ์รายการเดียวนี้จะมีผลกับออบเจ็กต์การอัปเดตแบบกลุ่มทั้งหมดในคำขอ
- เซิร์ฟเวอร์จะประมวลผลคำขอย่อยในลำดับเดียวกันกับที่ปรากฏในคำขอแบบกลุ่ม คำขอย่อยในภายหลังอาจขึ้นอยู่กับการดำเนินการที่เกิดขึ้นระหว่างคำขอย่อยก่อนหน้านี้ ตัวอย่างเช่น ในคำขอแบบกลุ่มเดียวกัน ผู้ใช้จะแทรกข้อความลงในเอกสารที่มีอยู่และจัดรูปแบบข้อความได้
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียกใช้เมธอด batchUpdate
1 รายการโดยมีคำขอย่อยหลายรายการสำหรับเพิ่มและจัดรูปแบบเอกสาร เป็นต้น
คำขอแต่ละรายการจะได้รับการตรวจสอบก่อนนำไปใช้ ระบบนำคำขอย่อยทั้งหมดในการอัปเดตเป็นกลุ่มไปใช้แบบอะตอม กล่าวคือ หากมีคำขอที่ไม่ถูกต้อง การอัปเดตทั้งหมดจะไม่สำเร็จ และจะไม่มีการใช้การเปลี่ยนแปลง (ที่อาจขึ้นอยู่กับ) กัน
คำขอบางรายการจะให้คำตอบพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ เช่น คำขออัปเดตแบบกลุ่มทั้งหมดเพื่อเพิ่มออบเจ็กต์จะแสดงการตอบกลับเพื่อให้คุณเข้าถึงข้อมูลเมตาของออบเจ็กต์ที่เพิ่มเข้ามาใหม่ เช่น รหัสหรือชื่อได้
ด้วยวิธีการนี้ คุณจะสร้างเอกสาร Google ทั้งฉบับได้โดยใช้คำขออัปเดตกลุ่ม API รายการเดียวที่มีคำขอย่อยหลายรายการ
รูปแบบของคำขอแบบกลุ่ม
คำขอคือคำขอ JSON รายการเดียวที่มีคำขอย่อยหลายรายการที่ซ้อนกันอยู่และมีพร็อพเพอร์ตี้ที่จำเป็น 1 รายการ ได้แก่ requests
ระบบจะสร้างคำขอในอาร์เรย์ของคำขอแต่ละรายการ คำขอแต่ละรายการใช้ JSON เพื่อแสดงออบเจ็กต์คำขอและมีพร็อพเพอร์ตี้ของออบเจ็กต์ดังกล่าว
รูปแบบของการตอบกลับแบบกลุ่ม
รูปแบบการตอบกลับสำหรับคำขอแบบกลุ่มจะคล้ายกับรูปแบบคำขอ การตอบกลับของเซิร์ฟเวอร์มีการตอบกลับออบเจ็กต์การตอบกลับรายการเดียวโดยสมบูรณ์
พร็อพเพอร์ตี้ของออบเจ็กต์ JSON หลักมีชื่อว่า replies
การตอบกลับจะแสดงผลในอาร์เรย์ โดยการตอบกลับแต่ละรายการสำหรับคำขอรายการใดรายการหนึ่งจะมีลำดับดัชนีเดียวกันกับคำขอที่เกี่ยวข้อง บางคำขอไม่มีการตอบกลับและการตอบกลับที่ดัชนีอาร์เรย์นั้นว่างเปล่า
ตัวอย่าง
ตัวอย่างโค้ดต่อไปนี้แสดงการใช้การจัดกลุ่มกับ Docs API
ส่งคำขอ
ตัวอย่างคำขอแบบกลุ่มนี้จะแสดงวิธีดำเนินการต่อไปนี้
แทรกข้อความ "สวัสดีโลก" ลงในส่วนต้นของเอกสารที่มีอยู่ โดยมีดัชนี
location
เป็น1
โดยใช้InsertTextRequest
อัปเดตคำว่า "สวัสดี" โดยใช้
UpdateTextStyleRequest
startIndex
และendIndex
กำหนดrange
ของข้อความที่จัดรูปแบบภายในกลุ่มใช้
textStyle
ให้กำหนดรูปแบบตัวอักษรเป็นตัวหนา และตั้งสีเป็นสีฟ้าสำหรับคำว่า "สวัสดี" เท่านั้นคุณใช้ช่อง
WriteControl
เพื่อควบคุมวิธีการส่งคำขอการเขียนได้ สำหรับข้อมูลเพิ่มเติม โปรดดู สร้างความสอดคล้องของสถานะด้วย WriteControl
{ "requests":[ { "insertText":{ "location":{ "index":1 }, "text":"Hello World" } }, { "updateTextStyle":{ "range":{ "startIndex":1, "endIndex":6 }, "textStyle":{ "bold":true, "foregroundColor":{ "color":{ "rgbColor":{ "blue":1 } } } }, "fields":"bold,foreground_color" } } ], "writeControl": { "requiredRevisionId": "REQUIRED_REVISION_ID" } }
แทนที่ REQUIRED_REVISION_ID ด้วยรหัสการแก้ไขของเอกสารที่จะใช้คำขอเขียน
คำตอบ
ตัวอย่างการตอบกลับแบบกลุ่มนี้จะแสดงข้อมูลเกี่ยวกับวิธีใช้คำขอย่อยแต่ละรายการภายในคำขอแบบกลุ่ม ทั้ง InsertTextRequest
หรือ UpdateTextStyleRequest
ต่างไม่มีการตอบกลับ ดังนั้นค่าดัชนีของอาร์เรย์ที่ [0] และ [1] จึงมีวงเล็บปีกกาที่ว่างเปล่า คำขอแบบกลุ่มจะแสดงออบเจ็กต์ WriteControl
ซึ่งแสดงวิธีดำเนินการตามคำขอ
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }