Aspectos básicos de las tareas relacionadas con informes

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.

Todos los usuarios con acceso de lectura a tu propiedad de Google Analytics pueden usar el recurso de tarea de informes generado a partir de esta solicitud para acceder a informes personalizados.

Un informe personalizado estará disponible durante 72 horas después de que esté listo. Después de este período, el recurso de tarea de informes correspondiente y su contenido se borrarán automáticamente.

Cómo crear una tarea de informes

La API de Google Analytics Data v1 usa un enfoque asíncrono para crear tareas de informes. Primero, es necesario enviar una solicitud al reportTasks.create método para crear una tarea de informes. Luego, se usa el reportTasks.query método para recuperar el informe personalizado generado.

Además, puedes usar reportTasks.get para recuperar metadatos de configuración sobre una tarea de informes específica y reportTasks.list para enumerar todas las tareas de informes de una propiedad.

Selecciona una entidad de informes

Todos los métodos de la API de Data v1 requieren que se especifique el identificador de la propiedad de Google Analytics dentro de una ruta de acceso de solicitud de URL con el formato properties/GA_PROPERTY_ID, como el siguiente:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

El informe se genera 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 Data, no es necesario manipular la ruta de acceso de la 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 con el formato properties/GA_PROPERTY_ID. Consulta la guía de inicio rápido para ver ejemplos de cómo usar las bibliotecas cliente.

Solicita la creación de la tarea de informes

Para crear una tarea de informes, llama al reportTasks.create método con el ReportTask objeto en una solicitud. Se requieren los siguientes parámetros:

  • reportDefinition campo 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 informes:

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 informes en el campo name (como properties/1234567/reportTasks/123), que se puede usar en consultas posteriores para obtener el estado de una tarea de informes 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"
    }
  }
}

Obtén el estado de preparación de la tarea de informes

La generación de un informe puede tardar varios minutos después de la reportTasks.create llamada. Para obtener el estado de preparación de una tarea de informes, llama al reportTasks.get método.

Usa el nombre de la tarea de informes (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 informes se muestra en el state de una respuesta. Una vez que se completa la generación del informe, el estado de una tarea de informes cambia de CREATING a ACTIVE.

El reportMetadata campo contiene la información de alto nivel sobre el informe generado, como el recuento de filas y la cantidad de tokens de cuota cobrados.

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 reportTasks.list método.

Recupera el informe generado

Una vez que se genera la tarea de informes creada con el reportTasks.create método, llama al reportTasks.query método y especifica el nombre de la tarea de informes (como properties/1234567/reportTasks/123).

Solicitud HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

Si la tarea de informes 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"
  }
}