คําขอแบบกลุ่ม

เอกสารนี้แสดงวิธีเรียก API แบบเป็นกลุ่มเพื่อลดจำนวนการเชื่อมต่อที่ไคลเอ็นต์ต้องสร้าง การแบ่งกลุ่มสามารถปรับปรุงประสิทธิภาพของแอปพลิเคชันได้โดยลดจำนวนครั้งที่ต้องส่งข้อมูลไปมาทางเครือข่ายและเพิ่มปริมาณข้อมูลที่ได้รับ

ภาพรวม

การเชื่อมต่อแต่ละครั้งที่ลูกค้าทำจะทำให้เกิดค่าใช้จ่ายเพิ่มเติมจำนวนหนึ่ง Google Slides API รองรับการรวมกลุ่มเพื่อให้ไคลเอ็นต์สามารถส่งออบเจ็กต์คำขอหลายรายการ โดยแต่ละรายการจะระบุคำขอประเภทเดียวที่จะดำเนินการ ไปยังคำขอแบบกลุ่มรายการเดียว คำขอแบบเป็นกลุ่มช่วยเพิ่มประสิทธิภาพได้ด้วยการรวมคำขอย่อยหลายรายการไว้ในการเรียกใช้เซิร์ฟเวอร์ครั้งเดียว เพื่อดึงข้อมูลการตอบกลับรายการเดียว

เราขอแนะนำให้ผู้ใช้ส่งคำขอหลายรายการพร้อมกันเสมอ ตัวอย่างสถานการณ์ที่คุณสามารถใช้การแยกกลุ่มมีดังนี้

• คุณเพิ่งเริ่มใช้ API และมีข้อมูลจำนวนมากที่จะอัปโหลด
• คุณต้องอัปเดตข้อมูลเมตาหรือพร็อพเพอร์ตี้ เช่น การจัดรูปแบบ ในออบเจ็กต์หลายรายการ
• คุณต้องลบออบเจ็กต์หลายรายการ

ข้อควรพิจารณาเกี่ยวกับขีดจํากัด การให้สิทธิ์ และทรัพยากร Dependency

รายการอื่นๆ ที่ควรพิจารณาเมื่อใช้การอัปเดตแบบเป็นกลุ่มมีดังนี้

• คำขอแบบกลุ่มแต่ละรายการ รวมถึงคำขอย่อยทั้งหมดจะนับเป็นคำขอ API 1 รายการตามขีดจำกัดการใช้งาน
• ระบบจะตรวจสอบสิทธิ์คําขอแบบเป็นกลุ่มเพียงครั้งเดียว การตรวจสอบสิทธิ์ครั้งเดียวนี้จะมีผลกับออบเจ็กต์การอัปเดตแบบเป็นกลุ่มทั้งหมดในคำขอ
• เซิร์ฟเวอร์จะประมวลผลคำขอย่อยตามลำดับเดียวกันกับที่ปรากฏในคำขอกลุ่ม คำขอย่อยที่ส่งมาภายหลังอาจขึ้นอยู่กับการดำเนินการที่ทำในคำขอย่อยก่อนหน้านี้ เช่น ในคำขอแบบเป็นกลุ่มเดียวกัน ผู้ใช้สามารถแทรกข้อความลงในเอกสารที่มีอยู่ แล้วจัดรูปแบบข้อความได้

รายละเอียดการประมวลผลเป็นกลุ่ม

คำขอแบบกลุ่มประกอบด้วยbatchUpdateการเรียกใช้เมธอด 1 ครั้ง ที่มีคำขอย่อยหลายรายการ เช่น เพิ่มและจัดรูปแบบงานนำเสนอ

ระบบจะตรวจสอบคําขอแต่ละรายการก่อนนำไปใช้ ระบบจะใช้คำขอย่อยทั้งหมดในการอัปเดตแบบเป็นกลุ่มพร้อมกัน กล่าวคือ หากคำขอใดไม่ถูกต้อง การอัปเดตทั้งหมดจะไม่สำเร็จและจะไม่มีการใช้การเปลี่ยนแปลง (ที่อาจเกี่ยวข้อง) ใดๆ

คำขอบางรายการจะตอบกลับพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ตัวอย่างเช่น คำขออัปเดตแบบเป็นกลุ่มทั้งหมดเพื่อเพิ่มออบเจ็กต์จะแสดงผลลัพธ์เพื่อให้คุณเข้าถึงข้อมูลเมตาของออบเจ็กต์ที่เพิ่มใหม่ได้ เช่น รหัสหรือชื่อ

แนวทางนี้ช่วยให้คุณสร้างเอกสาร Google ทั้งหมดได้โดยใช้ API รายการเดียว โดยส่งคำขออัปเดตแบบเป็นกลุ่มที่มีคำขอย่อยหลายรายการ

รูปแบบคำขอแบบเป็นกลุ่ม

คําขอคือคําขอ JSON รายการเดียวที่มีคําขอย่อยที่ฝังอยู่หลายรายการซึ่งมีพร็อพเพอร์ตี้ที่ต้องระบุ 1 รายการ ได้แก่ requests คำขอจะสร้างขึ้นเป็นอาร์เรย์ของคำขอแต่ละรายการ คำขอแต่ละรายการใช้ JSON เพื่อแสดงออบเจ็กต์คำขอและเพื่อเก็บพร็อพเพอร์ตี้

รูปแบบของการตอบกลับแบบเป็นกลุ่ม

รูปแบบคำตอบสำหรับคำขอแบบเป็นกลุ่มจะคล้ายกับรูปแบบคำขอ การตอบกลับของเซิร์ฟเวอร์มีการตอบกลับที่สมบูรณ์ของออบเจ็กต์การตอบกลับรายการเดียว

พร็อพเพอร์ตี้ของออบเจ็กต์ JSON หลักมีชื่อว่า replies ระบบจะแสดงคําตอบเป็นอาร์เรย์ โดยคําตอบแต่ละรายการสําหรับคําขอรายการใดรายการหนึ่งจะอยู่ในลําดับดัชนีเดียวกันกับคําขอที่เกี่ยวข้อง คำขอบางรายการไม่มีการตอบกลับและคำตอบที่อินเด็กซ์อาร์เรย์นั้นว่างเปล่า

ตัวอย่าง

ตัวอย่างโค้ดต่อไปนี้แสดงการใช้การแยกกลุ่มกับ PowerPoint 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
   }
}