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

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

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

ภาพรวม

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

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

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

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

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

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

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

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

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

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

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