En esta guía, se proporcionan lineamientos para migrar la versión 3 de la API de Core Reporting a la API de Analytics Reporting v4.
Introducción
Si quieres aprovechar las nuevas funciones que se introdujeron en la API de Analytics Reporting v4, migra tu código para usar la API. En esta guía, se muestran las solicitudes en la API de Core Reporting v3 y las solicitudes equivalentes en la API de Analytics Reporting v4 para facilitar la migración.
Migración de Python
Si eres desarrollador de Python, usa la biblioteca auxiliar GAV4 en GitHub para convertir las solicitudes de la versión 3 de la API de Google Analytics Core Reporting en las solicitudes de la versión 4 de la API de Analytics Reporting
Extremos
La API de Core Reporting v3 y la API de Analytics Reporting v4 tienen extremos y métodos HTTP diferentes:
Extremo v3
GET https://www.googleapis.com/analytics/v3/data/ga
Extremo v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
En los siguientes ejemplos se compara una solicitud en la v3 y la solicitud equivalente en la v4:
v3
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
v4
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 cliente y servicio de descubrimiento
Si usas la biblioteca cliente de Python, JavaScript o alguna otra que se basa en el servicio de Google Discovery, debes proporcionar la ubicación del documento de descubrimiento para la API de Reporting v4.
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 cliente de Java y PHP están compiladas previamente, pero puedes usar el servicio de descubrimiento y el generador de las APIs de Google para generarlas.
Solicitudes
En la referencia de la API v4, se describe en detalle la estructura del cuerpo de la solicitud. En las siguientes secciones, se describe la migración de parámetros de solicitud de v3 a parámetros de solicitud de v4.
Ver IDs
En la versión 3, un parámetro ids, que acepta un "ID de tabla", tiene el formato ga:XXXX, en el que XXXX es el ID de la 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 siguientes ejemplos, se compara el parámetro ids en una solicitud v3 y el campo viewId
en una solicitud v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Intervalos de fechas
La API de Analytics Reporting v4 te permite especificar varios períodos
en una sola solicitud. El campo dateRanges toma una lista de objetos DateRange.
En la versión 3, se usan los parámetros start-date y end-date para especificar un período en una solicitud.
En los siguientes ejemplos, se comparan los parámetros start-date y end-date en una solicitud v3
y el campo dateRanges en una solicitud v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
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 toma una lista de objetos Métricas.
En los siguientes ejemplos, se comparan los parámetros metrics en una solicitud v3
y el campo metrics en una solicitud v4:
v3
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 \
...
v4
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 toma una lista de objetos Dimensión.
En los siguientes ejemplos, se comparan los parámetros dimensions en una solicitud v3
y el campo dimensions en una solicitud v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Ordena
El parámetro sort de la versión 3 es equivalente al campo orderBys de la versión 4 que toma una lista de objetos OrderBy.
En la versión 4, para ordenar los resultados por el valor de una dimensión o métrica, sigue estos pasos:
- Proporciona su nombre o alias a través del campo
fieldName. - Especifica el orden de clasificación (
ASCENDINGoDESCENDING) a través del camposortOrder.
En los siguientes ejemplos, se compara el parámetro sort en una solicitud v3
y el campo orderBy en una solicitud v4. Ambos ordenan los usuarios
en orden descendente y las fuentes alfabéticamente:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
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 aceptados son FASTER, HIGHER_PRECISION y DEFAULT. En la versión 4, los valores de samplingLevel aceptados son SMALL, LARGE y DEFAULT.
Ten en cuenta que FASTER en la versión 3 cambió a SMALL en la versión 4 y de HIGHER_PRECISION a LARGE.
En los siguientes ejemplos, se compara el parámetro samplingLevel en una solicitud v3
y el campo samplingLevel en una solicitud v4:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
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 toma una lista de objetos Segment.
IDs de segmento
En la versión 4, para solicitar un segmento por ID de segmento, debes crear un objeto Segment y proporcionar su ID mediante el campo segmentId.
En los siguientes ejemplos, se compara el parámetro segment en una solicitud v3
y el campo segments en una solicitud v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
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 segmentos más complicadas, usa el campo segments que incluye un objeto DynamicSegment.
En los siguientes ejemplos, se compara el parámetro segment en una solicitud v3
y el campo segments que contiene un objeto DynamicSegment en una solicitud v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
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 segmento:
v3
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
v4
"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 la versión 3 de los segmentos en la versión 4
El campo segmentId en la API v4 admite la sintaxis de segmentos en la API v3.
En los siguientes ejemplos, se muestra cómo el parámetro segment de una solicitud de la versión 3
es compatible con el campo segmentId de la solicitud equivalente en la versión 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filtros
La versión 4 usa dimensionFilterClauses para filtrar dimensiones y metricFilterClauses para filtrar métricas. Un dimensionFilterClauses contiene una lista de objetos DimensionFilter y un metricFilterClauses contiene una lista de objetos MetricFilter.
En los siguientes ejemplos, se compara el parámetro filters en una solicitud v3
y el campo dimensionFilterClauses en una solicitud v4:
v3
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
v4
"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 en la versión 4 admite la sintaxis filters en la versión 3, debes usar dimensionFilterClauses y metricFilterClauses para filtrar dimensiones y métricas.
En los siguientes ejemplos, se muestra cómo el parámetro filters de una solicitud de la versión 3
es compatible con el campo filtersExpression de la solicitud equivalente en la versión 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
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. El parámetro predeterminado de la v3 es true, mientras que, en la v4, el campo
es false. Si no tienes el valor establecido en la versión 3, tendrás que establecer el valor en true en la versión 4.
En los siguientes ejemplos, se compara el parámetro include-empty-rows en una solicitud v3 con el campo includeEmptyRows en una solicitud v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Paginación
La versión 4 usa los campos pageToken y pageSize para paginar una gran cantidad de resultados. El pageToken se obtiene de la propiedad nextPageToken de un objeto de respuesta.
En los siguientes ejemplos, se comparan los parámetros start-index y max-results
de una solicitud de v3 con los campos pageToken y pageSize de una solicitud de v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
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 API de Analytics Reporting v4 admite la mayoría de los
parámetros de consulta estándar
de la API v3, excepto los parámetros userIp y callback.
En los siguientes ejemplos, se compara el parámetro quotaUser de una solicitud de la versión 3 con el de una solicitud de la versión 4:
Extremo v3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
Extremo v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Respuestas
Debido a que v4 te permite enviar varios objetos ReportRequest en una sola solicitud HTTP, obtienes un array de objetos de informe en la respuesta. Por cada ReportRequest que envíes, recibirás el Report correspondiente en la respuesta.
Informes
Un Informe v4 tiene tres campos de nivel superior: columnHeader, data y nextPageToken.
Debido a que el cuerpo de la respuesta v4 no incluye respuestas a todos los parámetros de consulta como lo hace la respuesta de v3, para obtener una respuesta a un parámetro de consulta específico, la aplicación cliente debe agregar ese parámetro a ReportRequest.
Ya tratamos nextPageToken en la sección Paginación, así que primero veamos el objeto columnHeader.
Encabezado de columna
El encabezado de la columna contiene una lista de dimensiones con nombre y un objeto MetricHeader, que incluye una lista de objetos MetricHeaderEntry. Cada objeto MetricHeaderEntry especifica la métrica name y su type (moneda, porcentaje, etcétera).
, que te ayuda a dar formato a la salida.
En los siguientes ejemplos, se compara el campo columnHeaders de una respuesta de la versión v3 con el campo de columnHeader de una respuesta de la versión v4:
v3
"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"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Filas del informe
La versión 3 de la API de Core Reporting muestra los datos de informes en el array de rows, que contiene las dimensiones y métricas solicitadas.
La versión 4 de la API de Analytics Reporting muestra los datos de informes en un objeto ReportRow, que contiene un array de dimensiones y un array de objetos DateRangeValues, cada uno de los cuales contiene uno o dos períodos, como se muestra en el siguiente diagrama:
Filas
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"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 se muestrean, la API de Core Reporting v3 muestra el campo booleano containsSampledData, que se establece en true.
La API de Analytics Reporting v4 no muestra un valor booleano si los datos están muestreados. En cambio, la API muestra los campos samplesReadCounts y samplingSpaceSizes.
Si los resultados no se muestrean, estos campos no se definirán.
En el siguiente ejemplo de Python, se muestra cómo calcular si un informe contiene una muestra 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 un ejemplo de respuesta que contiene datos muestreados de una solicitud con dos períodos. Los resultados se calcularon a partir de casi 500,000 muestras de un espacio de muestra de aproximadamente 15 millones de sesiones:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Análisis de la respuesta de la versión 4
En el siguiente código de muestra, se analiza y se imprime la respuesta de la API de Analytics Reporting v4:
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));
}
}
}
}
}
Manejo de errores
Debido a que el formato de respuesta de error en la versión 4 es diferente al de la versión 3, actualiza el código para manejar las respuestas de error de la versión 4.
En los siguientes ejemplos, se compara una respuesta de error en la versión 3 y la respuesta de error equivalente en la versión 4:
v3
{
"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."
}
}
v4
{
"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.\" }"
}
]
}
}