เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เข้าด้วยกันเพื่อลดจำนวนการเชื่อมต่อที่ไคลเอ็นต์ต้องสร้างขึ้น การจับคู่เป็นกลุ่มช่วยปรับปรุงประสิทธิภาพของแอปพลิเคชันด้วยการลดการเดินทางไป-กลับของเครือข่ายและเพิ่มอัตราการส่งข้อมูล
ภาพรวม
การเชื่อมต่อแต่ละครั้งของไคลเอ็นต์จะมีค่าใช้จ่ายในการดำเนินการจำนวนหนึ่ง Google สไลด์ API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์วางออบเจ็กต์คำขอหลายรายการ โดยแต่ละรายการจะระบุคำขอประเภทเดียวที่จะดำเนินการเป็นคำขอกลุ่มเดียว คำขอแบบกลุ่มจะเพิ่มประสิทธิภาพด้วยการรวมคำขอย่อยหลายรายการไว้ในการเรียกไปยังเซิร์ฟเวอร์ครั้งเดียว ซึ่งจะดึงการตอบกลับรายการเดียวกลับมา
เราขอแนะนำให้ผู้ใช้จัดกลุ่มคำขอหลายรายการไว้ด้วยกันเสมอ ตัวอย่างสถานการณ์ที่คุณใช้การทำงานแบบกลุ่มได้มีดังนี้
- คุณเพิ่งเริ่มต้นใช้ API และมีข้อมูลที่จะอัปโหลดมากมาย
- คุณต้องอัปเดตข้อมูลเมตาหรือพร็อพเพอร์ตี้ เช่น การจัดรูปแบบ ในออบเจ็กต์หลายรายการ
- คุณต้องลบออบเจ็กต์หลายรายการ
ข้อจำกัด การให้สิทธิ์ และการขึ้นต่อกัน
ต่อไปนี้เป็นรายการอื่นๆ ที่ควรพิจารณาเมื่อใช้การอัปเดตแบบกลุ่ม
- คำขอแบบกลุ่มแต่ละรายการรวมถึงคำขอย่อยทั้งหมดจะนับเป็นคำขอ API 1 รายการสำหรับขีดจำกัดการใช้งาน
- คำขอแบบกลุ่มจะได้รับการตรวจสอบสิทธิ์เพียงครั้งเดียว การตรวจสอบสิทธิ์รายการเดียวนี้จะมีผลกับออบเจ็กต์การอัปเดตเป็นกลุ่มทั้งหมดในคำขอ
- เซิร์ฟเวอร์จะประมวลผลคำขอย่อยในลำดับเดียวกันกับที่ปรากฏในคำขอแบบกลุ่ม คำขอย่อยรายการหลังอาจขึ้นอยู่กับการดำเนินการที่ทำระหว่างคำขอย่อยก่อนหน้า ตัวอย่างเช่น ในคำขอแบบกลุ่มเดียวกัน ผู้ใช้จะแทรกข้อความลงในเอกสารที่มีอยู่และจัดสไตล์ได้
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียกใช้เมธอด batchUpdate
1 รายการที่มีคำขอย่อยหลายรายการ เช่น เพิ่มแล้วจัดรูปแบบงานนำเสนอ
คำขอแต่ละรายการจะได้รับการตรวจสอบก่อนนำไปใช้ ระบบจะนำคำขอย่อยทั้งหมดในการอัปเดตเป็นกลุ่มไปใช้แบบอะตอม กล่าวคือ หากคำขอใดไม่ถูกต้อง การอัปเดตทั้งหมดจะไม่สำเร็จและไม่มีการเปลี่ยนแปลงใดๆ (ที่อาจต้องอาศัย)
บางคำขอมีคำตอบพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ตัวอย่างเช่น คำขอการอัปเดตแบบกลุ่มทั้งหมดเพื่อเพิ่มออบเจ็กต์จะแสดงคำตอบเพื่อให้คุณเข้าถึงข้อมูลเมตาของออบเจ็กต์ที่เพิ่มใหม่ เช่น รหัสหรือชื่อ
ด้วยวิธีการนี้ คุณจะสร้างเอกสาร Google ทั้งฉบับโดยใช้คำขออัปเดตกลุ่ม API รายการเดียวที่มีคำขอย่อยหลายรายการได้
รูปแบบคำขอแบบกลุ่ม
คำขอคือคำขอ JSON รายการเดียวที่มีคำขอย่อยหลายรายการที่ฝังอยู่ โดยมีพร็อพเพอร์ตี้ที่จำเป็น 1 รายการคือ requests
ระบบจะสร้างคำขอในอาร์เรย์ของคำขอแต่ละรายการ แต่ละคำขอใช้ JSON เพื่อแสดงถึงออบเจ็กต์คำขอและเก็บพร็อพเพอร์ตี้ของออบเจ็กต์นั้นๆ
รูปแบบการตอบกลับแบบกลุ่ม
รูปแบบการตอบกลับสำหรับคำขอแบบกลุ่มคล้ายกับรูปแบบคำขอ การตอบกลับของเซิร์ฟเวอร์ประกอบด้วยการตอบกลับที่สมบูรณ์ของออบเจ็กต์การตอบกลับรายการเดียว
พร็อพเพอร์ตี้ของออบเจ็กต์ JSON หลักมีชื่อว่า replies
ระบบจะแสดงผลการตอบกลับในอาร์เรย์ โดยที่การตอบกลับคำขอแต่ละรายการมีลำดับดัชนีเดียวกันกับคำขอที่เกี่ยวข้อง คำขอบางรายการไม่มีการตอบกลับและการตอบกลับที่ดัชนีอาร์เรย์นั้นว่างเปล่า
ตัวอย่าง
ตัวอย่างโค้ดต่อไปนี้แสดงการใช้การทำงานแบบกลุ่มกับ Slides API
ส่งคำขอ
ตัวอย่างคำขอแบบกลุ่มนี้แสดงวิธีดำเนินการต่อไปนี้
เพิ่มทรัพยากร
presentations.pages
ไปยังงานนำเสนอที่มีอยู่ โดยมีinsertionIndex
เป็น1
โดยใช้เมธอดCreateSlideRequest
เพิ่ม
shapeType
ประเภทTEXT_BOX
ลงในสไลด์ใหม่โดยใช้เมธอดCreateShapeRequest
แทรกข้อความ "Hello World" ลงในช่องใหม่โดยใช้เมธอด
InsertTextRequest
{ "requests":[ { "createSlide":{ "insertionIndex":1, "objectId":"newSlide" } }, { "createShape":{ "elementProperties":{ "pageObjectId":"newSlide", "size":{ "height":{ "magnitude":50, "unit":"PT" }, "width":{ "magnitude":200, "unit":"PT" } } }, "shapeType":"TEXT_BOX", "objectId":"newTextBox" } }, { "insertText":{ "objectId":"newTextBox", "text":"Hello World" } } ] }
คำตอบ
ตัวอย่างการตอบกลับแบบกลุ่มนี้จะแสดงข้อมูลเกี่ยวกับวิธีใช้คำขอย่อยแต่ละรายการภายในคำขอแบบกลุ่ม โปรดทราบว่าเมธอด InsertTextRequest
ไม่มีการตอบสนอง ดังนั้นค่าดัชนีของอาร์เรย์ที่ [2] จึงมีวงเล็บปีกกาที่ว่างเปล่า คำขอแบบกลุ่มจะแสดงพร็อพเพอร์ตี้ WriteControl
ซึ่งแสดงวิธีการดำเนินการคำขอการเขียน
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }