หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

ภาพรวม

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

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

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

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

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

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

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

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

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

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

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

ตัวอย่าง

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

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

POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==--

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

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

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "1234567890",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "0987654321",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "5432109876",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--