Żądania zbiorcze

Z tego dokumentu dowiesz się, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.

Ten dokument dotyczy przesyłania zbiorczego za pomocą żądania HTTP. Jeśli zamiast tego do przesyłania zbiorczego używasz biblioteki klienta Google, zapoznaj się z dokumentacją biblioteki klienta.

Przegląd

Każde połączenie HTTP powoduje pewne narzuty. Interfejs Manufacturer Center API obsługuje grupowanie, dzięki czemu Twój klient może wykonać kilka wywołań interfejsu API w jednym żądaniu HTTP.

Przykłady sytuacji, w których warto używać grupowania:

• Przesyłam dużą liczbę produktów.

• Usuwam dużą liczbę produktów.

• Pobieram dużą liczbę produktów.

W każdym przypadku zamiast wysyłać każde wywołanie osobno, możesz je zgrupować w jedno żądanie HTTP. Wszystkie żądania wewnętrzne muszą trafiać do tego samego interfejsu API Google.

Jedno żądanie zbiorcze może zawierać maksymalnie 1000 wywołań. Jeśli musisz wykonać więcej wywołań, użyj wielu żądań zbiorczych.

Uwaga: system wsadowy dla interfejsu API Manufacturer Center ma taką samą składnię jak system przetwarzania wsadowego OData, ale semantyka może być inna.

Szczegóły wsadu

Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w jedno żądanie HTTP, które może zostać wysłane do batchPath wskazanego w dokumencie na temat wykrywania interfejsów API. Ścieżka domyślna to /batch/api_name/api_version. W tej sekcji szczegółowo opisujemy składnię wsadu. W dalszej części przedstawiamy przykład.

Uwaga: zbiór n zbiorczych żądań wlicza się do limitu wykorzystania jako żądania n, a nie jako jedno żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zestaw żądań.

Format żądania zbiorczego

Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele wywołań interfejsu API Manufacturer Center, używając typu treści multipart/mixed. Każda część tego głównego żądania HTTP zawiera zagnieżdżone żądanie HTTP.

Każda część zaczyna się od własnego nagłówka HTTP Content-Type: application/http. Może też mieć opcjonalny nagłówek Content-ID. Nagłówki części służą jednak tylko do oznaczenia początku danej części i są niezależne od zagnieżdżonego żądania. Gdy serwer wyodrębni żądanie zbiorcze na osobne żądania, nagłówki części są ignorowane.

Treść każdej części to kompletne żądanie HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP może zawierać tylko ścieżkę adresu URL. W żądaniach zbiorczych nie można używać pełnych adresów URL.

Nagłówki HTTP zewnętrznego żądania zbiorczego, z wyjątkiem nagłówków Content-, takich jak Content-Type, mają zastosowanie do każdego żądania wsadu. Jeśli określisz nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i w pojedynczym wywołaniu, wartość nagłówka tego wywołania zastąpi wartość zewnętrznego nagłówka żądania zbiorczego. Nagłówki pojedynczego połączenia odnoszą się tylko do tego połączenia.

Jeśli na przykład podasz nagłówek autoryzacji dla określonego wywołania, będzie on stosowany tylko do tego wywołania. Jeśli podasz nagłówek autoryzacji dla żądania zewnętrznego, będzie on stosowany do wszystkich poszczególnych wywołań, chyba że zastąpią go własnym nagłówkiem autoryzacji.

Po otrzymaniu żądania zbiorczego serwer stosuje do każdej części parametry zapytania i nagłówki żądania zewnętrznego (odpowiednio) do każdej części, a następnie traktuje każdą część jako osobne żądanie HTTP.

Odpowiedź na żądanie zbiorcze

Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP z typem treści multipart/mixed. Każda część to odpowiedź na jedno z żądań zbiorczych w tej samej kolejności co żądania.

Podobnie jak części żądania, każda odpowiedź zawiera pełną odpowiedź HTTP, w tym kod stanu, nagłówki i treść. Podobnie jak w przypadku części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type, który określa jej początek.

Jeśli dana część żądania miała nagłówek Content-ID, odpowiadająca jej część ma pasujący nagłówek Content-ID, w którym pierwotna wartość jest poprzedzona ciągiem response- (jak pokazano w przykładzie poniżej).

Uwaga: serwer może wykonywać połączenia w dowolnej kolejności. Nie licz na ich wykonanie w kolejności, w jakiej zostały one określone. Jeśli chcesz mieć pewność, że w danej kolejności będą wykonywane 2 wywołania, nie możesz wysłać ich w jednym żądaniu. Zamiast tego wyślij pierwsze z nich samodzielnie, a następnie poczekaj na odpowiedź, zanim wyślesz kolejne.

Przykład

Poniższy przykład pokazuje wykorzystanie grupowania w interfejsie API Manufacturer Center.

Przykładowe żądanie zbiorcze

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

Przykładowa odpowiedź zbiorcza

To jest odpowiedź na przykładowe żądanie podane w poprzedniej sekcji.

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

Wymagania wstępne

Konto Manufacturer Center

Przykład wsadu

Poniższy kod ilustruje, jak zbiorczo wysyłać aktualizacje produktów za pomocą Javy.

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();