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

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