バッチ リクエスト

ここでは、複数のバッチ API 呼び出しを行って、クライアント側の HTTP 接続の回数を減らす方法について説明します。

具体的には、1 件の HTTP リクエストを送信してバッチ リクエストを行う方法を取り上げます。Google クライアント ライブラリを使用してバッチ リクエストを行う場合は、クライアント ライブラリのドキュメントをご覧ください。

概要

クライアントで HTTP 接続を行うたびに、ある程度のオーバーヘッドが発生します。Manufacturer Center API では一括処理がサポートされており、クライアントは複数の API 呼び出しを 1 つの HTTP リクエストにまとめることができます。

バッチ処理は次のような状況で使用します。

• 多数の商品をアップロードしている。

• 多数の商品を削除しています。

• 多数の商品を取得しています。

いずれの場合も、各呼び出しを個別に送信するのではなく、1 つの HTTP リクエストにまとめることができます。内部リクエストはすべて同じ Google API に送信する必要があります。

1 つのバッチ リクエストに含めることができる呼び出しの上限は 1,000 個です。これ以上の呼び出しを行う必要がある場合は、バッチ リクエストを複数使用します。

注: Manufacturer Center API のバッチシステムは OData バッチ処理システムと同じ構文を使用しますが、セマンティクスは異なります。

バッチ リクエストの詳細

バッチ リクエストは、複数の API 呼び出しを 1 つの HTTP リクエストにまとめたもので、API ディスカバリ ドキュメントで指定されている batchPath に送信できます。デフォルトのパスは /batch/api_name/api_version です。このセクションでは、バッチ リクエストの構文について詳しく説明し、最後に例を紹介します。

注: n 件のリクエストを 1 つにまとめたバッチ リクエストは、1 件のリクエストではなく n 件のリクエストとして使用量上限に加算されます。バッチ リクエストは、個々のリクエストに分割されてから処理されます。

バッチ リクエストの形式

バッチ リクエストは multipart/mixed コンテンツ タイプを使用した単一の標準 HTTP リクエストで、複数の Manufacturer Center API 呼び出しから構成されます。そのメインの HTTP リクエスト内の各パーツには、ネストされた HTTP リクエストが含まれます。

各パーツはそれぞれ Content-Type: application/http という形式の HTTP ヘッダーで始まり、オプションの Content-ID ヘッダーを指定することもできます。ただし、パーツヘッダーはパーツの開始箇所を示すためだけに存在していて、ネストされたリクエストとは分かれています。サーバーがバッチ リクエストを別々のリクエストにアンラップした後、パーツヘッダーは無視されます。

各パーツのボディは、独自の動詞、URL、ヘッダー、ボディを含む完全な HTTP リクエストです。これらの HTTP リクエストには URL のパス部分のみを含める必要があり、完全な URL は、バッチ リクエストでは許可されていません。

外側のバッチ リクエストの HTTP ヘッダー（Content-Type などの Content- ヘッダー以外）はバッチ リクエスト内の各リクエストに適用されます。ある HTTP ヘッダーを外側のリクエストと個々の呼び出しの両方で指定した場合、個々の呼び出しのヘッダー値は外側のバッチ リクエストのヘッダー値を上書きします。個々の呼び出しのヘッダーはその呼び出しにのみ適用されます。

たとえば、ある呼び出しに Authorization ヘッダーを指定した場合、そのヘッダーはその呼び出しにのみ適用されます。Authorization ヘッダーを外側のリクエストに指定した場合、そのヘッダーはすべての呼び出しに適用されます。ただし、各呼び出しに独自の Authorization ヘッダーを指定している場合は各呼び出しの Authorization ヘッダーで上書きされます。

サーバーがバッチ リクエストを受信すると、外側のリクエストのクエリ パラメータとヘッダー（指定した場合）を各パーツに適用し、各パーツを個別の HTTP リクエストとして処理します。

バッチ リクエストへのレスポンス

サーバーのレスポンスは multipart/mixed コンテンツ タイプを使用した単一の標準 HTTP レスポンスです。各パーツはバッチ リクエスト内の個々のリクエストに対するレスポンスで、リクエストと同じ順序にネストされます。

レスポンスの各パーツは、リクエストのパーツと同様にステータス コード、ヘッダー、ボディを含む完全な HTTP レスポンスになっています。また、リクエストのパーツと同様に、レスポンスの各パーツはパーツの開始箇所を示す Content-Type ヘッダーから始まります。

リクエストのパーツに Content-ID ヘッダーがある場合、対応するレスポンスのパーツには、それに一致する Content-ID ヘッダーが指定されます。レスポンスのパーツのヘッダーは、以下の例に示すように、元の値の先頭に文字列 response- が付いた値となります。

注: サーバーはバッチ リクエスト内の呼び出しを順番どおりに処理するとは限りません。指定した順序で実行されると想定しないでください。2 つの呼び出しを特定の順序で実行したい場合は、1 つのバッチ リクエストで送信することはできません。代わりに、最初の呼び出しを送信してレスポンスが返ってきてから、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();