Principes de base des tâches de création de 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énements Google Analytics.

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

Un rapport personnalisé sera disponible pendant 72 heures une fois qu'il sera prêt. Passé ce délai, la ressource de tâche de rapport correspondante et son contenu seront automatiquement supprimés.

Créer une tâche de rapport

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

Vous pouvez également utiliser reportTasks.get pour récupérer les métadonnées de configuration d'une tâche de rapport spécifique et reportTasks.list pour lister toutes les tâches de rapport d'une propriété.

Sélectionnez une entité de reporting

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

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

Le rapport est généré à partir des données d'événement Google Analytics collectées dans la propriété Google Analytics spécifiée.

Si vous utilisez l'une des bibliothèques clientes de l'API Data, vous n'avez pas besoin de manipuler manuellement le chemin d'URL de la requête. La plupart des clients API fournissent un paramètre property qui attend une chaîne au format properties/GA_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 en utilisant l'objet ReportTask dans une requête. Les paramètres suivants sont requis :

Exemple de requête de création de 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), qui 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 obtenu.

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 de la tâche de 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 de quota 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 générée, 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"
  }
}

Étapes suivantes