Un approccio specifico al raggruppamento in batch, l'endpoint batch HTTP globale (www.googleapis.com/batch), è stato disattivato il 12 agosto 2020, come annunciato nel blog degli sviluppatori Google. Altri approcci al batch funzionano comunque, come documentato nel resto di questa pagina. Se il tuo codice utilizza l'endpoint batch HTTP globale, consulta il post del blog per le istruzioni sulla transizione per utilizzare altri approcci, come gli endpoint batch HTTP specifici dell'API (www.googleapis.com/batch/API/VERSION).
Questo documento mostra come raggruppare le chiamate API per ridurre il numero di connessioni HTTP che il client deve effettuare.
Questo documento riguarda specificamente l'invio di una richiesta batch inviando una richiesta HTTP. Se, invece, utilizzi una libreria client Google per effettuare una richiesta batch, consulta la documentazione della libreria client.
Panoramica
Ogni connessione HTTP eseguita dal client genera un certo sovraccarico. L'API Google Mirror supporta il batch, per consentire al client di inserire più chiamate API in una singola richiesta HTTP.
Esempi di situazioni in cui potresti voler utilizzare il raggruppamento:
- Hai appena iniziato a utilizzare l'API e devi caricare molti dati.
- Un utente ha apportato modifiche ai dati mentre l'applicazione era offline (non in connessione a Internet), pertanto l'applicazione deve sincronizzare i dati locali con il server inviando molti aggiornamenti ed eliminazioni.
In ogni caso, invece di inviare ogni chiamata separatamente, puoi raggrupparle in una singola richiesta HTTP. Tutte le richieste interne devono essere inviate alla stessa API di Google.
Non puoi superare le 1000 chiamate in una singola richiesta in batch. Se devi effettuare più chiamate, utilizza più richieste in batch.
Nota: il sistema batch per l'API Google Mirror utilizza la stessa sintassi del sistema di elaborazione batch OData, ma la semantica è diversa.
Dettagli batch
Una richiesta in batch è composta da più chiamate API combinate in una richiesta HTTP, che può essere inviata a batchPath specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version. Questa sezione descrive la sintassi batch in dettaglio; di seguito, è riportato un esempio.
Nota: un insieme di n richieste raggruppate insieme ai fini del tuo limite di utilizzo come richieste n, non come una singola richiesta. La richiesta in batch viene suddivisa in un insieme di richieste prima dell'elaborazione.
Formato di una richiesta in batch
Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate API di Google Mirror, che utilizza il tipo di contenuti multipart/mixed. All'interno di questa richiesta HTTP principale, ogni 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 sono solo per contrassegnare l'inizio della parte e sono separate dalla richiesta nidificata. Dopo che il server ha annullato il wrapping della richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.
Il corpo di ogni parte è una richiesta HTTP completa, con verbo, URL, intestazioni e corpo. La richiesta HTTP deve contenere solo la porzione del percorso dell'URL; gli URL completi non sono consentiti nelle richieste batch.
Le intestazioni HTTP per la richiesta batch esterna, ad eccezione delle intestazioni Content- come Content-Type, si applicano a ogni richiesta nel batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna sia in una singola chiamata, il valore della singola intestazione della chiamata 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 di autorizzazione per una chiamata specifica, l'intestazione verrà applicata 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 vengano sostituite con intestazioni di autorizzazione proprie.
Quando il server riceve la richiesta in batch, applica i parametri di ricerca e le intestazioni della richiesta esterna (a seconda dei casi) a ciascuna parte e quindi gestisce ogni parte come se fosse una richiesta HTTP separata.
Risposta a una richiesta in batch
La risposta del server è una singola risposta HTTP standard con un tipo di contenuti multipart/mixed; ogni parte corrisponde alla risposta a una delle richieste nella richiesta in batch, nello stesso ordine delle richieste.
Come le parti nella richiesta, ogni risposta contiene una risposta HTTP completa, inclusi codice di stato, intestazioni e corpo. Come per le parti nella richiesta, ogni parte di risposta è preceduta da un'intestazione Content-Type che segna l'inizio della parte.
Se una determinata parte della richiesta ha 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 tue chiamate in qualsiasi ordine. Non conteggiarli nell'ordine in cui sono stati specificati. Se vuoi assicurarti che si verifichino due chiamate in un determinato ordine, non puoi inviarle in una singola richiesta; piuttosto, invia la prima da sola, quindi attendi la risposta prima della prima, quindi invia la seconda.
Esempio
L'esempio seguente mostra l'utilizzo del batch con l'API Google Mirror.
Esempio di richiesta in batch
POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==--
Esempio di risposta in batch
Questa è la risposta alla richiesta di esempio nella sezione precedente.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "1234567890",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "0987654321",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "5432109876",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--