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

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

ภาพรวม

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

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

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

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

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

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

รายละเอียดกลุ่ม

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

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

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

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

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

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

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

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

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

ตัวอย่าง

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

ส่งคำขอ

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

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

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

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

  • การใช้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] ประกอบด้วย ของวงเล็บปีกกาว่างทั้ง 2 แบบ คำขอแบบกลุ่มจะแสดงออบเจ็กต์ WriteControl ซึ่งจะแสดงวิธีการดำเนินการกับคำขอ

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