批量请求

本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的 HTTP 连接数量。

本文档专门介绍了如何通过发送 HTTP 请求来发出批处理请求。如果您要使用某个 Google 客户端库来发出批处理请求，请参阅该客户端库的说明文档。

概览

客户端建立的每个 HTTP 连接都会产生一定的开销。Manufacturer Center API 支持批处理，这样您的客户就可以将多个 API 调用组合为一个 HTTP 请求。

在以下示例情况下，您可能需要使用批处理：

    • 上传大量商品。

    • 正在删除大量商品。

    • 正在检索大量商品。

在上述每种情况下，您都可以将这些调用组合成一个 HTTP 请求，而不是单独发送每个调用。请注意，所有内部请求都必须发送到同一 Google API。

单个批量请求最多可以包含 1000 次调用。如果必须进行更多次调用，请使用多个批量请求。

注意：Manufacturer Center API 的批处理系统使用的语法与 OData 批处理系统相同，但语义有所不同。

批量详情

批量请求就是将多个 API 调用进行合并而形成的一个 HTTP 请求，您可以将此请求发送到 API 发现文档中指定的 batchPath。默认路径为 /batch/api_name/api_version。本部分详细介绍了批处理语法，随后还会提供一个示例。

注意：一组一起进行批处理的 n 个请求将按 n 个请求（而非一个请求）计入用量限额。在处理之前，系统会将批量请求拆分为一组请求。

批量请求的格式

批量请求是一个包含多个 Manufacturer Center API 调用的标准 HTTP 请求，使用 multipart/mixed 内容类型。在此主 HTTP 请求中，每个部分都包含一个内嵌的 HTTP 请求。

各个部分都以其自身的 Content-Type: application/http 标头开头。您还可以选择添加一个 Content-ID 标头。不过，每个部分的标头仅用于标记该部分的开头，而与嵌套请求无关。在服务器将批量请求拆分为多个单独请求之后，每个部分的标头就会被忽略。

各个部分的正文是一个完整的 HTTP 请求，各自有专用的动词、网址、标头和正文。此 HTTP 请求必须仅包含网址的路径部分；不允许在批量请求中使用完整的网址。

外部批量请求的 HTTP 标头应用于批次中的每个请求，但 Content-Type 之类的 Content- 标头除外。如果您在外部请求和个别调用中都指定了特定的 HTTP 标头，则个别调用标头的值将替换外部批量请求标头的值。另请注意，单个调用的标头仅应用于该调用本身。

例如，如果您为特定调用提供了 Authorization 标头，则该标头仅应用于该调用。如果您为外部请求提供了 Authorization 标头，则该标头将应用于所有的单个调用，除非单个调用将其替换为自身的 Authorization 标头。

当服务器收到批处理请求时，会将外部请求的查询参数和标头（如果适用）应用于各部分，然后将各部分视作单独的 HTTP 请求进行处理。

对批量请求的响应

服务器的响应是一个标准的 HTTP 响应，使用 multipart/mixed 内容类型；其中的每个部分分别是对批量请求中一个请求的响应，且顺序与这些请求相同。

和请求中的各部分一样，响应中的各部分都包含一个完整的 HTTP 响应，其中包括状态代码、标头和正文。此外，和请求中的各部分一样，响应中的各部分均以 Content-Type 标头为前缀，用于标记各部分的开头。

如果请求的某个特定部分具有 Content-ID 标头，则响应的对应部分也会有相同的 Content-ID 标头，其格式为在原始值前面加上 response- 字符串，如下例所示。

注意：服务器可能会以任何顺序执行您的调用，因此不要预期这些调用将会以您指定的顺序执行。如果要确保两个调用以指定顺序执行，就不能在单个请求中发送这两个调用。正确的做法是，先单独发送第一个调用，等收到其响应之后再发送第二个。

示例

以下示例展示了如何通过 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();