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