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 in batch mediante l'invio di una richiesta HTTP. Se, invece, utilizzi una libreria client di Google per effettuare una richiesta in batch, consulta la documentazione relativa alla libreria client.
Panoramica
Ogni connessione HTTP effettuata dal client comporta un certo overhead. L'API People supporta il batch, per consentire al tuo client di effettuare diverse chiamate API in un'unica richiesta HTTP.
Esempi di situazioni in cui si potrebbe voler utilizzare il raggruppamento:
- Hai appena iniziato a utilizzare l'API e hai molti dati da caricare.
- Un utente ha apportato modifiche ai dati mentre l'applicazione era offline (disconnessa da 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 indirizzate alla stessa API di Google.
Puoi creare un massimo di 1000 chiamate in una singola richiesta batch. Se devi effettuare più chiamate, utilizza più richieste batch.
Nota: il sistema batch per l'API People 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 al batchPath specificato nel documento di rilevamento dell'API. Il percorso predefinito è /batch/api_name/api_version. Questa sezione descrive in dettaglio la sintassi del batch e seguito è riportato un esempio.
Nota: un insieme di n richieste raggruppate in blocco per il raggiungimento del limite di utilizzo viene considerato come una richiesta n, non come una singola richiesta. La richiesta batch viene scomposta in un insieme di richieste prima dell'elaborazione.
Formato di una richiesta batch
Una richiesta in batch è una singola richiesta HTTP standard contenente più chiamate API People, che utilizza il tipo di contenuto multipart/mixed. All'interno della richiesta HTTP principale, ciascuna delle parti contiene una richiesta HTTP nidificata.
Ogni parte inizia con una 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; sono separate dalla richiesta nidificata. Dopo che il server ha annullato il wrapping della richiesta batch in richieste separate, le intestazioni di parte vengono ignorate.
Il corpo di ogni parte è una richiesta HTTP completa, con verbo, URL, intestazioni e corpo. La richiesta HTTP deve contenere solo la parte di percorso dell'URL; gli URL completi non sono consentiti nelle richieste batch.
Le intestazioni HTTP della 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 che in una singola chiamata, il valore della singola intestazione della chiamata prevale sul 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, l'intestazione si applica solo a quella chiamata. Se fornisci un'intestazione Authorization per la richiesta esterna, questa si applica a tutte le singole chiamate, a meno che non vengano sostituite da intestazioni 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, quindi considera 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; ogni parte è la risposta a una delle richieste nella richiesta in batch, nello stesso ordine delle richieste.
Come le parti della richiesta, ogni parte di risposta contiene una risposta HTTP completa, inclusi un codice di stato, le intestazioni e il corpo. Come per 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 conteggiare la loro esecuzione nell'ordine in cui sono stati specificati. Se vuoi assicurarti che vengano effettuate due chiamate in un determinato ordine, non puoi inviarle in una singola richiesta; invia invece la prima autonomamente, quindi attendi la risposta alla prima prima di inviare la seconda.
Esempio
L'esempio seguente mostra l'utilizzo del raggruppamento con l'API People.
Esempio di richiesta in batch
POST /batch HTTP/1.1 accept-encoding: gzip, deflate Authorization: Bearer your_auth_token Content-Type: multipart/mixed; boundary="batch_people" Content-Length: total_content_length--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 1
POST /v1/people:createContact HTTP/1.1 Content-Type: application/json Content-Length: part_content_length Accept: application/json { "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_people Content-Type: application/http Content-Transfer-Encoding: binary Content-ID: 2
GET /v1/people/c123456789012345?personFields=emailAddresses HTTP/1.1 Accept: application/json --batch_people--
Esempio di risposta batch
Questa è la risposta alla richiesta di esempio nella sezione precedente.
HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Date: Tue, 22 Jan 2020 18:56:00 GMT Expires: Tue, 22 Jan 2020 18:56:00 GMT Cache-Control: private--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c11111111111111", "etag": "1111", "names": [{ "givenName": "John", "familyName": "Doe" }] }
--batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50 Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "resourceName": "people/c123456789012345", "etag": "1234", "emailAddresses": [{ "value": "jane.doe@gmail.com" }] } --batch_GOMozbDceUiJkwfCeHo28pGmhwRG5o50--