En este documento, se proporcionan instrucciones para migrar el código existente de la API de Google Analytics Reporting v4 a la API de datos de Google Analytics v1 y se proporciona una breve descripción general de las diferencias clave entre las dos APIs.
Por qué necesito realizar la migración
Si tu aplicación necesita acceder a los datos de una propiedad Google Analytics 4, debes actualizar el código para usar la versión 1 de la API de datos, ya que la API de informes v4 solo puede acceder a las propiedades creadas con Universal Analytics.
Requisitos previos
Familiarízate con los conceptos básicos de la API de datos v1 mediante la guía de inicio rápido.
Primeros pasos
Para comenzar, prepararás una propiedad Google Analytics 4, habilitarás la versión 1 de la API de datos y, luego, configurarás una biblioteca cliente de API adecuada para tu plataforma.
Prepara una propiedad Google Analytics 4
Antes de comenzar a migrar tu código para admitir la API de datos v1, debes migrar tu sitio web para usar una propiedad Google Analytics 4. No es posible reabastecer una propiedad Google Analytics 4 con datos históricos de una propiedad Universal Analytics.
Habilita la API
Haz clic en este botón para habilitar automáticamente la API de datos v1 en el proyecto de Google Cloud seleccionado.
Habilitar la versión 1 de la API de datos de Google AnalyticsUtilizar una biblioteca cliente
Instalar una biblioteca cliente
Si usas una biblioteca cliente, debes instalar la biblioteca cliente v1 de la API de datos para tu lenguaje de programación.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Cómo inicializar una biblioteca cliente
Las bibliotecas cliente de la versión 1 de la API de datos se diseñaron para que puedas comenzar rápidamente. Según la configuración predeterminada, las bibliotecas cliente intentan encontrar automáticamente las credenciales de tu cuenta de servicio.
Una manera fácil de proporcionar credenciales de cuenta de servicio es mediante la configuración de la variable de entorno GOOGLE_APPLICATION_CREDENTIALS. El cliente de la API usará el valor de esta variable para buscar el archivo JSON de la clave de la cuenta de servicio.
Por ejemplo, para configurar las credenciales de la cuenta de servicio, ejecuta el siguiente comando y usa la ruta de acceso al archivo JSON de la cuenta de servicio:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
A continuación, se muestran los fragmentos de código que se usan comúnmente para inicializar las bibliotecas cliente de la versión 1 de la API de datos.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
En lugar de usar una variable de entorno, también es posible pasar la información de credenciales a una instancia de cliente de API de forma explícita durante la inicialización. A continuación, se muestran los fragmentos que se usan para inicializar las bibliotecas cliente de la versión 1 de la API de datos pasando las credenciales de forma explícita en el código.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
No usar una biblioteca cliente
Si usabas la versión 4 de la API de Reporting sin una biblioteca cliente y deseas seguir haciéndolo con la versión 1 de la API de datos, puedes usar tus credenciales.
Debes usar el nuevo documento de extremo HTTP y descubrimiento que proporciona la API de datos:
Si tu código aprovecha un documento de descubrimiento, debes actualizarlo al documento de descubrimiento que proporciona la API de datos v1:
Después de actualizar el extremo, deberás familiarizarte con la nueva estructura de solicitud y los conceptos de la API de datos para actualizar tu consulta JSON.
Informes principales
Métodos de informes disponibles
La API de Reporting v4 ofrecía un método único batchGet para acceder a su funcionalidad de informes principal. La API de datos v1 proporciona varios métodos principales de informes entre los que puedes elegir:
- runReport Este método muestra un informe personalizado de los datos de eventos de Google Analytics. No admite la funcionalidad de tabla dinámica y es un método preferido para las consultas de informes simples.
- runPivotReport Este método muestra un informe de redireccionamiento personalizado de tus datos de eventos de Google Analytics. Al igual que las tablas dinámicas en la versión 4 de la API de Reporting, cada una describe las columnas y filas de dimensiones visibles en la respuesta del informe.
- batchRunReports es una versión por lotes del método
runReportque permite generar varios informes con una sola llamada a la API. - batchRunPivotReports es una versión por lotes del método
runPivotReportque permite generar varios informes con una sola llamada a la API.
El propósito de tener varios métodos de informes es mayormente conveniente, ya que algunos métodos admiten funciones más complejas que otros (elementos dinámicos y lotes), pero comparten una estructura de solicitud similar.
Cambios en el esquema de la API
Las capacidades de generación de informes tanto de la API de Reporting como de la API de datos se determinan principalmente por su esquema, es decir, las dimensiones y métricas admitidas en las consultas de informes. Existen diferencias significativas en los esquemas de API entre las dos APIs, debido a las diferencias conceptuales entre Universal Analytics y Google Analytics 4.
- Familiarízate con la lista de dimensiones y métricas actual compatible con la API de datos. Actualmente, todas las dimensiones y métricas son compatibles entre sí, por lo que no es necesario usar el Explorador de dimensiones y métricas para determinar las combinaciones compatibles. Este comportamiento cambiará en el futuro.
- Se puede acceder a las dimensiones personalizadas en Google Analytics 4 con la sintaxis de dimensiones personalizadas de la versión 1 de la API de datos, que se debe usar en lugar de las ranuras de dimensiones ga:dimensionXX de la API de Reporting v4.
- Se puede acceder a las métricas personalizadas en Google Analytics 4 con la sintaxis de métricas personalizadas de la versión 1 de la API de datos, que se debe usar en lugar de las ranuras de métricas ga:metricXX de la API de Reporting v4.
- Algunas dimensiones y métricas que se encuentran en Universal Analytics tienen un equivalente directo en Google Analytics 4. Consulta el gráfico de equivalencia del esquema de la API de UA/GA4 para obtener más información.
- Los nombres de dimensiones y métricas ya no tienen el prefijo
ga:en Google Analytics 4. - Algunas funciones de Universal Analytics aún no están disponibles en GA4 (p.ej., Campaign Manager, DV360 y la integración con Search Ads 360). Una vez que se implemente esta funcionalidad en Google Analytics 4, la API de datos la admitirá, se agregarán dimensiones y métricas nuevas al esquema de la API.
Entidades
Google Analytics 4 no tiene el concepto de vistas (perfiles) que se introdujo en Universal Analytics. Como resultado, no hay ningún parámetro viewId en las solicitudes de informes de la versión 1 de la API de datos. En su lugar, se debe especificar un ID numérico de propiedad Google Analytics 4
en una ruta de URL de solicitud cuando se llama a los métodos v1 de la API de datos.
Este comportamiento es diferente de la API de Reporting v4, que se basa en los IDs de vista (perfil) para identificar la entidad de informe.
API de datos v1
En el caso de la API de datos v1, se debe especificar un ID numérico de la propiedad Google Analytics 4 en la ruta de URL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
API de Reporting v4
La API de Reporting v4 requiere que se especifique un ID de vista (perfil) de Universal Analytics en el cuerpo de una consulta de informe.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Si usas una de las bibliotecas cliente de la API de datos, no es necesario manipular la ruta de URL de la solicitud de forma manual. La mayoría de los clientes de la API proporcionan un parámetro property que espera una cadena en forma de properties/GA4_PROPERTY_ID. Consulta la Guía de inicio rápido para ver ejemplos del uso de las bibliotecas cliente.
Intervalos de fechas
Tanto la API de Reporting v4 como la API de datos v1 admiten varios períodos
especificados mediante el campo dateRanges en una solicitud de informe. Ambas APIs comparten el mismo formato de entrada de fecha y aceptan valores de fecha absolutos en forma de YYYY-MM-DD o fechas relativas como yesderday, today, 7daysAgo, etcétera.
Las solicitudes a la versión 1 de la API de datos se limitan a 4 períodos, mientras que la versión 4 de la API de informes permite 2 períodos en una sola solicitud de informe.
Cada dateRange de la versión 1 de la API de datos puede tener un campo opcional name que se puede usar para hacer referencia al período correspondiente en una respuesta.
Si no se proporciona name, el nombre del período se genera automáticamente.
Cuando se especifican varios períodos en una solicitud de la versión 1 de la API de datos, se agrega automáticamente una dimensión nueva dateRange a una respuesta, y el nombre del período se usa como valor de dimensión. Ten en cuenta que este comportamiento es diferente de la
API de Reporting v4, que muestra datos de un período como un grupo de valores de métricas dentro de cada fila.
Solicitud de la versión 1 de la API de datos
Se usa un campo name opcional para cada valor de dateRange en una solicitud.
Este nombre de período se utilizará como valor de la dimensión dateRange en la respuesta.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Respuesta de la versión 1 de la API de datos
Se incluye automáticamente una dimensión dateRange adicional en la respuesta.
El valor de la dimensión dateRange contiene el nombre de un período, que proviene del campo dateRange.name o que proviene de forma automática.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Solicitud de la versión 4 de la API de Reporting
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Respuesta de la API de Reporting v4
En la versión 4 de la API de Reporting, los valores de cada período se agrupan dentro del campo metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Ordena
El comportamiento del ordenamiento de las consultas de informes de la API de datos versión 1 se puede controlar mediante el campo
orderBys, similar al campo
orderBys de la API de Reporting versión 4.
La especificación OrderBy cambió en la versión 1 de la API de datos.
Cada OrderBy puede contener uno de los siguientes elementos:
- DimensionOrderBy, que ordena los resultados según los valores de una dimensión,
- MetricOrderBy, ordena los resultados según los valores de una métrica.
- PivotOrderBy, que se usa en las consultas dinámicas y ordena los resultados según los valores de una métrica dentro de un grupo de columnas dinámicas.
Los tipos de pedido DELTA, SMART y HISTOGRAM_BUCKET compatibles con la API de Reporting v4 no se implementan en la API de datos v1.
El tipo de orden OrderType.NUMERIC de la versión 1 de la API de datos es equivalente al valor OrderType.DIMENSION_AS_INTEGER de la versión 4 de la API de Reporting.
Solicitud de la versión 1 de la API de datos
En este ejemplo, se muestra una consulta de muestra que informa el recuento de sesiones por país y ordena las filas según la métrica sessions en orden descendente.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Respuesta de la versión 1 de la API de datos
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Solicitud de la versión 4 de la API de Reporting
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Respuesta de la API de Reporting v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Filtros
Las cláusulas dimensionFilter y metricFilter de la API de datos v1 se pueden usar para solicitar a la API que solo muestre datos de valores de dimensiones o métricas específicos. Esto es similar a dimensionFilterClauses y metricFilterClauses de la API de Reporting v4.
La API de datos v1 no admite strings de expresión de filtro como la cláusula filtersExpression de la API de Reporting v4. Estas expresiones se deben volver a escribir con las cláusulas dimensionFilter y metricFilter.
Solicitud de la versión 1 de la API de datos
Esta solicitud de ejemplo muestra una lista de los recuentos de sesiones de ciertas rutas de la página que visitaron los usuarios.
La cláusula dimensionFilter se usa para mostrar solo las filas con los valores de dimensión pagePath que comienzan con /webstore/ y contienen la string action=a12345.
La cláusula metricFilter le solicita al método runReport que muestre solo las filas con los valores de métrica sessions superiores a 1,000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Solicitud de la versión 4 de la API de Reporting
Esta solicitud de ejemplo es similar al ejemplo de la versión 1 de la API de datos. Muestra una lista de los recuentos de sesiones de ciertas rutas de la página que visitaron los usuarios.
El campo dimensionFilterClauses se usa para mostrar solo las filas con los valores de dimensión pagePath que comienzan con /webstore/ y contienen la cadena action=a12345.
El campo metricFilterClauses se usa para mostrar solo las filas con los valores de la métrica ga:sessions mayores a 1,000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Paginación
La API de datos v1 usa los campos limit y offset para paginar los resultados de respuesta que abarcan varias páginas, mientras que la API de Reporting v4 usa pageToken y pageSize.
Para las solicitudes de tabla dinámica de la API de datos v1, los campos limit y offset del objeto Pivot deben usarse para implementar la paginación de cada tabla dinámica de forma individual. El campo limit ahora es obligatorio para cada objeto Pivot.
De forma predeterminada, la API de datos v1 muestra, como máximo, las primeras 10,000 filas de datos de eventos, mientras que el valor predeterminado para la API de Reporting v4 es de 1,000 filas.
El número total de filas que coinciden con la consulta se devuelve mediante el campo rowCount en una respuesta de la API de datos v1, que es similar a la de la API de Reporting v4.
Solicitud de la versión 1 de la API de datos
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Respuesta de la versión 1 de la API de datos
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Solicitud de la versión 4 de la API de Reporting
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Respuesta de la API de Reporting v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Agregaciones de métricas
La API de datos v1 calcula los valores de agregación solo cuando se especifica el campo metricAggregations en una solicitud. Por el contrario, la API de Reporting v4 muestra los valores totales, mínimos y máximos de cada métrica de forma predeterminada, a menos que los campos hideTotals y hideValueRanges se configuren en true.
Solicitud de la versión 1 de la API de datos
Las agregaciones solo se calcularán si se especifica el campo metricAggregations en una solicitud.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Respuesta de la versión 1 de la API de datos
Las filas de métricas agregadas se muestran en los campos totals, minimum y maximum de una respuesta. Para las filas de métricas agregadas, el campo dimensionValues contiene un valor especial de RESERVED_TOTAL, RESERVED_MAX o RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Solicitud de la versión 4 de la API de Reporting
Una solicitud de ejemplo para mostrar el recuento de sesiones por país.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Respuesta de la API de Reporting v4
Los campos totals, minimums y maximums están presentes de forma predeterminada en una respuesta de la API de Reporting v4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Tabla dinámica
La API de datos v1 admite la funcionalidad pivot en los métodos de informes runPivotReport y batchRunPivotReports.
La API de Reporting v4 permite incluir pivots en las consultas de informes con el método batchGet.
Los elementos dinámicos se implementan de manera diferente en la API de datos v1 en comparación con la API de Reporting v4 de modo que cada fila de respuesta represente una sola celda de la tabla, mientras que en la API de Reporting v4 una sola fila de respuesta representa una línea de tabla completa.
API de datos v1
A continuación, se muestra un fragmento de la respuesta de la versión v1 de la API de datos a la consulta runPivotReport. Cada celda del informe de tabla dinámica se muestra de forma individual:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
API de Reporting v4
A continuación, se muestra un fragmento de la respuesta de la versión 4 de la API de Reporting a la consulta batchGet. Una sola fila de respuesta representa una línea de tabla completa que contiene todos los valores de métricas para la tabla dinámica en pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
En la versión 1 de la API de datos, cada dimensión de la consulta runPivotReport o batchRunPivotReports debe definirse dentro de un objeto dinámico. Una dimensión no se verá en un informe si no se utiliza en ninguna tabla dinámica de una consulta dinámica.
Las columnas dinámicas de la API de datos v1 se especifican con el campo fieldNames en lugar del campo dimensions de la API de informes v4.
Se debe usar un filtro de dimensión con alcance de solicitud si se desea el filtrado de dimensiones en una solicitud de informe de la versión 1 de la API de datos. Es diferente de la API de Reporting v4, que acepta la especificación dimensionFilterClauses en un objeto dinámico.
El campo offset de la API de datos v1 es funcionalmente similar al campo startGroup de la API de Reporting v4.
El campo limit de la API de datos v1 es similar a maxGroupCount de la API de Reporting v4 y debe usarse para limitar la cardinalidad del informe.
La API de Data v1 admite varias tablas dinámicas, siempre y cuando el producto del parámetro limit para cada tabla dinámica no supere los 100,000. La API de Reporting v4 solo admite una dimensión dinámica.
De forma predeterminada, la API de datos v1 ordena las dimensiones de una tabla dinámica según la primera métrica del informe. Este comportamiento es diferente de la API de Reporting v4, en la que el orden de las tablas dinámicas se determina por orden descendente de "total" de las métricas solicitadas. Para especificar el orden en la API de datos v1, usa el campo orderBys de una especificación Pivot.
Solicitud de la versión 1 de la API de datos
Esta consulta dinámica v1 de la API de datos compila un informe de los recuentos de sesiones por país, que se dinamiza según la dimensión browser. Ten en cuenta cómo la consulta usa los campos orderBys, limit y offset para reproducir el comportamiento de una consulta similar de la API de Reporting v4 a fin de preservar la configuración de orden y paginación.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
},
{
"name": "browser"
}
]
}
Respuesta de la versión 1 de la API de datos
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Solicitud de la versión 4 de la API de Reporting
Esta consulta dinámica de la versión 4 de la API de Reporting crea un informe de los recuentos de sesiones por país, que se dinamiza según la dimensión ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Respuesta de la API de Reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Cohortes
La API de datos v1 usa la especificación CohortSpec para configurar informes de cohorte. Esto es similar a la especificación CohortGroup de la versión 4 de la API de Reporting.
En la actualidad, todas las métricas disponibles en la versión 1 de la API de datos son compatibles con las consultas de cohorte, mientras que la API de informes v4 solo permite que se use un subconjunto de métricas especiales en una consulta de cohorte.
En una solicitud de cohorte de la API de datos v1, la métrica cohortActiveUsers es obligatoria.
Tanto la API de datos v1 como la API de Reporting v4 permiten hasta 12 cohortes en una sola solicitud.
Actualmente, las métricas de valor del ciclo de vida del cliente (LTV) no son compatibles con la versión 1 de la API de datos.
Equivalencia de las métricas de cohorte
La mayoría de las métricas de cohorte definidas en la API de Reporting v4 se pueden reemplazar por una expresión para lograr un resultado equivalente en la API de datos v1, según el gráfico que aparece a continuación.
| Nombre de la métrica de la versión 4 de la API de Reporting | Nombre o expresión de la métrica de la versión 1 de la API de datos |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers", además de un filtro de dimensión por eventName que corresponda al evento de finalización de objetivo deseado. |
Solicitud de la versión 1 de la API de datos
Una consulta de muestra que configura una cohorte de usuarios cuya primera sesión ocurrió en una semana del 3/1/2021. La cantidad de usuarios activos y la tasa de retención de usuarios se calculan para la cohorte durante 5 semanas, con el nivel de detalle SEMANAL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Respuesta de la versión 1 de la API de datos
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Solicitud de la versión 4 de la API de Reporting
Una consulta de muestra que configura una cohorte de usuarios cuya primera sesión ocurrió en una semana del 3/1/2021. La cantidad de usuarios activos y la tasa de retención de usuarios se calculan para la cohorte durante 5 semanas, con el nivel de detalle de WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Respuesta de la API de Reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Muestreo
La API de datos v1 usa el muestreo de datos automáticamente cuando anticipa que los límites de cardinalidad reducirán la calidad de los datos. Si se muestrean los resultados de un período, el metadata de RunReportResponse contendrá un SamplingMetadata correspondiente, similar al campo samplingLevel presente en la versión 4 de la API de Reporting.
Actualidad de los datos
La API de datos no proporciona un equivalente del campo isDataGolden de la versión 4 de la API de Reporting, que se usaba para indicar si todos los hits de un informe terminaron de procesarse. De todas formas, un mismo informe puede mostrar resultados diferentes cuando se consulta en una fecha posterior debido a un procesamiento adicional.
Segmentos (no admitidos)
Actualmente, los segmentos no son compatibles con la versión 1 de la API de datos.
Informes en tiempo real
Usa el método properties.runRealtimeReport de la versión 1 de la API de datos para generar informes en tiempo real para las propiedades Google Analytics 4. La función de informes en tiempo real para las propiedades Universal Analytics se proporcionó a través del método data.realtime.get de la API de Google Analytics v3.
El esquema de informes en tiempo real de la API de datos es diferente del esquema de informes en tiempo real de la versión 3 de la API de Analytics debido a las diferencias conceptuales entre Universal Analytics y Google Analytics 4.
Solicitud de la versión 1 de la API de datos
En el siguiente ejemplo, para preservar el comportamiento de ordenamiento predeterminado de la
versión 3 de la API de Google Analytics, se agregó un elemento orderBy opcional a la consulta
de la API de datos de muestra v1.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Respuesta de la versión 1 de la API de datos
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Solicitud de la versión 3 de la API de Google Analytics
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Respuesta de la API de Google Analytics v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(No admitido) Informes de actividad del usuario
En la actualidad, la API de datos v1 no admite la funcionalidad para informar actividades de usuarios individuales similares al método userActivity.search de la API de Reporting v4.
Cambios en la cuota de la API
Categorías de cuotas principales y en tiempo real
A los efectos de la cuota, la API de datos tiene dos categorías de solicitud: Núcleo y En tiempo real. Las solicitudes a la API para los métodos de informes principales (runReport, getMetadata, runPivotReport, batchRunReports y batchRunPivotReports) cobran cuotas de Core.
Las solicitudes a la API al método runRealtimeReport cobran cuotas en tiempo real.
Cuotas de tokens
Además de las cuotas de proyectos, cada solicitud consume cuotas de token de propiedad que se cobran según la complejidad de la consulta. Consulta la documentación de cuotas de la versión 1 de la API de datos para obtener una descripción detallada de las cuotas y los límites de la API.
Es posible obtener el estado actual de todas las cuotas de una propiedad de Analytics si configuras returnPropertyQuota como true en una solicitud de informes principal o en tiempo real. El estado de la cuota se mostrará en PropertyQuota.
(No compatible) Cuota basada en recursos
Dado que todos los informes principales de Google Analytics 4 se basan en datos sin muestrear, la cuota basada en recursos que se introdujo en la API de Reporting v4 ya no es aplicable y no hay equivalente al campo useResourceQuotas presente en una solicitud de informe de la API de datos v1.
Cuota diaria de solicitudes por vista (perfil) (no admitido)
Debido a que no hay vistas en Google Analytics 4, la cuota de requests per view (profile) per day
no está presente en la versión 1 de la API de datos y se reemplaza por cuotas de tokens.