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

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

ภาพรวม

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

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

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

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

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

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

รายละเอียดแบทช์

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

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

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

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

รูปแบบของคำขอแบบกลุ่ม

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

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

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

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

ตัวอย่าง

ตัวอย่างโค้ดต่อไปนี้แสดงการใช้การประมวลผลแบบกลุ่มกับ Docs API

ส่งคำขอ

คำขอแบบกลุ่มตัวอย่างนี้แสดงวิธีดำเนินการต่อไปนี้

  • แทรกข้อความ "Hello World" ที่จุดเริ่มต้นของเอกสารที่มีอยู่ โดยมี ดัชนี location ของ 1 โดยใช้ InsertTextRequest

  • อัปเดตคำว่า "Hello" โดยใช้ UpdateTextStyleRequest startIndex และ endIndex กำหนด range ของข้อความที่จัดรูปแบบภายใน กลุ่ม

  • ใช้ textStyle กำหนดรูปแบบแบบอักษรเป็นตัวหนาและสีเป็นสีน้ำเงินสำหรับคำว่า "Hello" เท่านั้น

  • การใช้ฟิลด์ WriteControl จะช่วยให้คุณควบคุมวิธีดำเนินการคำขอเขียนได้ ดูข้อมูลเพิ่มเติมได้ที่สร้างความสอดคล้องของสถานะด้วย WriteControl

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "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"
  }
}

แทนที่ TAB_ID และ REQUIRED_REVISION_ID ด้วยรหัสแท็บและรหัสการแก้ไขตามลำดับของเอกสารที่ใช้คำขอเขียน

การตอบกลับ

การตอบกลับแบบกลุ่มตัวอย่างนี้จะแสดงข้อมูลเกี่ยวกับวิธีใช้คำขอแบบกลุ่มย่อยแต่ละรายการภายในคำขอแบบกลุ่ม ทั้ง InsertTextRequest และ UpdateTextStyleRequest ไม่มีการตอบกลับ ดังนั้นค่าดัชนีของอาร์เรย์ที่ [0] และ [1] จึงประกอบด้วย วงเล็บปีกกาว่าง คำขอแบบกลุ่มจะแสดงออบเจ็กต์ WriteControl ซึ่งแสดงวิธีดำเนินการคำขอ

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}