การส่งคำขอแบบกลุ่ม

ภาพรวม

การเชื่อมต่อ 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--