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

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

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

ภาพรวม

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

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

• การอัปโหลดผลิตภัณฑ์จำนวนมาก

• การลบผลิตภัณฑ์จำนวนมาก

• การดึงข้อมูลผลิตภัณฑ์จำนวนมาก

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

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

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

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

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

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

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

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

ตัวอย่าง

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

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

POST https://manufacturers.googleapis.com/batch
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary=--batch_item

--batch_item
Content-Type: application/http
Content-ID: 

PUT /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
Content-Type: application/json

{
   "gtin": "gtin",
   "product_name": "product_name",
   "description": "description",
   "image_link": {
       "image_url": "image_url"
   }
}
--batch_item
Content-Type: application/http
Content-ID: 

GET /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
--batch_item
Content-Type: application/http
Content-ID: 

DELETE /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
--batch_item--

ตัวอย่างการตอบกลับแบบกลุ่ม

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

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "parent": "accounts/account_id",
  "name": "targetCountry:contentLanguage:productId",
  "targetCountry": "targetCountry",
  "contentLanguage": "contentLanguage",
  "productId": "productId"
}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa--

ข้อกำหนดเบื้องต้น

บัญชี Manufacturer Center

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

โค้ดต่อไปนี้แสดงวิธีส่งการอัปเดตผลิตภัณฑ์แบบกลุ่มโดยใช้ Java

Java

String parent = "accounts/123456";
String newProductName = "US:en:product_id_1";

Image image = new Image();
image.setUrl("http://www.example.com/example.png");

Attributes attributes = new Attributes();
attributes.setGtin(ImmmutableList.of("1234567890"));
attributes.setImageLink(image);

// Creates a new BatchRequest object from the ManufacturerCenter object.
BatchRequest batch = manufacturerCenter.batch();

// JsonBatchCallback generic type is Empty to match the return type of update API.
JsonBatchCallback updateProductCallback =  new JsonBatchCallback() {
    public void onSuccess(Empty empty, HttpHeaders responseHeaders) {
        System.out.printf("Product updated successfully.\n");
    }

    public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders)
            throws IOException {
        System.out.printf("Error updating product: %s.\n", error.getMessage());
    }
}

// Adds update product request to batch object.
manufacturerCenter.accounts().products().update(parent, newProductName, attributes)
    .queue(batch, updateProductCallback);

String getProductName = "US:en:product_id_2";

// JsonBatchCallback generic type is Product to match the return type of get API.
JsonBatchCallback getProductCallback =  new JsonBatchCallback() {
    public void onSuccess(Product product, HttpHeaders responseHeaders) {
        System.out.printf("Found product: %s.\n", product.getName());
    }

    public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders)
            throws IOException {
        System.out.printf("Error retrieving product: %s.\n", error.getMessage());
    }
}

// Adds get product request to batch object.
manufacturerCenter.accounts().products().get(parent, getProductName)
    .queue(batch, getProductCallback);

// Sends batch request to Manufacturer Center API.
batch.execute();