Guía de migración

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

Para aprovechar las ventajas que ofrecen las nuevas funciones de la versión 4 de la API de informes de Analytics, migra tu código de modo 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.

Puntos finales

La versión 3 de la API de informes centrales y la versión 4 de la API de informes de Analytics tienen puntos finales y métodos HTTP distintos:

Punto final de la versión 3

GET https://www.googleapis.com/analytics/v3/data/ga

Punto final de la versión 4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

En los siguientes ejemplos se compara una solicitud realizada 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 proporcionar 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 Java y PHP están predefinidas, pero puedes usar el servicio de detección y el generador de las API 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 acepta un "ID de tabla", presenta el formato ga:XXXX, de forma que 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 realizada con la versión 3 con el campo viewId de una solicitud realizada 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

La versión 4 de la API de informes de Analytics te permite especificar varios periodos en una sola solicitud. El campo dateRanges utiliza una lista de objetos DateRange. En la versión 3, se utilizan 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 realizada con la versión 3 con el campo dateRanges de una solicitud realizada 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 utiliza una lista de objetos Metric.

En los ejemplos siguientes se comparan los parámetros metrics de una solicitud realizada con la versión 3 con el campo metrics de una solicitud realizada 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 utiliza una lista de objetos Dimension.

En los ejemplos siguientes se comparan los parámetros dimensions de una solicitud realizada con la versión 3 con el campo dimensions de una solicitud realizada 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"
    }],
    ...
  }]
}

Ordenar los elementos

El parámetro sort de la versión 3 corresponde al campo orderBys de la versión 4, que utiliza 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 de la dimensión o la métrica en el campo fieldName.
  • Indica cómo quieres ordenar los resultados (ASCENDING o DESCENDING) en el campo sortOrder.

En los ejemplos siguientes se compara el parámetro sort de una solicitud realizada con la versión 3 con el campo orderBy de una solicitud realizada 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 realizada con la versión 3 con el campo samplingLevel de una solicitud realizada 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 utiliza 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 facilitar el ID correspondiente en el campo segmentId.

En los ejemplos siguientes se compara el parámetro segment de una solicitud realizada con la versión 3 con el campo segments de una solicitud realizada 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 realizada con la versión 3 con el campo segments, que contiene un objeto DynamicSegment, de una solicitud realizada 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 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 versión 4 de la API admite la sintaxis de segmentos de la versión 3 de la API.

En los ejemplos siguientes se muestra cómo el parámetro segment de una solicitud realizada con la versión 3 se admite en el campo segmentId de la solicitud correspondiente 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 métodos dimensionFilterClauses para filtrar dimensiones y métodos 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 realizada con la versión V3 con el campo dimensionFilterClauses de una solicitud realizada 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 métodos dimensionFilterClauses y metricFilterClauses para filtrar dimensiones y métricas.

En los ejemplos siguientes se muestra cómo el parámetro filters de una solicitud realizada con la versión 3 se admite en el campo filtersExpression de la solicitud correspondiente de 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 realizada con la versión 3 con el campo includeEmptyRows de una solicitud realizada 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

La versión 4 utiliza 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 realizada con la versión 3 con los campos pageToken y pageSize de una solicitud realizada 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 realizada con la versión 3 con el parámetro correspondiente de una solicitud realizada con la versión 4:

Punto final de la versión 3

GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2

Punto final 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. Cada objeto ReportRequest enviado, 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 de MetricHeaderEntry. En cada objeto MetricHeaderEntry se especifica el nombre (name) de la métrica y su tipo (type), es decir moneda, porcentaje, etc., lo que ayuda a formatear el 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 dibujo:

Filas de informes

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"
                ]
            }
        ]
    }
],

Datos de muestra

Si los resultados se muestrean, la versión 3 de la API de informes centrales devuelve el campo booleano containsSampledData, que se define utilizando el valor true.

La versión 4 de la API de informes de Analytics no devuelve ningún campo booleano si los datos se muestrean, sino que devuelve los campos samplesReadCounts y samplingSpaceSizes. Si no se aplica el muestreo a los resultados, estos campos no se definen. En el ejemplo de Python siguiente se muestra cómo calcular si un informe contiene datos de muestra:

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 datos de muestra 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));
        }
      }
    }
  }
}