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