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

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

ภาพรวม

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

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

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

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

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

  • คำขอกลุ่มแต่ละรายการ รวมถึงคำขอย่อยทั้งหมด จะนับเป็นคำขอ 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,
               "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`
}