La versión 1 de la API de datos de Google Analytics te permite generar tablas dinámicas. Dinámico las tablas son una herramienta de resumen de datos que visualiza los datos reorganizando los información de la tabla dinamizando (rotando) los datos en uno o varios dimensiones.
A modo de 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 pivotes adicionales.
Funciones compartidas con los informes principales
Las solicitudes de informes dinámicos tienen la misma semántica que las solicitudes de informes principales para muchas funciones compartidas. Por ejemplo: paginación, Filtros de dimensión y Usuarios Las propiedades se comportan de la misma manera en los Informes dinámicos que en los informes principales. Esta se centra en las funciones de informes dinámicos. Para familiarizarse con el Core Funcionalidad de informes de la API de datos v1; lee la guía básica 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 tabla dinámica en los siguientes métodos de informes:
runPivotReport Este método devuelve un informe de tabla dinámica personalizado con los datos de eventos de Google Analytics. Cada pivot describe las columnas y filas de las dimensiones visibles en la respuesta del informe.
batchRunPivotReports Esto es una versión por lotes del método
runPivotReportque permite generar varios informes con una sola llamada a la API.
Cómo seleccionar una entidad denunciante
Todos los métodos de Data API v1 requieren el identificador de propiedad de Google Analytics
que se especificará dentro de una ruta de solicitud de URL con el formato
properties/GA_PROPERTY_ID, por ejemplo:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
El informe resultante se generará en función de los datos de eventos de Google Analytics. recopilados en la propiedad de Google Analytics especificada.
Si usas una de las bibliotecas cliente de la API de datos,
no es necesario manipular manualmente la ruta de la URL de solicitud. La mayoría de los clientes de API
proporciona un parámetro property que espera una cadena en la forma de
properties/GA_PROPERTY_ID Consulta la Guía de inicio rápido
para ver ejemplos de uso de las bibliotecas cliente.
Solicitud de informe dinámico
Para construir una solicitud con una tabla dinámica, usa runPivotReport o el batchRunPivotReports .
Para solicitar datos dinámicos, puedes construir una 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ámica válidas en el campo pivots.
Esta es una solicitud de ejemplo con los campos recomendados:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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
}
]
}
Tablas dinámicas
Usa objetos Pivot en el campo pivot de la solicitud
body para definir los pivotes del informe. Cada Pivot describe la dimensión visible
y filas en la respuesta del informe.
La API de datos v1 admite varias pivotes siempre y cuando el producto del límite de cada elemento dinámico no supere los 100,000.
A continuación, se muestra un fragmento que muestra el uso de pivots para crear un informe de
recuentos de sesiones por país, según la dimensión browser. Observa cómo la
usa el campo orderBys
ordenamiento, y el límite, y
offset para 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
Las dimensiones describen y agrupan los datos de eventos de tu
sitio web o aplicación. La dimensión city, por ejemplo, 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
dimensiones
de la solicitud. Para que se puedan ver en un informe, esas dimensiones también deben
deben mostrarse en los campos fieldNames
de un objeto Pivot.
Una dimensión no será visible en un informe si no se usa en ninguna
tabla dinámica de una consulta dinámica. No todas las dimensiones deben estar presentes en la tabla dinámica
fieldNames Las dimensiones se pueden utilizar exclusivamente en los filtros y no en el
fieldNames de cualquier elemento dinámico.
A continuación, se incluye un fragmento que muestra el uso de los campos dimension y fieldNames
para una tabla con browser, country y language pivotes:
"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 para tu sitio web o aplicación. En una solicitud de informe, puedes especificar una o más métricas. Consulta las Métricas de la API para ver una lista completa de los nombres de las métricas de la API. disponibles para especificarse en las solicitudes.
En las solicitudes de informes dinámicos, las métricas se definen usando el campo metrics de la
del cuerpo de la solicitud, que es similar a los métodos de los informes principales.
En el siguiente ejemplo, se especifica el recuento de sesiones para usar como valor de métrica en un informe:
"metrics": [
{
"name": "sessions"
}
],
Agregaciones de métricas
Usa la clase metricAggregations. campo de un objeto Pivot para calcular la métrica agregada de salida para cada pivot.
Las agregaciones solo se calcularán si metricAggregations campo especificado en una solicitud.
A continuación, se muestra un fragmento de una consulta que solicita los totales para el
Dimensión de tabla dinámica browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Las métricas calculadas se muestran en el conjunto de datos agregados
campo de 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 informes principales, las solicitudes dinámicas te permiten
para especificar el límite
y offset en los
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 para limitar la
cardinalidad del informe.
La API de datos v1 admite múltiples pivotes siempre y cuando el producto de limit
de cada elemento dinámico no supere los 100,000.
A continuación, se muestra un fragmento que muestra el uso de los campos offset y limit para
Recupera las siguientes cinco dimensiones de language con un desplazamiento de 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtros
Al igual que la funcionalidad de informes principales, una filtro de dimensión centrado en la solicitud se debe usar si se desea filtrar las dimensiones en un informe dinámico para cada solicitud.
Ordenar
El comportamiento de ordenamiento de las consultas de los informes de tabla dinámica se puede controlar para cada uno individualmente mediante orderBys de un objeto Pivot, que contiene una lista de OrderBy.
Cada OrderBy puede contener uno de los siguientes elementos:
- DimensionOrderBy, ordena los resultados según los valores de una dimensión.
- MetricOrderBy, ordena los resultados según los valores de una métrica.
- PivotOrderBy, utilizado en dinamizar consultas y ordenar los resultados según los valores de la métrica dentro de un grupo de columnas dinámicas.
Este ejemplo muestra un fragmento de una definición de tabla dinámica que reorienta el informe en
la dimensión browser, ordenando los resultados por la métrica sessions en
orden descendente.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Denunciar respuesta
La Respuesta del informe de Pivot de una tabla dinámica la solicitud a la API de informes es principalmente un encabezado y filas.
Encabezados de respuesta
El encabezado del informe dinámico consta de PivotHeaders, DimensionHeaders y MetricHeaders, que enumeran las columnas de la 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 el rol de cada componente del informe dinámico Respuesta durante la renderización del informe de datos dinámicos:
Filas de respuesta
La respuesta del informe de elementos dinámicos de runPivotReport y batchRunPivotReports difiere de una respuesta para los métodos de informes principales como runReport y batchRunReports ya que cada fila de respuesta del informe dinámico representa una sola celda del , mientras que, en un informe normal, una sola fila de respuesta representa un línea de la tabla.
A continuación se muestra un fragmento de la respuesta de un informe de datos dinámicos para una
con las dimensiones dinámicas browser, country y language, y el
sessions. Cada celda del informe dinámico 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 que aparecen destacadas en la siguiente tabla:
Bibliotecas cliente
Consulta la Guía de inicio rápido para obtener una explicación de a instalar y configurar bibliotecas cliente.
En los siguientes ejemplos se usa la biblioteca cliente para ejecutar una consulta dinámica y así compilar una informe de recuentos de sesiones por país, controlado por la dimensión del navegador
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue() ); } }
Python
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = Y'OUR-GA4-PROPERTY-ID;' // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require(@'google-analytics/data)'; // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, dateRanges: [ { startDate: 2'021-01-01,' endDate: 2'021-01-30,' }, ], pivots: [ { fieldNames: [c'ountry]', limit: 250, orderBys: [ { dimension: { dimensionName: c'ountry,' }, }, ], }, { fieldNames: [b'rowser]', offset: 3, limit: 3, orderBys: [ { metric: { metricName: s'essions,' }, desc: true, }, ], }, ], metrics: [ { name: s'essions,' }, ], dimensions: [ { name: c'ountry,' }, { name: b'rowser,' }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log(R'eport result:)'; response.rows.forEach(row = >{ row.dimensionValues.forEach(dimensionValue = >{ console.log(dimensionValue.value); }); row.metricValues.forEach(metricValue = >{ console.log(metricValue.value); }); }); }r
Aplicación de demostración
Consulta la Demostración del informe dinámico v1 de la API de Google Analytics aplicación para ver un ejemplo de cómo compilar y mostrar un informe dinámico con JavaScript.