คำขอแบบกลุ่ม

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

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

ภาพรวม

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

ตัวอย่างสถานการณ์ที่คุณอาจต้องการใช้การแยกกลุ่ม

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

ในแต่ละกรณี คุณสามารถจัดกลุ่มการเรียกแต่ละรายการไว้ในคําขอ HTTP รายการเดียวแทนการส่งการเรียกแต่ละรายการแยกกัน คำขอภายในทั้งหมดต้องส่งไปยัง Google API เดียวกัน

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

หมายเหตุ: ระบบการประมวลผลเป็นกลุ่มสําหรับ Gmail API ใช้ไวยากรณ์เดียวกับระบบการประมวลผลเป็นกลุ่มของ OData แต่ความหมายจะแตกต่างกัน

หมายเหตุ: การส่งกลุ่มที่มีขนาดใหญ่มีแนวโน้มที่จะทริกเกอร์การจำกัดอัตราการส่ง ไม่แนะนำให้ส่งคำขอแบบเป็นกลุ่มที่มีจำนวนมากกว่า 50 รายการ

รายละเอียดการประมวลผลเป็นกลุ่ม

คำขอกลุ่มประกอบด้วยการเรียก API หลายรายการที่รวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งสามารถส่งไปยัง batchPath ที่ระบุไว้ในเอกสารการค้นพบ API เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้จะอธิบายไวยากรณ์ของกลุ่มอย่างละเอียด โดยจะมีตัวอย่างให้ดูในภายหลัง

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

รูปแบบคำขอแบบเป็นกลุ่ม

คำขอกลุ่มคือคำขอ HTTP มาตรฐานคำขอเดียวที่มีการเรียกใช้ Gmail API หลายรายการโดยใช้ประเภทเนื้อหา multipart/mixed ภายในคําขอ HTTP หลักนั้น แต่ละส่วนจะมีคําขอ HTTP ที่ฝังอยู่

แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว Content-Type: application/http HTTP ของตัวเอง และอาจมีส่วนหัว Content-ID เสริมด้วย อย่างไรก็ตาม ส่วนหัวของส่วนมีไว้เพื่อระบุจุดเริ่มต้นของส่วนเท่านั้น โดยแยกจากคำขอที่ฝังอยู่ หลังจากเซิร์ฟเวอร์เปิดคำขอกลุ่มออกเป็นคำขอแยกต่างหาก ระบบจะไม่สนใจส่วนหัวของส่วน

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

ส่วนหัว HTTP สำหรับคำขอกลุ่มภายนอก ยกเว้นส่วนหัว Content- เช่น Content-Type จะมีผลกับคำขอทุกรายการในกลุ่ม หากคุณระบุส่วนหัว HTTP หนึ่งๆ ทั้งในคําขอภายนอกและการเรียกแต่ละรายการ ค่าของส่วนหัวการเรียกแต่ละรายการจะลบล้างค่าของส่วนหัวคําขอกลุ่มภายนอก ส่วนส่วนหัวของการโทรแต่ละครั้งจะมีผลกับการโทรครั้งนั้นเท่านั้น

ตัวอย่างเช่น หากคุณระบุส่วนหัวการให้สิทธิ์สําหรับการเรียกใช้ที่เฉพาะเจาะจง ส่วนหัวนั้นจะมีผลกับการเรียกใช้นั้นเท่านั้น หากคุณระบุส่วนหัวการให้สิทธิ์สําหรับคําขอภายนอก ส่วนหัวนั้นจะมีผลกับคําขอแต่ละรายการ เว้นแต่ว่าจะมีการลบล้างด้วยส่วนหัวการให้สิทธิ์ของตนเอง

เมื่อเซิร์ฟเวอร์ได้รับคําขอแบบเป็นกลุ่ม ก็จะใช้พารามิเตอร์การค้นหาและส่วนหัวของคําขอด้านนอก (ตามความเหมาะสม) กับแต่ละส่วน จากนั้นจะถือว่าแต่ละส่วนเป็นคําขอ HTTP แยกกัน

การตอบสนองต่อคําขอแบบเป็นกลุ่ม

การตอบกลับของเซิร์ฟเวอร์คือการตอบกลับ HTTP มาตรฐานรายการเดียวที่มีประเภทเนื้อหา multipart/mixed แต่ละส่วนเป็นการตอบกลับคําขอรายการใดรายการหนึ่งในคําขอแบบเป็นกลุ่มตามลําดับเดียวกับคําขอ

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

หากส่วนใดส่วนหนึ่งของคําขอมีส่วนหัว Content-ID ส่วนที่เกี่ยวข้องของการตอบกลับก็จะมีส่วนหัว Content-ID ที่ตรงกัน โดยมีสตริง response- นำหน้าค่าเดิม ดังที่แสดงในตัวอย่างต่อไปนี้

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

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้การแยกกลุ่มกับ API สาธิตทั่วไป (สมมติ) ที่เรียกว่า Farm API อย่างไรก็ตาม แนวคิดเดียวกันนี้จะใช้กับ Gmail API ได้

ตัวอย่างคำขอแบบเป็นกลุ่ม

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:[e-mail]>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

ตัวอย่างการตอบกลับแบบเป็นกลุ่ม

นี่คือการตอบกลับคำขอตัวอย่างในส่วนก่อนหน้า

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:[e-mail]>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:[e-mail]>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--