En esta guía se indica cómo realizar la migración de la versión 3 de la API de informes centrales a la versión 4 de la API de informes de Analytics.
Introducción
Si quieres aprovechar las ventajas que ofrecen las nuevas funciones de la versión 4 de la API de informes de Analytics, migra tu código para que use la API. En la guía se muestran ejemplos de solicitudes de la versión 3 de la API de informes centrales y sus equivalentes en la versión 4 de la API de informes de Analytics para facilitarte la migración.
Migración en Python
Si utilizas el lenguaje de programación Python, debes usar la biblioteca auxiliar GAV4 de GitHub para convertir las solicitudes de la versión 3 de la API de informes centrales de Google Analytics en solicitudes de la versión 4 de la API de informes de Analytics.
Extremos
Los extremos y métodos HTTP de ambas API son distintos:
Extremo de la versión 3
GET https://www.googleapis.com/analytics/v3/data/ga
Extremo de la versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
En los siguientes ejemplos se compara una solicitud enviada en la versión 3 con su equivalente en la versión 4:
Versión 3
Documentación de referencia de la versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
Versión 4
Documentación de referencia de la versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
Bibliotecas de cliente y servicio de detección
Si utilizas Python, JavaScript u otra biblioteca de cliente que emplee el servicio de detección de Google, debes indicar la ubicación del documento de detección para la versión 4 de la API de informes.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
Las bibliotecas de cliente de Java y PHP están predefinidas, pero puedes usar el servicio de detección y el generador de APIs de Google para generarlas.
Solicitudes
En la referencia de la versión 4 de la API se proporciona una descripción detallada de la estructura del cuerpo de la solicitud. En las secciones siguientes se describe la migración de los parámetros de solicitud de la versión 3 a los parámetros de solicitud de la versión 4.
IDs de vista
En la versión 3, el parámetro ids
, que admite un ID de tabla, presenta el formato ga:XXXX
, donde XXXX
es el ID de vista (perfil). En la versión 4, el ID de vista (perfil) se especifica en el campo viewId
del cuerpo de la solicitud.
En los ejemplos siguientes se compara el parámetro ids
de una solicitud enviada con la versión 3 con el campo viewId
de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Periodos
Con la versión 4 de la API de informes de Analytics puedes especificar varios periodos en una sola solicitud. El campo dateRanges
admite una lista de objetos DateRange.
En la versión 3, se usan los parámetros start-date
y end-date
para especificar un periodo en una solicitud.
En los ejemplos siguientes se comparan los parámetros start-date
y end-date
de una solicitud enviada con la versión 3 con el campo dateRanges
de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
Métricas
El parámetro metrics
de la versión 3 corresponde al campo metrics
de la versión 4, que admite una lista de objetos Metric.
En los ejemplos siguientes se comparan los parámetros metrics
de una solicitud enviada con la versión 3 con el campo metrics
de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
Dimensiones
El parámetro dimensions
de la versión 3 corresponde al campo dimensions
de la versión 4, que admite una lista de objetos Dimension.
En los ejemplos siguientes se comparan los parámetros dimensions
de una solicitud enviada con la versión 3 con el campo dimensions
de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Orden
El parámetro sort
de la versión 3 corresponde al campo orderBys
de la versión 4, que admite una lista de objetos OrderBy.
Para ordenar los resultados por un valor de dimensión o métrica en la versión 4:
- Indica el nombre o el alias en el campo
fieldName
. - Indica cómo quieres ordenar los resultados (
ASCENDING
oDESCENDING
) en el camposortOrder
.
En los ejemplos siguientes se compara el parámetro sort
de una solicitud enviada con la versión 3 con el campo orderBy
de una solicitud enviada con la versión 4. En ambas solicitudes los usuarios se clasifican en sentido descendente y los recursos en orden alfabético:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
Nivel de muestreo
El parámetro samplingLevel
de la versión 3 corresponde al campo samplingLevel
de la versión 4. En la versión 3, los valores de samplingLevel
admitidos son FASTER
, HIGHER_PRECISION
y DEFAULT
. En la versión 4, los valores de samplingLevel
admitidos son SMALL
, LARGE
y DEFAULT
. Ten en cuenta que el valor FASTER
de la versión 3 se ha convertido en SMALL
en la versión 4 y el valor HIGHER_PRECISION
en LARGE
.
En los ejemplos siguientes se compara el parámetro samplingLevel
de una solicitud enviada con la versión 3 con el campo samplingLevel
de una solicitud enviada con la versión 4:
Versión 3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
Segmentos
El parámetro segment
de la versión 3 corresponde al campo segments
de la versión 4, que admite una lista objetos Segment.
IDs de segmento
En la versión 4, para solicitar un segmento por ID de segmento, debes crear un segmento e introducir el ID correspondiente en el campo segmentId.
En los ejemplos siguientes se compara el parámetro segment
de una solicitud enviada con la versión 3 con el campo segments
de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
Segmentos dinámicos
En la versión 4, para expresar definiciones de segmento más complejas usa el campo segments
, que incluye un objeto DynamicSegment.
En los ejemplos siguientes se compara el parámetro segment
de una solicitud enviada con la versión 3 con el campo segments
, que contiene un objeto DynamicSegment
, de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
Puedes combinar condiciones y secuencias en un mismo segmento:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
Versión 4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
Sintaxis de segmentos de la versión 3 en la versión 4
El campo segmentId de la API, versión 4 admite la sintaxis de segmentos de la API, versión 3.
En los ejemplos siguientes se muestra cómo el parámetro segment
de una solicitud enviada con la versión 3 se admite en el campo segmentId
de la solicitud equivalente en la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filtros
La versión 4 utiliza el parámetro dimensionFilterClauses
para filtrar dimensiones y metricFilterClauses
para filtrar métricas. dimensionFilterClauses
incluye una lista de objetos DimensionFilter y metricFilterClauses
incluye una lista de objetos MetricFilter.
En los ejemplos siguientes se compara el parámetro filters
de una solicitud enviada con la versión 3 con el campo dimensionFilterClauses
de una solicitud enviada con la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
Versión 4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
Sintaxis de filtros de la versión 3 en la versión 4
Aunque el campo filtersExpression de la versión 4 admite la sintaxis filters
de la versión 3, utiliza los parámetros dimensionFilterClauses
y metricFilterClauses
para filtrar dimensiones y métricas.
En los ejemplos siguientes se muestra cómo el parámetro filters
de una solicitud enviada con la versión 3 se admite en el campo filtersExpression
de la solicitud equivalente en la versión 4:
Versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
Filas vacías
El parámetro include-empty-rows
de la versión 3 corresponde al campo includeEmptyRows
de la versión 4. En la versión 3, el valor predeterminado de este parámetro es true, mientras que en la versión 4, el valor predeterminado del campo es false. Si no has definido el valor en la versión 3, deberás definirlo como true en la versión 4.
En los ejemplos siguientes se compara el parámetro include-empty-rows
de una solicitud enviada con la versión 3 con el campo includeEmptyRows
de una solicitud enviada con la versión 4:
Versión 3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Paginación
En la versión 4 se usan los campos pageToken
y pageSize
para paginar un gran número de resultados. El valor de pageToken
se obtiene de la propiedad nextPageToken
de un objeto de respuesta.
En los ejemplos siguientes se comparan los parámetros start-index
y max-results
de una solicitud enviada con la versión 3 con los campos pageToken
y pageSize
de una solicitud enviada con la versión 4:
Versión 3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
Versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Parámetros estándar
La versión 4 de la API de informes de Analytics admite la mayoría de los parámetros de consulta estándar de la versión 3 de la API, salvo userIp
y callback
.
En los ejemplos siguientes se compara el parámetro quotaUser
de una solicitud enviada con la versión 3 con el parámetro correspondiente de una solicitud enviada con la versión 4:
Extremo de la versión 3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
Extremo de la versión 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Respuestas
La versión 4 permite enviar varios objetos ReportRequest en una sola solicitud HTTP, por lo que puedes obtener una matriz de objetos de informe en la respuesta. Por cada objeto ReportRequest enviado, se obtiene el informe correspondiente en la respuesta.
Informes
Los informes de la versión 4 tienen tres campos de nivel superior: columnHeader
, data
y nextPageToken
.
A diferencia de lo que ocurre en la versión 3, en la versión 4 el cuerpo de respuesta no incluye respuestas a todos los parámetros de consulta, por lo que para obtener una respuesta a un parámetro de consulta concreto la aplicación cliente debe incluir dicho parámetro en el objeto ReportRequest.
Puesto que ya hemos visto el valor de nextPageToken
en la sección Paginación, ahora nos centraremos en el objeto columnHeader.
Encabezado de columna
El encabezado de columna contiene una lista de dimensiones concretas y un objeto MetricHeader, que incluye una lista de objetos MetricHeaderEntry. En cada objeto MetricHeaderEntry se especifica el nombre de la métrica (name
) y su tipo (type
), es decir, moneda, porcentaje, etc.,
lo que ayuda a dar formato al resultado.
En los ejemplos siguientes se compara el campo columnHeaders
de una respuesta obtenida con la versión 3 con el campo columnHeader
de una respuesta obtenida con la versión 4:
Versión 3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
Versión 4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Filas de informes
La versión 3 de la API de informes centrales devuelve los datos del informe en la matriz rows, que contiene las dimensiones y las métricas solicitadas.
La versión 4 de la API de informes de Analytics devuelve los datos del informe en un objeto ReportRow, que contiene una matriz de dimensiones y una matriz de objetos DateRangeValues, cada uno de los cuales incluye uno o dos periodos, como se ilustra en el siguiente diagrama:
Filas
Versión 3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
Versión 4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
Muestras de datos
Si los resultados son una muestra de datos, la versión 3 de la API de informes centrales devuelve el campo booleano containsSampledData
con el valor true
.
La versión 4 de la API de informes de Analytics no devuelve ningún campo booleano si los datos son una muestra; devuelve los campos samplesReadCounts
y samplingSpaceSizes
.
Si los resultados no son una muestra de datos, estos campos no se definen.
En el ejemplo de Python siguiente se indica cómo calcular si un informe contiene muestras de datos:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
A continuación se incluye una respuesta de ejemplo que contiene una muestra de datos de una solicitud con dos periodos distintos. Para calcular los resultados se utilizaron prácticamente 500.000 muestras con un tamaño de muestra aproximado de 15 millones de sesiones:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Analizar la respuesta en la versión 4
En el código de ejemplo siguiente se analiza y se imprime la respuesta de la versión 4 de la API de informes de Analytics:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
Gestión de errores
El formato de las respuestas de error que se devuelven en la versión 4 es distinto del formato que se utiliza en la versión 3, por lo que te recomendamos que actualices tu código para poder gestionar las respuestas de error en la versión 4.
En los siguientes ejemplos se compara una respuesta de error que se ha devuelto en la versión 3 con su equivalente en la versión 4:
Versión 3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
Versión 4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}