เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API ไว้ด้วยกันเพื่อลดจำนวนการเชื่อมต่อ HTTP ให้ลูกค้ามีส่วนร่วม
เอกสารนี้เกี่ยวข้องกับการส่งคำขอแบบกลุ่มโดยส่ง คำขอ HTTP แต่หากคุณกำลังใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคำขอแบบกลุ่ม โปรดดูเอกสารประกอบของไลบรารีไคลเอ็นต์
ภาพรวม
การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์สร้างค่าใช้จ่ายในการดำเนินการตามจำนวนที่กำหนด Directory API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์ใส่การเรียก API หลายรายการลงในคำขอ HTTP รายการเดียวได้
ตัวอย่างสถานการณ์ที่คุณอาจต้องใช้การรวมกลุ่มมีดังนี้
- คุณเพิ่งเริ่มใช้ API และมีข้อมูลที่จะอัปโหลดจำนวนมาก
- ผู้ใช้ทำการเปลี่ยนแปลงข้อมูลขณะที่แอปพลิเคชันของคุณออฟไลน์ (ตัดการเชื่อมต่อจากอินเทอร์เน็ต) ดังนั้นแอปพลิเคชันของคุณจำเป็นต้องซิงค์ข้อมูลในเครื่องกับเซิร์ฟเวอร์ด้วยการส่งการอัปเดตและลบข้อมูลจำนวนมาก
ในแต่ละกรณี คุณสามารถจัดกลุ่มการเรียกไว้ด้วยกันเป็นคำขอ HTTP รายการเดียว แทนการส่งแต่ละการเรียกแยกกัน คำขอภายในทั้งหมดจะต้องไปยัง Google API เดียวกัน
คุณจำกัดการโทรไว้ที่ 1,000 ครั้งในคำขอแบบกลุ่มเดียว หากคุณต้องทำการเรียกมากกว่าจำนวนนั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ
หมายเหตุ: ระบบแบบกลุ่มสำหรับ Directory API ใช้ไวยากรณ์เดียวกันกับระบบการประมวลผลแบบกลุ่ม OData แต่ความหมายแตกต่างกัน
รายละเอียดกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการรวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งจะส่งไปยัง batchPath
ที่ระบุไว้ในเอกสารการค้นพบ API ได้ เส้นทางเริ่มต้นคือ /batch/api_name/api_version
ส่วนนี้จะอธิบายไวยากรณ์แบบกลุ่มโดยละเอียด จะมีตัวอย่างในภายหลัง
หมายเหตุ: ชุดคำขอ n ที่จัดกลุ่มไว้ด้วยกันจะนับรวมในขีดจำกัดการใช้งานเป็นคำขอ n ไม่ใช่คำขอเดียว ระบบจะแยกคำขอเป็นกลุ่มออกเป็นชุดคำขอก่อนประมวลผล
รูปแบบของคำขอแบบกลุ่ม
คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก Directory 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 แต่ไดเรกทอรี 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--