Żądania zbiorcze

W tym dokumencie pokazujemy, jak łączyć wywołania interfejsu API w żądania wsadowe, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.

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

Przegląd

Każde połączenie HTTP nawiązywane przez klienta wiąże się z określonym narzutem. Interfejs Manufacturer Center API obsługuje tworzenie żądań wsadowych, dzięki czemu klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.

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

• Przesyłanie dużej liczby produktów.

• Usuwanie dużej liczby produktów.

• Pobieranie dużej liczby produktów.

W każdym z tych przypadków zamiast wysyłać każde wywołanie osobno możesz zgrupować je w jednym żądaniu HTTP. Wszystkie żądania wewnętrzne muszą być kierowane do tego samego interfejsu API Google.

W jednym żądaniu zbiorczym możesz wykonać maksymalnie 1000 wywołań. Jeśli musisz wykonać więcej wywołań, użyj kilku żądań zbiorczych.

Uwaga: system przetwarzania wsadowego interfejsu Manufacturer Center API używa tej samej składni co system przetwarzania wsadowego OData, ale różni się od niego semantyką.

Szczegóły wsadu

Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w jedno żądanie HTTP, które można wysłać do batchPath określonego w dokumencie opisującym interfejs API. Ścieżka domyślna to /batch/api_name/api_version. W tej sekcji szczegółowo opisujemy składnię wsadową. Przykład znajdziesz w dalszej części artykułu.

Uwaga: zestaw n żądań połączonych w pakiet jest liczony do limitu wykorzystania jako n żądania, a nie jako 1 żą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 Manufacturer Center API, które korzysta z typu treści multipart/mixed. W ramach głównego żądania HTTP każda z części zawiera zagnieżdżone żądanie HTTP.

Każda część zaczyna się od własnego Content-Type: application/http nagłówka HTTP. Może też zawierać opcjonalny Content-ID nagłówek. Nagłówki części służą jednak tylko do oznaczania początku części i są oddzielone od zagnieżdżonego żądania. Gdy serwer rozpakuje żą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 musi zawierać tylko ścieżkę 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 partii. Jeśli podasz dany nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i w pojedynczym wywołaniu, wartość nagłówka pojedynczego wywołania zastąpi wartość nagłówka zewnętrznego żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.

Jeśli na przykład podasz nagłówek Authorization dla konkretnego wywołania, będzie on dotyczył tylko tego wywołania. Jeśli w przypadku żądania zewnętrznego podasz nagłówek autoryzacji, będzie on obowiązywać we wszystkich poszczególnych wywołaniach, chyba że zostaną one zastąpione własnymi nagłówkami autoryzacji.

Gdy serwer otrzyma żądanie zbiorcze, zastosuje do każdej części parametry zapytania i nagłówki żądania zewnętrznego (w odpowiednich przypadkach), a następnie potraktuje każdą część tak, jakby była osobnym żądaniem HTTP.

Odpowiedź na żądanie zbiorcze

Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP o multipart/mixed typie treści. Każda jej część jest odpowiedzią na jedno z żądań w żądaniu zbiorczym, w tej samej kolejności co żądania.

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

Jeśli dana część żądania zawierała nagłówek Content-ID, odpowiednia część odpowiedzi zawiera pasujący nagłówek Content-ID, a przed pierwotną wartością znajduje się ciąg znaków response-, jak pokazano w przykładzie poniżej.

Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie zakładaj, że zostaną one wykonane w kolejności, w jakiej zostały określone. Jeśli chcesz mieć pewność, że 2 wywołania nastąpią w określonej kolejności, nie możesz wysłać ich w jednym żądaniu. Zamiast tego wyślij najpierw pierwsze wywołanie, a potem poczekaj na odpowiedź, zanim wyślesz drugie.

Przykład

Poniższy przykład pokazuje użycie przetwarzania wsadowego w 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

Jest to 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 wysyłać aktualizacje produktów w pakietach 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();