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

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

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

คำขอกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก People API หลายรายการโดยใช้ประเภทเนื้อหา multipart/mixed ภายในคําขอ HTTP หลักนั้น แต่ละส่วนจะมีคําขอ HTTP ที่ฝังอยู่

แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว Content-Type: application/http 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--