เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก 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 } }