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

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

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

ภาพรวม

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

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

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

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

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

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

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

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

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

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

คำขอแบบกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก Enterprise License Manager 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 แต่แนวคิดเดียวกันนี้จะใช้กับ Enterprise License Manager 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:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

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:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--