Procesar por lotes las solicitudes de la API de Google Analytics

Global HTTP Batch Endpoints (www.googleapis.com/batch) dejará de funcionar el 25 de marzo del 2019, tal y como se anunció en una de las entradas del blog de Google Developers. En su lugar, sigue las instrucciones de la entrada de blog para utilizar solicitudes por lotes homogéneas en los correspondientes puntos de conexión de la API (www.googleapis.com/batch/api/version).

En este documento se muestra cómo hacer llamadas a la API en bloque para reducir el número de conexiones HTTP que tiene que realizar tu cliente.

En el documento se trata específicamente cómo hacer una solicitud en bloque enviando una solicitud HTTP. Si utilizas una biblioteca de cliente de Google para dicha solicitud, consulta la documentación de la biblioteca del cliente.

Descripción general

Las conexiones HTTP que realiza tu cliente generan un determinado volumen de sobrecarga. La API de Google Analytics admite el procesamiento por lotes para que tu cliente incluya varias llamadas a la API en una única solicitud HTTP.

A continuación te presentamos algunas situaciones en las que se puede utilizar el procesamiento por lotes:

En cada caso, en vez de enviar las llamadas por separado, puedes agruparlas en una solicitud HTTP. Todas las solicitudes deben dirigirse a la misma API de Google.

Cada solicitud por lotes puede incluir un máximo de 1000 llamadas. Si tienes que hacer más llamadas, usa varias solicitudes por lotes.

Nota: El sistema por lotes de la API de Google Analytics usa la misma sintaxis que el sistema de procesamiento por lotes OData, pero con una semántica distinta.

Detalles del lote

Una solicitud por lotes consta de varias llamadas a la API combinadas en una solicitud HTTP, que puede enviarse a la ruta del lote batchPath indicada en el documento de detección de la API. La ruta predeterminada es /batch/api_name/api_version. En esta sección se ofrece una descripción detallada de la sintaxis del lote y más adelante se incluye un ejemplo.

Nota: Un grupo de n solicitudes agrupadas en un lote se descuenta del límite de uso como n solicitudes, no como una única solicitud. La solicitud por lotes se descompone en un conjunto de solicitudes antes de procesarse.

Formato de la solicitud por lotes

Una solicitud por lotes es una solicitud HTTP estándar que contiene varias llamadas a la API de Google Analytics utilizando el tipo de contenido multipart/mixed. En esa solicitud HTTP principal, cada una de las partes contiene una solicitud HTTP anidada.

Cada parte comienza con su propio encabezado HTTP Content-Type: application/http. También tiene un encabezado Content-ID opcional. No obstante, la única finalidad de los encabezados de parte es marcar el comienzo de cada parte y separarla de la solicitud anidada. Después de que el servidor desglose la solicitud por lotes en solicitudes independientes, se ignoran los encabezados de parte.

El cuerpo de cada parte es una solicitud HTTP completa, con su propio verbo, URL, encabezados y cuerpo. La solicitud HTTP solo debe contener el fragmento de ruta de la URL, ya que en las solicitudes por lotes no se permiten las URL completas.

Los encabezados HTTP de la solicitud por lotes contenedora, a excepción de los encabezados de tipo Content-, como Content-Type, se aplican a todas las solicitudes del lote. Si especificas un determinado encabezado HTTP en la solicitud contenedora y una llamada individual, el valor del encabezado de la llamada anula el de la solicitud contenedora. Los encabezados de una llamada solo se aplican a dicha llamada.

Por ejemplo, si proporcionas un encabezado Authorization para una determinada llamada, dicho encabezado se aplica únicamente a la llamada. Si proporcionas un encabezado Authorization para la solicitud contenedora, se aplicará a todas las llamadas a menos que estas lo anulen con sus propios encabezados.

Cuando el servidor recibe la solicitud por lotes, aplica los parámetros de consulta y los encabezados de la solicitud contenedora (según proceda) a cada parte, que trata como si fuera una solicitud HTTP independiente.

Respuesta a una solicitud por lotes

La respuesta del servidor es una respuesta HTTP estándar con el tipo de contenido multipart/mixed. Cada parte es la respuesta a una de las solicitudes que componen la solicitud por lotes en el mismo orden que las solicitudes.

Al igual que las partes de la solicitud, cada parte de respuesta contiene una respuesta HTTP completa, incluyendo el código de estado, los encabezados y el cuerpo. Y, al igual que las partes de la solicitud, cada parte de respuesta va precedida de un encabezado Content-Type que marca su comienzo.

Si una parte de la solicitud tenía un encabezado Content-ID, la parte correspondiente de la respuesta también tiene un encabezado Content-ID precedido de la cadena response-, tal como se muestra en el ejemplo siguiente.

Nota: El servidor puede realizar las llamadas en cualquier orden. No confíes en que se ejecutarán en el orden en el que las has especificado. Si quieres asegurarte de que dos llamadas se realicen en un orden concreto, no puedes enviarlas en una única solicitud, sino que debes enviar primero una y esperar la respuesta a la primera antes de enviar la segunda.

Ejemplo

En el ejemplo siguiente se muestra el uso del proceso por lotes con la API de Google Analytics.

Solicitud por lotes de ejemplo

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

Respuesta por lotes de ejemplo

La respuesta a la solicitud de ejemplo de la sección anterior es la siguiente:

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

Consulta en las siguientes guías de las bibliotecas de cliente el modo de implementar el procesamiento por lotes en tu lenguaje:

Proceso por lotes y cuota de Google Analytics

Aunque el proceso por lotes te puede ahorrar la tarea de crear muchas solicitudes HTTP, cada solicitud a la API de Google Analytics de una solicitud por lotes cuenta para la cuota de proyecto diaria. De forma predeterminada, un proyecto se puede componer de un máximo de 50.000 solicitudes al día y el procesamiento por lotes no impide que se supere la cuota.

A excepción de las solicitudes de escritura (suprimir, insertar o actualizar) de los permisos de usuario, se aplican todos los límites de frecuencia. Por ejemplo, la API de informes centrales tiene un límite de 10 solicitudes simultáneas por vista (perfil) y el procesamiento por lotes no impide que se supere este límite.

El límite de 1,5 consultas por segundo (QPS) por ID de cuenta se aplica a las solicitudes de escritura de la API de administración y a las de la API de aprovisionamiento. Por lo tanto, es posible que el rendimiento no mejore si estas solicitudes de escritura se procesan por lotes.