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 ReportTask 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é sera disponible pendant 72 heures après sa création. 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 à la méthode reportTasks.create est nécessaire pour créer une tâche de rapport. 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 rapport spécifique et reportTasks.list pour lister toutes les tâches de rapport d'une propriété.

Sélectionnez une entité de référence

Toutes les méthodes de l'API Data v1 nécessitent que l'identifiant de propriété Google Analytics soit spécifié dans un chemin d'accès à la requête 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 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 d'une 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 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 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é, comme 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, 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 génération 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"
  }
}