La API de datos de Google Analytics v1 te permite generar tablas dinámicas. Las tablas dinámicas son una herramienta de resumen de datos que permite visualizar datos reorganizando la información de la tabla a través de la reorientación (rotación) de los datos en una o varias dimensiones.
Como ejemplo, considera la siguiente tabla de datos sin procesar:
Con estos datos, es posible construir una tabla dinámica, desglosando los datos de las sesiones por navegador, con las dimensiones de idioma y país seleccionadas como elementos dinámicos adicionales.
Funciones compartidas con informes principales
Las solicitudes de informes dinámicos tienen la misma semántica con las solicitudes de informes principales para muchas funciones compartidas. Por ejemplo, la paginación, los filtros de dimensión y las propiedades del usuario se comportan de la misma manera en los informes dinámicos que en los informes principales. Esta guía se centra en las funciones de informes dinámicos. Para familiarizarte con la funcionalidad de informes principales de la versión 1 de la API de datos, lee la guía de conceptos básicos de informes y la guía de casos de uso avanzados.
Métodos de informes dinámicos
La API de datos v1 admite la funcionalidad de pivote en los siguientes métodos de informes:
runPivotReport Este método muestra un informe de tabla dinámico personalizado de los datos de eventos de Google Analytics. Cada tabla dinámica describe las columnas y filas de dimensiones visibles en la respuesta del informe.
batchRunPivotReports es una versión por lotes del método
runPivotReportque permite generar varios informes con una sola llamada a la API.
Selección de una entidad denunciante
Todos los métodos de la API de datos v1 requieren que se especifique el identificador de la propiedad Google Analytics 4 dentro de una ruta de solicitud de URL con el formato properties/GA4_PROPERTY_ID, por ejemplo:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
El informe resultante se generará en función de los datos de eventos de Google Analytics recopilados en la propiedad Google Analytics 4 especificada.
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.
Solicitud de informe dinámico
Para crear una solicitud con una tabla dinámica, usa el método runPivotReport o el batchRunPivotReports.
Para solicitar datos dinámicos, puedes crear un objeto RunPivotReportRequest. Recomendamos comenzar con estos parámetros de solicitud:
- Una entrada válida en el campo dateRanges.
- Al menos una entrada válida en el campo dimensions.
- Al menos una entrada válida en el campo metrics.
- Al menos dos entradas de tabla dinámicas válidas en el campo pivots.
Esta es una solicitud de ejemplo con los campos recomendados:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Tabla dinámica
Usa objetos Pivot en el campo pivot del cuerpo de la solicitud para definir los elementos dinámicos del informe. Cada Pivot describe las columnas y filas de dimensión visibles en la respuesta del informe.
La API de datos 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.
A continuación, se muestra un fragmento que muestra el uso de pivots para crear un informe de los recuentos de sesiones por país, que se dinamiza según la dimensión browser. Observa cómo la consulta usa el campo orderBys para ordenar y, además, los campos limit y offset a fin de implementar la paginación.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Dimensiones
En Dimensiones, se describen y agrupan los datos de eventos de tu sitio web o app. Por ejemplo, la dimensión city indica la ciudad ("París" o "Nueva York") donde se originó cada evento. En una solicitud de informe, puedes especificar cero o más dimensiones.
Las dimensiones deben definirse dentro del campo dimensions del cuerpo de una solicitud. Para que se puedan ver en un informe, esas dimensiones también deben incluirse en el campo fieldNames de un objeto Pivot.
Una dimensión no será visible en un informe si no se utiliza en ninguna tabla dinámica de una consulta dinámica. No todas las dimensiones deben estar presentes en el fieldNames de una tabla dinámica. Las dimensiones se pueden usar exclusivamente en filtros y no en fieldNames de ninguna tabla dinámica.
A continuación, se muestra un fragmento que muestra el uso de los campos dimension y fieldNames para una tabla con las tablas dinámicas browser, country y language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Métricas
Las métricas son mediciones cuantitativas de los datos de eventos de tu sitio web o app. En una solicitud de informe, puedes especificar una o más métricas. Consulta las Métricas de API para obtener una lista completa de los nombres de las métricas de API disponibles que se pueden especificar en las solicitudes.
En las solicitudes de informes dinámicos, las métricas se definen con el campo metrics del cuerpo de la solicitud, que es similar a los métodos de Core Reporting.
En el siguiente ejemplo, se especifica el recuento de sesiones que se usará como un valor de métrica en un informe:
"metrics": [
{
"name": "sessions"
}
],
Agregaciones de métricas
Usa el campo metricAggregations de un objeto Pivot a fin de calcular los valores de métricas agregados para cada tabla dinámica.
Las agregaciones solo se calcularán si se especifica el campo metricAggregations en una solicitud.
A continuación, se muestra un fragmento de una consulta que solicita los totales de la
dimensión dinámica browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Las métricas calculadas se muestran en el campo de agregaciones del objeto RunPivotReportResponse. Para las filas de métricas agregadas, el campo dimensionValues contiene un valor especial de RESERVED_TOTAL, RESERVED_MAX o RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Paginación
Al igual que los métodos de Core Reporting, las solicitudes dinámicas te permiten especificar los campos limit y offset en el objeto Pivot para implementar la paginación.
La configuración de paginación se aplica a cada tabla dinámica de forma individual.
El campo limit es obligatorio para cada objeto Pivot a fin de 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.
A continuación, se muestra un fragmento que muestra el uso de los campos offset y limit para recuperar las siguientes cinco dimensiones language con un desplazamiento de 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtros
Al igual que con la funcionalidad principal de informes, se debe usar un filtro de dimensión centrado en la solicitud si se desea filtrar las dimensiones en una solicitud de informes dinámicos.
Ordena
El comportamiento del orden de las consultas de informes dinámicos se puede controlar para cada elemento dinámico de forma individual con el campo orderBys de un objeto Pivot, que contiene una lista de objetos OrderBy.
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 por los valores de una métrica dentro de un grupo de columnas dinámicas.
En este ejemplo, se muestra un fragmento de una definición dinámica que dinamiza el informe en la dimensión browser y ordena los resultados según la métrica sessions en orden descendente.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Denunciar respuesta
La respuesta del informe dinámico de una solicitud a la API de un informe dinámico es, principalmente, un encabezado y filas.
Encabezados de respuesta
El encabezado del informe de tabla dinámica consta de PivotHeaders, DimensionHeaders y MetricHeaders, que enumeran las columnas del informe de tabla dinámica.
Por ejemplo, un informe con dimensiones dinámicas browser, country y language, y la métrica sessions, generará encabezados como estos:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
En el siguiente gráfico, se ilustra la función de cada componente de la respuesta del informe dinámico para procesar el informe:
Filas de respuesta
La respuesta del informe de tabla dinámica de los métodos runPivotReport y batchRunPivotReports difiere de una respuesta para los métodos de Core Reporting, como runReport y batchRunReports, en que cada fila de respuesta del informe dinámico representa una sola celda de la tabla, mientras que en un informe normal, una sola fila de respuesta representa una línea de tabla completa.
A continuación, se muestra un fragmento de la respuesta de un informe de tabla dinámica para una consulta con las dimensiones de tabla dinámica browser, country y language, y la métrica sessions. Cada celda del informe de tabla dinámica se muestra de forma individual:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Estos datos corresponden a las dos celdas resaltadas en la tabla a continuación:
Bibliotecas cliente
Consulta la Guía de inicio rápido para obtener una explicación sobre cómo instalar y configurar las bibliotecas cliente.
A continuación, se muestra un ejemplo en el que se usa la biblioteca cliente de Python que ejecuta una consulta dinámica para compilar un informe de los recuentos de sesiones por país, que se dinamiza según la dimensión del navegador.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Aplicación de demostración
Consulta la aplicación de demostración del informe dinámico de la versión 1 de la API de Google Analytics para ver un ejemplo de cómo compilar y mostrar un informe de tabla dinámica con JavaScript.