Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Yêu cầu theo lô (Batch)

Tài liệu này trình bày cách kết hợp các lệnh gọi API với nhau để giảm số lượng kết nối HTTP mà ứng dụng của bạn phải thực hiện.

Tài liệu này đề cập cụ thể đến việc tạo yêu cầu hàng loạt bằng cách gửi một yêu cầu HTTP. Nếu bạn đang sử dụng một thư viện ứng dụng Google để thực hiện yêu cầu hàng loạt, hãy xem tài liệu của thư viện ứng dụng.

Tổng quan

Mỗi kết nối HTTP mà ứng dụng của bạn thực hiện sẽ dẫn đến một lượng hao tổn nhất định. Manufacturer Center API hỗ trợ việc xử lý hàng loạt để cho phép ứng dụng của bạn đưa nhiều lệnh gọi API vào một yêu cầu HTTP duy nhất.

Ví dụ về các trường hợp bạn có thể muốn sử dụng tính năng xử lý hàng loạt:

Tải số lượng lớn sản phẩm lên.
Xoá số lượng lớn sản phẩm.
Truy xuất số lượng lớn sản phẩm.

Trong mỗi trường hợp, thay vì gửi từng lệnh gọi riêng biệt, bạn có thể nhóm các lệnh gọi lại với nhau thành một yêu cầu HTTP duy nhất. Tất cả các yêu cầu nội bộ phải được gửi đến cùng một API của Google.

Bạn chỉ được thực hiện tối đa 1.000 lệnh gọi trong một yêu cầu hàng loạt. Nếu bạn phải thực hiện nhiều lệnh gọi hơn, hãy sử dụng nhiều yêu cầu hàng loạt.

Lưu ý: Hệ thống xử lý hàng loạt cho Manufacturer Center API sử dụng cùng một cú pháp như hệ thống xử lý hàng loạt OData, nhưng ngữ nghĩa thì khác.

Chi tiết gói

Yêu cầu hàng loạt bao gồm nhiều lệnh gọi API được kết hợp thành một yêu cầu HTTP duy nhất. Yêu cầu này có thể được gửi đến batchPath được chỉ định trong tài liệu khám phá API. Đường dẫn mặc định là /batch/api_name/api_version. Phần này mô tả chi tiết cú pháp của lô; sau đó, sẽ có một ví dụ.

Lưu ý: Một nhóm các yêu cầu n được gộp lại sẽ được tính vào hạn mức sử dụng của bạn dưới dạng các yêu cầu n, chứ không phải một yêu cầu. Yêu cầu theo lô được tách thành một nhóm yêu cầu trước khi xử lý.

Định dạng của yêu cầu theo lô

Yêu cầu theo lô là một yêu cầu HTTP tiêu chuẩn duy nhất chứa nhiều lệnh gọi Manufacturer Center API, sử dụng loại nội dung multipart/mixed. Trong yêu cầu HTTP chính đó, mỗi phần chứa một yêu cầu HTTP lồng nhau.

Mỗi phần bắt đầu bằng tiêu đề HTTP Content-Type: application/http riêng. Ngoài ra, bạn cũng có thể thêm tiêu đề Content-ID (không bắt buộc). Tuy nhiên, tiêu đề phần chỉ dùng để đánh dấu phần đầu của phần; chúng tách biệt với yêu cầu lồng nhau. Sau khi máy chủ mở gói yêu cầu hàng loạt thành các yêu cầu riêng biệt, tiêu đề phần sẽ bị bỏ qua.

Nội dung của mỗi phần là một yêu cầu HTTP hoàn chỉnh, với động từ, URL, tiêu đề và nội dung riêng. Yêu cầu HTTP chỉ được chứa phần đường dẫn của URL; bạn không được dùng URL đầy đủ trong các yêu cầu hàng loạt.

Tiêu đề HTTP cho yêu cầu hàng loạt bên ngoài, ngoại trừ các tiêu đề Content- như Content-Type, áp dụng cho mọi yêu cầu trong lô. Nếu bạn chỉ định một tiêu đề HTTP nhất định trong cả yêu cầu bên ngoài và một lệnh gọi riêng lẻ, thì giá trị của tiêu đề lệnh gọi riêng lẻ sẽ ghi đè giá trị của tiêu đề yêu cầu hàng loạt bên ngoài. Tiêu đề của một cuộc gọi riêng lẻ chỉ áp dụng cho cuộc gọi đó.

Ví dụ: nếu bạn cung cấp một tiêu đề Uỷ quyền cho một lệnh gọi cụ thể, thì tiêu đề đó chỉ áp dụng cho lệnh gọi đó. Nếu bạn cung cấp một tiêu đề Uỷ quyền cho yêu cầu bên ngoài, thì tiêu đề đó sẽ áp dụng cho tất cả các lệnh gọi riêng lẻ, trừ phi các lệnh gọi đó ghi đè tiêu đề này bằng tiêu đề Uỷ quyền của riêng chúng.

Khi nhận được yêu cầu theo lô, máy chủ sẽ áp dụng các tham số truy vấn và tiêu đề của yêu cầu bên ngoài (nếu thích hợp) cho từng phần, sau đó coi từng phần như thể đó là một yêu cầu HTTP riêng biệt.

Phản hồi yêu cầu theo lô

Phản hồi của máy chủ là một phản hồi HTTP tiêu chuẩn duy nhất có loại nội dung multipart/mixed; mỗi phần là phản hồi cho một trong các yêu cầu trong yêu cầu theo lô, theo cùng thứ tự với các yêu cầu.

Giống như các phần trong yêu cầu, mỗi phần phản hồi chứa một phản hồi HTTP hoàn chỉnh, bao gồm mã trạng thái, tiêu đề và nội dung. Giống như các phần trong yêu cầu, mỗi phần phản hồi đều có một tiêu đề Content-Type ở phía trước để đánh dấu phần bắt đầu.

Nếu một phần nhất định của yêu cầu có tiêu đề Content-ID, thì phần phản hồi tương ứng sẽ có tiêu đề Content-ID phù hợp, với giá trị ban đầu đứng trước chuỗi response-, như trong ví dụ sau.

Lưu ý: Máy chủ có thể thực hiện các lệnh gọi của bạn theo bất kỳ thứ tự nào. Đừng mong đợi các thao tác này được thực thi theo thứ tự mà bạn đã chỉ định. Nếu muốn đảm bảo rằng hai lệnh gọi xảy ra theo một thứ tự nhất định, bạn không thể gửi chúng trong một yêu cầu duy nhất; thay vào đó, hãy gửi lệnh gọi đầu tiên riêng biệt, sau đó đợi phản hồi cho lệnh gọi đầu tiên trước khi gửi lệnh gọi thứ hai.

Ví dụ:

Ví dụ sau đây minh hoạ cách sử dụng tính năng xử lý hàng loạt với API Manufacturer Center.

Ví dụ về yêu cầu theo lô


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--

Ví dụ về phản hồi hàng loạt

Đây là phản hồi cho yêu cầu ví dụ trong phần trước.



--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--

Điều kiện tiên quyết

Tài khoản Manufacturer Center

Ví dụ về lô

Đoạn mã sau đây minh hoạ cách gửi thông tin cập nhật sản phẩm theo lô bằng 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();

Yêu cầu theo lô (Batch) Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.