Richieste batch

Questo documento mostra come raggruppare le chiamate API in batch per ridurre il numero di connessioni HTTP che il cliente deve effettuare.

Questo documento riguarda nello specifico la creazione di una richiesta batch mediante l'invio di un richiesta HTTP. Se, invece, utilizzi una libreria client di Google per effettuare una richiesta batch, consulta la documentazione della libreria client.

Panoramica

Ogni connessione HTTP effettuata dal client determina un certo overhead. L'API Manufacturer Center supporta la creazione in batch, per consentire al tuo client di inserire più chiamate API in un'unica richiesta HTTP.

Esempi di situazioni in cui è possibile utilizzare la gestione in batch:

• Caricamento di un numero elevato di prodotti.

• Eliminazione di un numero elevato di prodotti.

• Recupero di un numero elevato di prodotti.

In ogni caso, invece di inviare ogni chiamata separatamente, puoi raggrupparle in un'unica richiesta HTTP. Tutte le richieste interne devono andare alla stessa API di Google.

Non puoi superare le 1000 chiamate in una singola richiesta batch. Se devi effettuare un numero maggiore di chiamate, utilizza più richieste batch.

Nota: il sistema batch per l'API Manufacturer Center utilizza la stessa sintassi del sistema di elaborazione batch OData, ma la semantica è diversa.

Dettagli batch

Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata all'indirizzo batchPath specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version. Questa sezione descrive in dettaglio la sintassi batch; in seguito puoi trovare un esempio.

Nota: un insieme di n richieste raggruppate insieme viene conteggiata ai fini del limite di utilizzo come richieste di n, non come una singola richiesta. La richiesta batch viene separata in un insieme di richieste prima dell'elaborazione.

Formato di una richiesta batch

Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate API di Manufacturer Center, che utilizza il tipo di contenuti multipart/mixed. All'interno di questa richiesta HTTP principale, ciascuna parte contiene una richiesta HTTP nidificata.

Ogni parte inizia con la propria intestazione HTTP Content-Type: application/http. Può anche avere un'intestazione Content-ID facoltativa. Tuttavia, le intestazioni delle parti servono solo a contrassegnare l'inizio della parte; e sono separate dalla richiesta nidificata. Dopo che il server ha decriptato la richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.

Il corpo di ogni parte è una richiesta HTTP completa, con il proprio verbo, URL, intestazioni e corpo. La richiesta HTTP deve contenere solo la parte del percorso dell'URL. Non sono consentiti URL completi nelle richieste batch.

Le intestazioni HTTP per la richiesta batch esterna, fatta eccezione per le intestazioni Content- come Content-Type, si applicano a tutte le richieste nel batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna sia in una singola chiamata, il valore dell'intestazione di chiamata singola sostituisce il valore dell'intestazione della richiesta batch esterna. Le intestazioni di una singola chiamata si applicano solo a quella chiamata.

Ad esempio, se fornisci un'intestazione Autorizzazione per una chiamata specifica, questa intestazione si applica solo a quella chiamata. Se fornisci un'intestazione di autorizzazione per la richiesta esterna, questa intestazione si applica a tutte le singole chiamate, a meno che non la sostituiscano con intestazioni di autorizzazione proprie.

Quando il server riceve la richiesta in batch, applica i parametri di ricerca e le intestazioni (a seconda dei casi) della richiesta esterna a ogni parte, quindi tratta ogni parte come se fosse una richiesta HTTP separata.

Risposta a una richiesta batch

La risposta del server è una singola risposta HTTP standard con un tipo di contenuti multipart/mixed; ciascuna parte è la risposta a una delle richieste nella richiesta in batch, nello stesso ordine delle richieste.

Come le parti della richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, intestazioni e corpo. E come le parti nella richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type che segna l'inizio della parte.

Se una determinata parte della richiesta aveva un'intestazione Content-ID, la parte corrispondente della risposta ha un'intestazione Content-ID corrispondente, con il valore originale preceduto dalla stringa response-, come mostrato nell'esempio seguente.

Nota: il server potrebbe eseguire le chiamate in qualsiasi ordine. Non fare affidamento sulla loro esecuzione nell'ordine in cui li hai specificati. Se vuoi assicurarti che due chiamate avvengano in un determinato ordine, non puoi inviarle in un'unica richiesta; invia la prima risposta da sola, quindi attendi la risposta alla prima prima di inviare la seconda.

Esempio

L'esempio seguente mostra l'utilizzo della creazione in batch con l'API Manufacturer Center.

Esempio di richiesta batch

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

Esempio di risposta batch

Questa è la risposta alla richiesta di esempio nella sezione precedente.

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

Prerequisiti

Un account Manufacturer Center.

Esempio batch

Il codice seguente illustra come inviare aggiornamenti di prodotto in batch utilizzando 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();