Como reunir as solicitações da Google Analytics API em lote

Este documento mostra como colocar chamadas de API em lotes para reduzir o número de conexões HTTP que seu cliente precisa fazer.

Este documento descreve especificamente como fazer uma solicitação de lote enviando uma solicitação HTTP. No entanto, se você usa uma biblioteca cliente do Google para fazer uma solicitação de lote, consulte a documentação da biblioteca cliente.

Visão geral

Cada conexão HTTP que seu cliente faz resulta em uma determinada quantidade de sobrecarga. A Google Analytics API é compatível com lotes para permitir que o cliente coloque várias chamadas da API em uma única solicitação HTTP.

Exemplos de situações em que convém usar lotes:

Em cada caso, em vez de enviar cada chamada separadamente, você pode agrupá-las em uma única solicitação HTTP. Você pode até mesmo agrupar solicitações de vários usuários ou várias APIs do Google.

Há um limite de 1.000 chamadas em uma única solicitação em lote. Se você precisar fazer mais chamadas do que isso, use várias solicitações em lote.

Observação: o sistema de lotes da Google Analytics API usa a mesma sintaxe que o sistema de processamento em lote OData, mas a semântica é diferente.

Detalhes do lote

Uma solicitação em lote consiste em várias chamadas da API combinadas em uma única solicitação HTTP. Esta seção descreve a sintaxe do lote em detalhes. Posteriormente, haverá um exemplo.

Observação: um conjunto de n solicitações colocadas em lote é contabilizado no seu limite de uso como n solicitações, e não como uma solicitação. A solicitação em lote é desmembrada em um conjunto de solicitações antes do processamento.

Formato de uma solicitação em lote

Uma solicitação em lote é uma única solicitação HTTP padrão que contém várias chamadas da Google Analytics API, usando o tipo de conteúdo multipart/mixed. Nessa solicitação HTTP principal, cada parte contém uma solicitação HTTP aninhada.

Cada parte começa com seu próprio cabeçalho HTTP Content-Type: application/http. Elas também podem ter um cabeçalho Content-ID opcional. No entanto, os cabeçalhos das partes estão presentes apenas para marcar o início da parte. Eles são separados da solicitação aninhada. Depois que o servidor desmembra a solicitação em lote em solicitações diferentes, os cabeçalhos das partes são ignorados.

O corpo de cada parte é uma solicitação HTTP completa, com seu próprio verbo, URL, cabeçalhos e corpo. A solicitação HTTP precisa conter somente a parte do caminho do URL. URLs completos não são permitidos em solicitações em lote.

Os cabeçalhos HTTP da solicitação em lote externa, exceto os cabeçalhos Content-, como Content-Type, são aplicáveis a todas as solicitações do lote. Se você especificar determinado cabeçalho HTTP na solicitação externa e em uma chamada individual, o valor do cabeçalho da chamada individual substitui o valor do cabeçalho da solicitação em lote externa. Os cabeçalhos de uma chamada individual são aplicáveis somente à chamada em questão.

Por exemplo, se você fornecer um cabeçalho de autorização para uma chamada específica, esse cabeçalho será aplicável somente à chamada em questão. Se você fornecer um cabeçalho de autorização para a solicitação externa, esse cabeçalho será aplicável a todas as chamadas individuais, a menos que elas o substituam por cabeçalhos de autorização próprios.

Quando o servidor receber a solicitação em lote, ele aplicará os cabeçalhos e parâmetros de consulta da solicitação externa (conforme for apropriado) a cada parte e tratará cada uma delas como se fosse uma solicitação HTTP diferente.

Resposta a uma solicitação em lote

A resposta do servidor é uma única resposta HTTP padrão com tipo de conteúdo multipart/mixed. Cada parte é a resposta a uma das solicitações da solicitação em lote, na mesma ordem que as solicitações.

Assim como as partes da solicitação, cada parte da resposta contém uma solicitação HTTP completa, incluindo um código de status, cabeçalhos e corpo. Além disso, assim como as partes da solicitação, cada parte da resposta é precedida por um cabeçalho Content-Type que marca o início da parte.

Se determinada parte da solicitação tiver um cabeçalho Content-ID, a parte correspondente da resposta terá um cabeçalho Content-ID correspondente, com o valor original precedido pela string response-, conforme mostrado no exemplo a seguir.

Observação: o servidor faz suas chamadas em qualquer ordem. Não espere que elas sejam executadas na ordem em que você as especificou. Se você quiser garantir que duas chamadas ocorram em determinada ordem, não as envie em uma única solicitação. Envie a primeira chamada sozinha e aguarde a resposta a ela antes de enviar a segunda.

Exemplo

O exemplo a seguir mostra o uso de lotes com a Google Analytics API.

Exemplo de solicitação em lote

POST /batch 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--

Exemplo de resposta em lote

Esta é a resposta ao exemplo de solicitação da seção anterior.

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

Bibliotecas cliente

Use os guias de bibliotecas cliente a seguir para ver como implementar os lotes na sua linguagem:

Lotes e a cota do Google Analytics

Embora os lotes possam ser úteis para reduzir a sobrecarga da criação de muitas solicitações HTTP, cada solicitação da Google Analytics API em uma solicitação em lote será contabilizada para sua cota diária do projeto. Por padrão, um projeto pode fazer até 50.000 solicitações por dia. Os lotes não ajudarão você a permanecer abaixo dessa cota.

Com exceção das solicitações de criação de permissões do usuário (exclusão, inserção, atualização), todos os limites de taxa continuarão sendo aplicados. Por exemplo, a Core Reporting API é limitada a 10 solicitações simultâneas por vista (perfil). Os lotes não ajudarão você a permanecer abaixo desse limite.

O limite de 1,5 consulta por segundo (QPS, na sigla em inglês) por ID de conta se aplica às solicitações de gravação da Management API e às solicitações de gravação da Provisioning API. Dessa forma, reunir essas solicitações de gravação em lote não melhora o desempenho.