Principes de base des tâches liées aux rapports

Les tâches de rapport vous permettent de lancer une requête asynchrone de longue durée pour créer un rapport personnalisé sur vos données d'événement Google Analytics.

La ressource "Report Task" (Tâche de rapport) générée à partir de cette requête peut être utilisée pour accéder à des rapports personnalisés par tous les utilisateurs disposant d'un accès en lecture à votre propriété Google Analytics.

Un rapport personnalisé est disponible pendant 72 heures après sa création. Après cette période, la ressource de tâche de rapport correspondante et son contenu seront automatiquement supprimés.

Créer une tâche de rapport

L'API Data de Google Analytics v1 utilise une approche asynchrone pour créer des tâches de rapport. Tout d'abord, vous devez envoyer une requête à la méthode reportTasks.create pour créer une tâche de rapport. Ensuite, la méthode reportTasks.query permet de récupérer le rapport personnalisé généré.

De plus, vous pouvez utiliser reportTasks.get pour récupérer les métadonnées de configuration concernant une tâche de rapport spécifique et reportTasks.list pour répertorier toutes les tâches de rapport d'une propriété.

Sélectionner une entité de reporting

Toutes les méthodes de l'API Data v1 nécessitent que l'identifiant de propriété Google Analytics 4 soit spécifié dans un chemin de requête d'URL au format properties/GA4_PROPERTY_ID, par exemple:

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

Il est généré en fonction des données d'événement Google Analytics collectées dans la propriété Google Analytics 4 spécifiée.

Si vous utilisez l'une des bibliothèques clientes des API Data, il n'est pas nécessaire de manipuler manuellement le chemin de l'URL de la requête. La plupart des clients API fournissent un paramètre property qui attend une chaîne au format properties/GA4_PROPERTY_ID. Consultez le guide de démarrage rapide pour obtenir des exemples d'utilisation des bibliothèques clientes.

Demander la création de la tâche de rapport

Pour créer une tâche de rapport, appelez la méthode reportTasks.create à l'aide de l'objet ReportTask dans une requête. Les paramètres suivants sont requis :

Exemple de demande de création d'une tâche de rapport:

Requête 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" }]
  }
}

Une réponse de la méthode reportTasks.create contient le nom de la tâche de rapport dans le champ name (par exemple, properties/1234567/reportTasks/123). Ce nom peut être utilisé dans les requêtes ultérieures pour obtenir l'état d'une tâche de rapport et récupérer le rapport résultant.

Réponse 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"
    }
  }
}

Obtenir l'état de préparation des tâches du rapport

La génération d'un rapport peut prendre plusieurs minutes après l'appel reportTasks.create. Vous pouvez obtenir l'état de préparation d'une tâche de rapport en appelant la méthode reportTasks.get.

Utilisez le nom de la tâche de rapport (par exemple, properties/1234567/reportTasks/123) que vous avez reçu d'une réponse reportTasks.create pour spécifier la tâche de rapport.

Exemple :

Requête HTTP

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

L'état de préparation d'une tâche de rapport est renvoyé dans le champ state d'une réponse. Une fois la génération du rapport terminée, l'état d'une tâche de rapport passe de CREATING à ACTIVE.

Le champ reportMetadata contient des informations générales sur le rapport généré, telles que le nombre de lignes et le nombre de jetons facturés.

Réponse 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
  }
}

Vous pouvez obtenir l'état de toutes les tâches de rapport en appelant la méthode reportTasks.list.

Récupérer le rapport généré

Une fois la tâche de rapport créée à l'aide de la méthode reportTasks.create, appelez la méthode reportTasks.query et spécifiez le nom de la tâche de rapport (par exemple, properties/1234567/reportTasks/123).

Requête HTTP

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

Si la tâche de rapport est prête, une réponse contenant le rapport généré est renvoyée:

Réponse HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}