เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เข้าด้วยกันเพื่อลดจำนวนการเชื่อมต่อที่ไคลเอ็นต์ต้องสร้าง การรวมกลุ่มจะช่วยเพิ่มประสิทธิภาพของแอปพลิเคชันด้วยการลดการเดินทางไป-กลับของเครือข่ายและเพิ่มอัตราการส่งข้อมูล
ภาพรวม
การเชื่อมต่อแต่ละครั้งที่ไคลเอ็นต์ของคุณทำให้เกิดค่าใช้จ่ายในการดำเนินการจำนวนหนึ่ง Google Docs API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์วางออบเจ็กต์คำขอหลายรายการ โดยแต่ละรายการจะระบุคำขอประเภทเดียวที่จะดำเนินการลงในคำขอกลุ่มเดียว คำขอแบบกลุ่มจะเพิ่มประสิทธิภาพได้โดยการรวมคำขอย่อยหลายรายการไว้ในการเรียกเซิร์ฟเวอร์รายการเดียว และดึงการตอบกลับรายการเดียวกลับมา
เราขอแนะนำให้ผู้ใช้จัดกลุ่มคำขอหลายรายการไว้ด้วยกันเสมอ ตัวอย่างสถานการณ์ที่คุณใช้การทำงานแบบกลุ่มได้มีดังนี้
- คุณเพิ่งเริ่มใช้ API และมีข้อมูลที่ต้องอัปโหลดมากมาย
- คุณต้องอัปเดตข้อมูลเมตาหรือพร็อพเพอร์ตี้ เช่น การจัดรูปแบบ ในออบเจ็กต์หลายรายการ
- คุณต้องลบออบเจ็กต์หลายรายการ
ข้อจำกัด การให้สิทธิ์ และการพึ่งพา
ต่อไปนี้เป็นรายการอื่นๆ ที่ควรพิจารณาเมื่อใช้การอัปเดตแบบกลุ่ม
- คำขอกลุ่มแต่ละรายการ รวมถึงคำขอย่อยทั้งหมด จะนับเป็นคำขอ API 1 รายการสำหรับขีดจำกัดการใช้งาน
- คำขอแบบกลุ่มจะได้รับการตรวจสอบสิทธิ์เพียงครั้งเดียว การตรวจสอบสิทธิ์รายการเดียวนี้จะมีผลกับออบเจ็กต์การอัปเดตแบบกลุ่มทั้งหมดในคำขอ
- เซิร์ฟเวอร์ประมวลผลคำขอย่อยในลำดับเดียวกับที่ปรากฏในคำขอแบบกลุ่ม คำขอย่อยในภายหลังอาจขึ้นอยู่กับการดำเนินการที่เกิดขึ้นระหว่างคำขอย่อยก่อนหน้านี้ เช่น ในคำขอแบบกลุ่มเดียวกัน ผู้ใช้จะแทรกข้อความลงในเอกสารที่มีอยู่และจัดรูปแบบได้
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียกใช้เมธอด batchUpdate
1 รายการที่มีคำขอย่อยหลายรายการ เช่น เพิ่มและจัดรูปแบบเอกสาร
คำขอแต่ละรายการจะได้รับการตรวจสอบก่อนนำไปใช้ คำขอย่อยทั้งหมดในการอัปเดตเป็นกลุ่มจะนำไปใช้แยกกัน กล่าวคือ หากคำขอใดไม่ถูกต้อง การอัปเดตทั้งหมดจะไม่สำเร็จ และการเปลี่ยนแปลงใดๆ ที่ (อาจไม่เกี่ยวข้อง) ไม่มีผล
บางคำขอจะมีคำตอบพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ เช่น คำขออัปเดตแบบกลุ่มทั้งหมดที่จะเพิ่มออบเจ็กต์จะแสดงการตอบกลับเพื่อให้คุณเข้าถึงข้อมูลเมตาของออบเจ็กต์ที่เพิ่มใหม่ เช่น รหัสหรือชื่อได้
ด้วยวิธีการนี้ คุณจะสร้างเอกสาร Google ทั้งฉบับโดยใช้คำขออัปเดตกลุ่ม API รายการเดียวที่มีคำขอย่อยหลายรายการได้
รูปแบบของคำขอแบบกลุ่ม
คำขอคือคำขอ JSON คำขอเดียวที่มีคำขอย่อยที่ฝังอยู่หลายรายการซึ่งมีพร็อพเพอร์ตี้ที่จำเป็น 1 รายการ: requests
คําขอจะสร้างขึ้นเป็นอาร์เรย์ของคําขอแต่ละรายการ แต่ละคำขอใช้ JSON เพื่อแสดงออบเจ็กต์คำขอและเก็บพร็อพเพอร์ตี้ของออบเจ็กต์นั้นๆ
รูปแบบของการตอบกลับแบบกลุ่ม
รูปแบบการตอบกลับสำหรับคำขอแบบกลุ่มคล้ายกับรูปแบบคำขอ การตอบกลับของเซิร์ฟเวอร์มีการตอบกลับที่สมบูรณ์ของออบเจ็กต์การตอบกลับรายการเดียว
พร็อพเพอร์ตี้ของออบเจ็กต์ JSON หลักมีชื่อว่า replies
การตอบกลับจะแสดงผลในอาร์เรย์ โดยที่การตอบสนองต่อคำขอใดคำขอหนึ่งที่มีลำดับดัชนีเดียวกับคำขอที่เกี่ยวข้อง คำขอบางรายการไม่มีการตอบกลับและการตอบกลับที่ดัชนีอาร์เรย์นั้นว่างเปล่า
ตัวอย่าง
ตัวอย่างโค้ดต่อไปนี้แสดงการใช้งานการทำงานแบบกลุ่มกับ Docs API
ส่งคำขอ
ตัวอย่างคำขอแบบกลุ่มนี้แสดงวิธีต่อไปนี้
แทรกข้อความ " Hello World" ด้านหน้าเอกสารที่มีอยู่ซึ่งมีดัชนี
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` }