Raggruppamento delle richieste dell'API di Google Analytics

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

Questo documento riguarda nello specifico l'esecuzione di una richiesta batch tramite l'invio di una richiesta HTTP. Se invece utilizzi una libreria client di Google per eseguire una richiesta batch, consulta la documentazione della libreria client.

Panoramica

Ogni connessione HTTP del client genera un determinato overhead. L'API di Google Analytics supporta i batch, per consentire al tuo client di inserire diverse chiamate API in una singola richiesta HTTP.

Esempi di situazioni in cui potresti voler utilizzare la creazione in batch:

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

Puoi effettuare un massimo di 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 Google Analytics 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 al batchPath specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version. Questa sezione descrive dettagliatamente la sintassi batch; più avanti troverai un esempio.

Nota: un insieme di richieste n raggruppate insieme viene conteggiato ai fini del limite di utilizzo come richieste n, non come un'unica 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 Google Analytics, che utilizza il tipo di contenuti multipart/mixed. All'interno di quella 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 di parte servono solo a segnare 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 specifici. 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, ad eccezione delle intestazioni Content- come Content-Type, si applicano a ogni richiesta del batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna che in una singola chiamata, il valore di quest'ultima sostituisce il valore dell'intestazione della richiesta batch esterna. Le intestazioni di una singola chiamata si applicano solo a quella chiamata.

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

Quando il server riceve la richiesta in batch, applica i parametri di query e le intestazioni della richiesta esterna (a seconda dei casi) 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 contenuto multipart/mixed; ogni parte è la risposta a una delle richieste della richiesta in batch, nello stesso ordine delle richieste.

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

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

Nota: il server potrebbe effettuare le chiamate in qualsiasi ordine. Non fare affidamento sull'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 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 Google Analytics.

Esempio di richiesta batch

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

Esempio di risposta batch

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

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

Librerie client

Utilizza le seguenti guide alle librerie client per scoprire come implementare la creazione in batch nella tua lingua:

Raggruppamento e quota di Google Analytics

Sebbene il raggruppamento in batch possa consentirti di evitare l'overhead associato alla creazione di molte richieste HTTP, ogni richiesta API di Google Analytics all'interno di una richiesta batch verrà conteggiata nella quota di progetto giornaliera. Per impostazione predefinita un progetto può effettuare fino a 50.000 richieste al giorno. Il raggruppamento in batch non ti aiuterà a rimanere al di sotto di questa quota.

Fatta eccezione per le richieste in batch di autorizzazioni utente di scrittura (eliminazione, inserimento, aggiornamento), vengono comunque applicati tutti i limiti di frequenza. Ad esempio, l'API di reporting principale è limitata a 10 richieste in parallelo per vista (profilo); il raggruppamento in batch non ti aiuterà a rimanere al di sotto di questo limite.

Il limite di 1,5 query al secondo (QPS) per ID account si applica alle richieste di scrittura dell'API di gestione e alle richieste di scrittura API di provisioning. Di conseguenza, il raggruppamento di queste richieste di scrittura in batch potrebbe non migliorare le prestazioni.