Con las tareas de informes, puedes iniciar una solicitud asíncrona de larga duración para crear un informe personalizado de tus datos de eventos de Google Analytics.
El recurso de la tarea de informe que se genera a partir de esta solicitud se puede usar para acceder a los informes personalizados de todos los usuarios con acceso de lectura a tu propiedad de Google Analytics.
Un informe personalizado estará disponible durante 72 horas después de que esté listo. Después de este período, se borrarán automáticamente el recurso de tarea de informe correspondiente y su contenido.
Crea una tarea de informe
La API de datos de Google Analytics v1 usa un enfoque asíncrono para
crear tareas de informes. Primero, se necesita una solicitud al método reportTasks.create
para crear una tarea de informe. Luego, se usa el método reportTasks.query
para recuperar el informe personalizado generado.
Además, puedes usar reportTasks.get
para recuperar metadatos de configuración sobre una tarea de informe específica y reportTasks.list
para enumerar todas las tareas de informe de una propiedad.
Selecciona una entidad de informe
Todos los métodos de la API de datos v1 requieren que el
identificador de la propiedad Google Analytics 4
se especifique dentro de una ruta de solicitud de URL en el formato
properties/GA4_PROPERTY_ID
, como los siguientes:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks
El informe se genera 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.
Solicita la creación de la tarea de informes
Para crear una tarea de informe, llama al método reportTasks.create
con el objeto ReportTask
en una solicitud. Se requieren los siguientes parámetros:
- Campo
reportDefinition
que describe la definición de un informe personalizado. La estructura de este parámetro es similar a la definición de informe que usan los métodos de Core Reporting.
Ejemplo de solicitud de creación de tarea de informe:
Solicitud HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
Una respuesta del método reportTasks.create
contiene el nombre de la tarea de informe en el campo name
(como properties/1234567/reportTasks/123
), que se puede usar en consultas posteriores para obtener el estado de una tarea de informe y recuperar el informe resultante.
Respuesta HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
Cómo obtener el estado de preparación de la tarea de informe
Generar un informe después de la llamada a reportTasks.create
puede tardar varios minutos. Puedes obtener el estado de preparación para una tarea de informe mediante una llamada al método reportTasks.get
.
Usa el nombre de la tarea de informe (como properties/1234567/reportTasks/123
) que recibiste de una respuesta reportTasks.create
para especificar la tarea de informes.
Ejemplo:
Solicitud HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
El estado de preparación de una tarea de informe se muestra en el campo state
de una respuesta. Una vez que se completa la generación de informes, el estado de una tarea de informe cambia de CREATING
a ACTIVE
.
El campo reportMetadata
contiene información de alto nivel sobre el informe generado, como el recuento de filas y la cantidad de tokens de cuota que se cobran.
Respuesta HTTP
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
Para obtener el estado de todas las tareas de informes, llama al método reportTasks.list
.
Cómo recuperar el informe generado
Una vez que se genere la tarea de informe creada con el método reportTasks.create
, llama al método reportTasks.query
y especifica el nombre de la tarea del informe (como properties/1234567/reportTasks/123
).
Solicitud HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
Si la tarea de informe está lista, se muestra una respuesta que contiene el informe generado:
Respuesta HTTP
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}