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é de 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 à 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. Passé ce délai, la ressource de tâche de rapport correspondante et son contenu sont 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 à la reportTasks.create méthode est nécessaire pour créer une tâche de rapport. Ensuite, la reportTasks.query méthode est utilisée pour 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 d'une tâche de rapport spécifique et reportTasks.list pour lister 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 la propriété Google Analytics soit spécifié dans un chemin de requête 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é en fonction des données d'événements 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 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/GA_PROPERTY_ID. Pour obtenir des exemples d'utilisation des bibliothèques clientes, consultez le guide de démarrage rapide.

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

Pour créer une tâche de rapport, appelez la reportTasks.create méthode à l'aide de l' ReportTask objet 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 suivantes 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 après l'appel reportTasks.create peut prendre plusieurs minutes. Vous pouvez obtenir l'état de préparation d'une tâche de rapport en appelant la reportTasks.get méthode.

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 state champ 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 reportMetadata champ contient les informations de haut niveau 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 reportTasks.list méthode.

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

Une fois la tâche de rapport créée à l'aide de la reportTasks.create méthode est générée, appelez la reportTasks.query méthode 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"
  }
}