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

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

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

คำขอแบบกลุ่มคือคำขอ 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:[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--