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

ภาพรวม

การเชื่อมต่อ 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 รายการ ไม่ใช่คำขอรายการเดียว ระบบจะแยกคำขอแบบกลุ่มออกเป็นชุดคำขอก่อนประมวลผล

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

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

แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว HTTP Content-Type: application/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 ครั้งในคำขอเดียวไม่ได้ แต่ให้ส่งการเรียกครั้งแรกด้วยตัวเอง แล้วรอการตอบกลับของการเรียกครั้งแรกก่อนที่จะส่งการเรียกครั้งที่ 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:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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:12930812@barnyard.example.com>

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

--batch_foobarbaz--