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

เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เข้าด้วยกันเพื่อลดจำนวนการเชื่อมต่อ HTTP ที่ไคลเอ็นต์ต้องสร้าง

เอกสารนี้เกี่ยวกับการสร้างคำขอแบบกลุ่มโดยการส่งคำขอ HTTP แต่หากคุณใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคำขอแบบกลุ่ม โปรดดูเอกสารประกอบของไลบรารีไคลเอ็นต์

ภาพรวม

การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์ทำให้เกิดโอเวอร์เฮดจำนวนหนึ่ง People API รองรับการทำงานแบบกลุ่มเพื่อให้ไคลเอ็นต์ใส่การเรียก API หลายรายการไว้ในคำขอ HTTP รายการเดียวได้

ตัวอย่างสถานการณ์ที่คุณอาจต้องใช้การทำงานแบบกลุ่มมีดังนี้

  • คุณเพิ่งเริ่มต้นใช้ API และมีข้อมูลที่จะอัปโหลดมากมาย
  • ผู้ใช้ได้ทำการเปลี่ยนแปลงข้อมูลในขณะที่แอปพลิเคชันออฟไลน์ (ยกเลิกการเชื่อมต่อจากอินเทอร์เน็ต) ดังนั้นแอปพลิเคชันของคุณจึงต้องซิงค์ข้อมูลในเครื่องกับเซิร์ฟเวอร์โดยส่งการอัปเดตและลบจำนวนมาก

ในแต่ละกรณี คุณสามารถจัดกลุ่มการโทรเข้าด้วยกันเป็นคำขอ HTTP รายการเดียว แทนการส่งแต่ละสายแยกกันได้ คำขอภายในทั้งหมดต้องไปยัง Google API เดียวกัน

คุณสามารถโทรได้ไม่เกิน 1,000 สายต่อคำขอเป็นกลุ่ม หากต้องการให้มีการเรียกมากกว่านั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ

หมายเหตุ: ระบบแบบกลุ่มสำหรับ People API จะใช้ไวยากรณ์เดียวกับระบบการประมวลผลแบบกลุ่มของข้อมูล OData แต่อรรถศาสตร์แตกต่างกัน

รายละเอียดกลุ่ม

คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการรวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งสามารถส่งไปยัง batchPath ที่ระบุไว้ในเอกสารการค้นพบ API ได้ เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้อธิบายไวยากรณ์แบบกลุ่มโดยละเอียด ต่อไปจะเป็นตัวอย่าง

หมายเหตุ: คำขอ n ชุดหนึ่งที่จัดกลุ่มเข้าด้วยกันจะนับรวมในขีดจำกัดการใช้งานของคุณเป็นคำขอ n ไม่ใช่คำขอเดียว ระบบจะแยกคำขอแบบกลุ่มเป็นชุดคำขอก่อนประมวลผล

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

คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก People 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

ตัวอย่าง

ตัวอย่างต่อไปนี้แสดงการใช้การจัดกลุ่มกับ People API

ตัวอย่างคำขอแบบกลุ่ม

POST /batch HTTP/1.1
accept-encoding: gzip, deflate
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary="batch_people"
Content-Length: total_content_length



--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1



POST /v1/people:createContact HTTP/1.1
Content-Type: application/json
Content-Length: part_content_length
Accept: application/json
{
  "names": [{ "givenName": "John", "familyName": "Doe" }]
}



--batch_people
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2



GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1
Accept: application/json
--batch_people--

ตัวอย่างการตอบกลับเป็นกลุ่ม

นี่เป็นการตอบสนองต่อคำขอตัวอย่างในส่วนก่อนหน้า

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Date: Tue, 22 Jan 2020 18:56:00 GMT
Expires: Tue, 22 Jan 2020 18:56:00 GMT
Cache-Control: private



--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resourceName": "people/c11111111111111",
  "etag": "1111",
  "names": [{ "givenName": "John", "familyName": "Doe" }]
}



--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50
Content-Type: application/http
Content-ID: response-2



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "resourceName": "people/c123456789012345",
  "etag": "1234",
  "emailAddresses": [{ "value": "jane.doe@gmail.com" }]
}
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--