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.

El recurso Report Task generado a partir de esta solicitud se puede usar para acceder a informes personalizados por 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 la tarea de informe correspondiente y su contenido.

Crea una tarea de informe

La API de Google Analytics Data v1 utiliza un enfoque asíncrono para crear tareas de informes. Primero, es necesario realizar 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 informes

Todos los métodos de la API de Data v1 requieren que se especifique el identificador de propiedad de Google Analytics dentro de una ruta 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 especificada de Google Analytics.

Si usas una de las bibliotecas cliente de la API de Data, no es necesario que manipules 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 con el formato properties/GA_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 informe

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:

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"
    }
  }
}

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

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

Usa el nombre de la tarea de informe (como properties/1234567/reportTasks/123) que recibiste de una respuesta de reportTasks.create para especificar la tarea de informe.

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 del informe, el estado de una tarea de informe cambia de CREATING a ACTIVE.

El campo reportMetadata contiene información general 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
  }
}

Puedes obtener el estado de todas las tareas de informes llamando al método reportTasks.list.

Recupera 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 de informe (por ejemplo, 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 devuelve 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"
  }
}