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

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

วิธีเดียวในการจัดกลุ่มก็คือปลายทาง Global HTTP Batch (www.googleapis.com/batch) ได้ปิดตัวลงในวันที่ 12 สิงหาคม 2020 ที่ประกาศไว้ในบล็อก Google Developers วิธีอื่นๆ ในการจัดกลุ่มยังคงใช้งานได้ตามที่ระบุไว้ในเอกสารอื่นๆ ของหน้านี้ หากโค้ดใช้ปลายทาง Batch ของ HTTP ทั่วโลก ให้ดูบล็อกโพสต์เกี่ยวกับวิธีการเปลี่ยนไปใช้วิธีการอื่นๆ เช่น ปลายทาง HTTP เฉพาะสําหรับ API (www.googleapis.com/batch/API/VERSION)

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

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

ภาพรวม

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

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

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

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

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

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

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

คําขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการรวมกันเป็นคําขอ HTTP 1 รายการ ซึ่งส่งไปยัง 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 หนึ่งๆ ทั้งในคําขอภายนอกและการเรียกใช้แต่ละรายการ ค่าของส่วนหัวแต่ละรายการจะลบล้างค่าของส่วนหัวคําขอแบบกลุ่มภายนอก ส่วนหัวของการโทรแต่ละครั้งจะมีผลกับการโทรดังกล่าวเท่านั้น

เช่น หากคุณระบุส่วนหัวการให้สิทธิ์สําหรับการโทรหนึ่งๆ ส่วนหัวนั้นจะมีผลกับการโทรดังกล่าวเท่านั้น หากคุณมีส่วนหัว Authorization สําหรับคําขอจากภายนอก ส่วนหัวนั้นจะมีผลกับการเรียกทั้งหมด เว้นแต่จะมีการลบล้างส่วนหัวนั้นด้วยส่วนหัวการให้สิทธิ์ของตนเอง

เมื่อเซิร์ฟเวอร์ได้รับคําขอแบบกลุ่ม เซิร์ฟเวอร์จะใช้พารามิเตอร์การค้นหาและส่วนหัวของคําขอภายนอก (ตามความเหมาะสม) กับแต่ละส่วน แล้วถือว่าแต่ละส่วนเป็นคําขอ HTTP แยกกัน

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

การตอบกลับของเซิร์ฟเวอร์เป็นการตอบกลับ HTTP มาตรฐานรายการเดียวที่มีประเภทเนื้อหา multipart/mixed แต่ละส่วนจะเป็นการตอบกลับคําขอใดคําขอหนึ่งในคําขอแบบกลุ่มตามลําดับเดียวกับคําขอ

การตอบสนองแต่ละส่วนมีการตอบสนอง HTTP ที่สมบูรณ์ เช่น รหัสสถานะ ส่วนหัว และเนื้อหา เช่นเดียวกับส่วนต่างๆ ในคําขอ และในแต่ละส่วน ส่วนหัวการตอบกลับจะมีส่วนหัว Content-Type ที่เป็นตัวทําเครื่องหมายในช่วงต้นของส่วน

หากส่วนใดของคําขอมีส่วนหัว Content-ID ส่วนที่เกี่ยวข้องของการตอบกลับจะมีส่วนหัว Content-ID ที่ตรงกัน โดยค่าเดิมจะขึ้นต้นด้วยสตริง response- ดังที่แสดงในตัวอย่างต่อไปนี้

หมายเหตุ: เซิร์ฟเวอร์อาจทําการโทรของคุณในลําดับใดก็ได้ อย่านับการเรียกใช้การเรียกใช้ตามลําดับที่คุณระบุไว้ หากต้องการมั่นใจว่าจะมีการโทร 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=--