Żądania zbiorcze

W tym dokumencie opisujemy, jak grupować wywołania interfejsu API, by zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.

Ten dokument dotyczy tworzenia żądań zbiorczych przez wysyłanie żądań HTTP. Jeśli zamiast tego używasz biblioteki klienta Google do wysyłania żądań zbiorczych, zapoznaj się z dokumentacją biblioteki klienta.

Opis

Każde połączenie HTTP realizowane przez klienta wiąże się z określonym obciążeniem. Interfejs Manufacturer Center API obsługuje grupowanie, dzięki czemu Twój klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.

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

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

• Usuwanie dużej liczby produktów.

• Pobieranie dużej liczby produktów.

W każdym przypadku zamiast wysyłać każde wywołanie oddzielnie, 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 wykonać maksymalnie 1000 wywołań. Jeśli musisz wykonać więcej wywołań, użyj wielu żądań zbiorczych.

Uwaga: system wsadowy dla interfejsu Manufacturer Center API używa tej samej składni co system przetwarzania zbiorczego OData, ale semantyka jest inna.

Szczegóły wsadu

Żądanie wsadowe składa się z wielu wywołań interfejsu API połączonych w jedno żądanie HTTP, które może zostać wysłane pod adres batchPath podany w dokumencie opisującym interfejs API. Domyślna ścieżka to /batch/api_name/api_version. W tej sekcji szczegółowo opisano składnię wsadu. Później znajdziesz przykład.

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

Format żądania zbiorczego

Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele wywołań interfejsu API Manufacturer Center wykorzystujące typ treści multipart/mixed. Każda część 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ż zawierać opcjonalny nagłówek Content-ID. Jednak nagłówki części służą tylko do zaznaczania początku części. Są oddzielone od zagnieżdżonego żądania. Po wyodrębnieniu przez serwer żądania zbiorczego w 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 część ścieżki adresu URL. W żądaniach zbiorczych nie są dozwolone pełne adresy 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 w grupie. Jeśli określisz nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i pojedynczym wywołaniu, wartość nagłówka pojedynczego wywołania zastąpi wartość zewnętrznego nagłówka żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.

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

Gdy serwer odbiera takie żądanie, stosuje (stosownie do potrzeb) parametry zapytania i nagłówki żądania zewnętrznego, 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ęść jest odpowiedzią na jedno z żądań zbiorczych w tej samej kolejności co żądania.

Podobnie jak części żądania, każda część odpowiedzi 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 wskazującym początek danej części.

Jeśli dana część żądania miała nagłówek Content-ID, odpowiadająca jej część odpowiedzi ma zgodny nagłówek Content-ID, z pierwotną wartością poprzedzoną ciągiem response-, jak w poniższym przykładzie.

Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie licz na to, że zostaną wykonane w kolejności, w jakiej zostały przez Ciebie określone. Jeśli chcesz mieć pewność, że 2 wywołania mają wystąpić w określonej kolejności, nie możesz wysyłać ich w ramach jednego żądania. Zamiast tego wyślij pierwsze z nich samodzielnie, a następnie poczekaj na odpowiedź pierwszego z nich, a dopiero potem poczekaj na odpowiedź drugiego żądania.

Przykład

Przykład poniżej pokazuje użycie grupowania za pomocą interfejsu Manufacturer Center API.

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 z 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 pokazuje, 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();