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

Les tâches de rapport vous permettent de démarrer 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 par tous les utilisateurs disposant d'un accès en lecture à votre propriété Google Analytics pour accéder aux rapports personnalisés.

Un rapport personnalisé est disponible pendant 72 heures après sa création. Passé ce délai, la ressource de tâche de création de rapports correspondante et son contenu seront automatiquement supprimés.

Créer une tâche de création de rapport

La version 1 de l'API Google Analytics Data utilise une approche asynchrone pour créer des tâches de création de rapports. Tout d'abord, une requête à la méthode reportTasks.create est nécessaire pour créer une tâche de création de rapports. La méthode reportTasks.query est ensuite 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 création de rapports spécifique et reportTasks.list pour lister toutes les tâches de création de rapports d'une propriété.

Sélectionnez une entité de reporting.

Toutes les méthodes de la version 1 de l'API Data nécessitent que l'identifiant de la propriété Google Analytics soit spécifié dans un chemin de requête d'URL sous la forme 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é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 d'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 création de rapports

Pour créer une tâche de création de rapports, appelez la méthode reportTasks.create à l'aide de 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 création de rapports 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 création de rapports et récupérer le rapport généré.

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 création de rapports

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 création de rapports en appelant la méthode reportTasks.get.

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

Exemple :

Requête HTTP

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

L'état de préparation d'une tâche de création de rapports est renvoyé dans le champ state d'une réponse. Une fois la génération de rapports terminée, l'état d'une tâche de création de rapports 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 création de rapports en appelant la méthode reportTasks.list.

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

Une fois la tâche de création de rapports 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 création de rapports (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 création de rapports 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"
  }
}