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 générée à partir de cette demande peut être utilisée pour accéder des rapports personnalisés de tous les utilisateurs disposant d'un accès en lecture à vos données Google Analytics .

Une fois prêt, un rapport personnalisé est disponible pendant 72 heures. Après cela la ressource correspondante de la tâche de rapport 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 reportTasks.create est nécessaire pour créer une tâche de rapport. Ensuite, reportTasks.query 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 concernant une tâche de rapport spécifique. reportTasks.list afin de répertorier toutes les tâches liées aux rapports pour une propriété.

Sélectionner une entité de reporting

Toutes les méthodes de la version 1 de l'API Data nécessitent le paramètre Identifiant de propriété Google Analytics dans un chemin de requête d'URL sous la forme suivante : 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 de l'événement Google Analytics les données collectées dans la propriété Google Analytics spécifiée.

Si vous utilisez l'une des bibliothèques clientes de l'API Data, procédez comme suit : 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 un sous la forme properties/GA_PROPERTY_ID. Consultez le Guide de démarrage rapide pour obtenir des exemples. de l'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 la méthode 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 la réponse Nom de la tâche dans le champ name (par exemple, properties/1234567/reportTasks/123), qui peut être utilisé dans les requêtes suivantes pour obtenir le statut d'une tâche de rapport et récupérer les 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 du rapport

Une fois le rapport terminé, la génération d'un rapport peut prendre plusieurs minutes. 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 du rapport (par exemple, properties/1234567/reportTasks/123). que vous avez reçue d'une réponse reportTasks.create pour spécifier Signaler la tâche.

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 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.

reportMetadata contient les 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 du rapport créée à l'aide de reportTasks.create est générée, appelez la méthode reportTasks.query et spécifiez le nom de la tâche (properties/1234567/reportTasks/123, par exemple).

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"
  }
}