เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API ไว้ด้วยกันเพื่อลดจำนวน กับการเชื่อมต่อที่ลูกค้าจะต้องทำ การทำงานเป็นกลุ่มช่วยปรับปรุง ประสิทธิภาพด้วยการลดการเดินทางไปกลับของเครือข่ายและเพิ่มอัตราการส่งข้อมูล
ภาพรวม
การเชื่อมต่อแต่ละครั้งที่ไคลเอ็นต์ทำให้เกิดค่าใช้จ่ายในการดำเนินการหนึ่งๆ Google Sheets API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์วางไฟล์หลายรายการได้ แต่ละออบเจ็กต์จะระบุคำขอประเภทเดียวที่จะดำเนินการ ให้เป็นคำขอกลุ่มเดียว คำขอแบบกลุ่มช่วยเพิ่มประสิทธิภาพได้ การรวมคำขอย่อยหลายรายการไว้ในการเรียกไปยังเซิร์ฟเวอร์ครั้งเดียว การเรียก การตอบกลับเพียงครั้งเดียว
เราขอแนะนำให้ผู้ใช้รวบรวมคำขอหลายรายการไว้ด้วยกันเสมอ นี่คือบางส่วน ตัวอย่างสถานการณ์ที่คุณสามารถใช้การจัดกลุ่มได้
- คุณเพิ่งเริ่มใช้ API และมีข้อมูลที่ต้องอัปโหลดจำนวนมาก
- คุณต้องอัปเดตข้อมูลเมตาหรือพร็อพเพอร์ตี้ เช่น การจัดรูปแบบ ในหลายแพลตฟอร์ม ออบเจ็กต์
- คุณต้องลบออบเจ็กต์หลายรายการ
ขีดจำกัด การให้สิทธิ์ และ ข้อควรพิจารณาเกี่ยวกับทรัพยากร Dependency
ต่อไปนี้เป็นรายการอื่นๆ ที่ควรพิจารณาเมื่อใช้การอัปเดตเป็นกลุ่ม
- คำขอแบบกลุ่มแต่ละรายการ รวมถึงคำขอย่อยทั้งหมด จะนับเป็น API 1 รายการ ในขีดจำกัดการใช้งาน
- คำขอแบบกลุ่มจะได้รับการตรวจสอบสิทธิ์ครั้งเดียว การตรวจสอบสิทธิ์รายการเดียวนี้มีผล ไปยังออบเจ็กต์อัปเดตแบบกลุ่มทั้งหมดในคำขอ
- เซิร์ฟเวอร์จะประมวลผลคำขอย่อยในลำดับเดียวกันกับที่ปรากฏใน คำขอแบบกลุ่ม คำขอย่อยในภายหลังอาจขึ้นอยู่กับการดำเนินการที่ทำในระหว่าง คำขอย่อยก่อนหน้านี้ ตัวอย่างเช่น ในคำขอแบบกลุ่มเดียวกัน ผู้ใช้สามารถ แทรกข้อความลงในเอกสารที่มีอยู่ แล้วจัดรูปแบบ
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียกใช้เมธอด batchUpdate
1 ครั้ง
พร้อมกับคำขอย่อยหลายรายการเพื่อนำไปเพิ่มและจัดรูปแบบสเปรดชีต
คำขอแต่ละรายการจะได้รับการตรวจสอบก่อนนำไปใช้ คำขอย่อยทั้งหมดในกลุ่ม แล้วนำการอัปเดตมาปรับใช้โดยอัตโนมัติ กล่าวคือ หากมีคำขอที่ไม่ถูกต้อง ระบบจะ การอัปเดตทั้งหมดไม่สำเร็จและไม่มีสิ่งใดเลย (อาจต้องใช้) ใช้การเปลี่ยนแปลงแล้ว
คำขอบางรายการจะให้คำตอบพร้อมข้อมูลเกี่ยวกับคำขอที่ใช้ ตัวอย่างเช่น คำขออัปเดตแบบกลุ่มทั้งหมดเพื่อเพิ่มออบเจ็กต์จะแสดงการตอบกลับ ดังนั้น คุณสามารถเข้าถึงข้อมูลเมตาของอ็อบเจกต์ที่เพิ่มเข้ามาใหม่ เช่น ID หรือ ชื่อ
วิธีนี้จะช่วยให้คุณสร้างเอกสาร Google ทั้งฉบับโดยใช้ API เดียวได้ คำขออัปเดตเป็นกลุ่มที่มีคําขอย่อยหลายรายการ
รูปแบบของคำขอแบบกลุ่ม
คำขอคือคำขอ JSON รายการเดียวที่มีหลายรายการ
คำขอย่อยที่ฝังอยู่ซึ่งมีพร็อพเพอร์ตี้ที่จำเป็น 1 รายการ: requests
จะสร้างขึ้นในอาร์เรย์ของคำขอแต่ละรายการ คำขอแต่ละรายการใช้
JSON เพื่อแสดงออบเจ็กต์คำขอและมีพร็อพเพอร์ตี้ของออบเจ็กต์
รูปแบบของการตอบกลับแบบกลุ่ม
รูปแบบการตอบกลับสำหรับคำขอแบบกลุ่มจะคล้ายกับ รูปแบบคำขอ การตอบกลับของเซิร์ฟเวอร์จะมีการตอบกลับที่สมบูรณ์ของ ออบเจ็กต์การตอบกลับ
พร็อพเพอร์ตี้ของออบเจ็กต์ JSON หลักมีชื่อว่า replies
คำตอบ
จะแสดงผลในอาร์เรย์ โดยแต่ละการตอบสนองต่อ 1 คำขอจะอยู่ใน
ลำดับดัชนีเดียวกับคำขอที่เกี่ยวข้อง คำขอบางรายการไม่มี
และการตอบกลับที่ดัชนีอาร์เรย์นั้นว่างเปล่า
ตัวอย่าง
ตัวอย่างต่อไปนี้แสดงการใช้งานแบบกลุ่มกับ Sheets API
ส่งคำขอ
ตัวอย่างคำขอแบบกลุ่มนี้จะแสดงวิธีดำเนินการต่อไปนี้
- เพิ่มชีตในสเปรดชีตที่มีอยู่ โดยมี
sheetId
เป็น 12345 โดยใช้AddSheetRequest
- เพิ่มข้อมูลในชีตใหม่ โดยเริ่มจากเซลล์ A1 โดยใช้
UpdateCellsRequest
- เพิ่ม
namedRange
หรือมุมมองตัวกรองในชีตใหม่
การเพิ่มรหัสชีตในคำขอจะทำให้ผู้ใช้ใช้รหัสชีตสําหรับคําขอย่อยอื่นๆ ในการเรียก API เดียวกันได้ ซึ่งจะช่วยปรับปรุงประสิทธิภาพโดยการหลีกเลี่ยงวงจรการเขียน-อ่าน-เขียน
โปรดดูรายการประเภทคำขออัปเดตเป็นกลุ่มที่จัดกลุ่มไว้เป็นหมวดหมู่ต่างๆ ได้ในการดำเนินการอัปเดตเป็นกลุ่ม
{ "requests":[ { "addSheet":{ "properties":{ "sheetId":123456 } } }, { "updateCells":{ "start":{ "sheetId":123456 }, "rows":[ { "values":[ { "userEnteredValue":{ "stringValue":"hello" } } ] }, { "values":[ { "userEnteredValue":{ "stringValue":"world" } } ] } ], "fields":"userEnteredValue" } }, { "addNamedRange":{ "namedRange":{ "name":"newRange", "range":{ "sheetId":123456, "endRowIndex":2 } } } } ] }
คำตอบ
ตัวอย่างการตอบกลับเป็นกลุ่มนี้จะแสดงข้อมูลเกี่ยวกับวิธีใช้คำขอย่อยแต่ละรายการภายในคำขอแบบกลุ่ม โปรดทราบว่า UpdateCellsRequest
ไม่มีการตอบกลับ ค่าดัชนีของอาร์เรย์ที่ [1] ประกอบด้วยวงเล็บปีกกาว่าง
"replies":[ { "addSheet":{ "properties":{ "sheetId":123456, "title":"Sheet3", "index":2, "sheetType":"GRID", "gridProperties":{ "rowCount":1000, "columnCount":26 } } } }, { }, { "addNamedRange":{ "namedRange":{ "namedRangeId":"2104325079", "name":"newRange", "range":{ "sheetId":123456, "startRowIndex":0, "endRowIndex":2, "startColumnIndex":0, "endColumnIndex":26 } } } } ]