Ce document explique comment migrer le code existant de l'API Reporting Google Analytics v4 vers l'API Google Analytics Data v1 et présente brièvement les principales différences entre les deux API.
Pourquoi effectuer la migration ?
Si votre application doit accéder aux données d'une propriété Google Analytics 4, vous devez mettre à jour le code pour utiliser l'API Data v1. En effet, la version 4 de l'API Reporting ne peut accéder qu'aux propriétés créées avec Universal Analytics.
Prérequis
Familiarisez-vous avec les bases de l'API Data v1 à l'aide du guide de démarrage rapide.
Premiers pas
Pour commencer, vous devez préparer une propriété Google Analytics 4, activer la version 1 de l'API Data, puis configurer une bibliothèque cliente d'API adaptée à votre plate-forme.
Préparer une propriété Google Analytics 4
Avant de commencer à migrer votre code pour qu'il soit compatible avec la version 1 de l'API Data, vous devez migrer votre site Web pour utiliser une propriété Google Analytics 4. Il n'est pas possible de remplir une propriété Google Analytics 4 avec les données historiques d'une propriété Universal Analytics.
Activer l'API
Cliquez sur ce bouton pour activer automatiquement l'API Data v1 dans le projet Google Cloud sélectionné.
Activer l'API Google Analytics Data v1Utiliser une bibliothèque cliente
Installer une bibliothèque cliente
Si vous utilisez une bibliothèque cliente, vous devez installer la bibliothèque cliente Data API v1 pour votre langage de programmation.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Initialiser une bibliothèque cliente
Les bibliothèques clientes de la version 1 de l'API Data ont été conçues pour vous permettre de démarrer rapidement. Par défaut, les bibliothèques clientes tentent de trouver automatiquement les identifiants de votre compte de service.
Pour fournir facilement les identifiants du compte de service, définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS. Le client API utilisera la valeur de cette variable pour trouver le fichier JSON de la clé du compte de service.
Par exemple, vous pouvez définir les identifiants du compte de service en exécutant la commande suivante et en indiquant le chemin d'accès au fichier JSON du compte de service:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Vous trouverez ci-dessous les extraits de code couramment utilisés pour initialiser les bibliothèques clientes de l'API Data v1.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Au lieu d'utiliser une variable d'environnement, il est également possible de transmettre explicitement les identifiants à une instance de client API lors de l'initialisation. Vous trouverez ci-dessous les extraits de code utilisés pour initialiser les bibliothèques clientes de l'API Data v1 en transmettant explicitement les identifiants dans le code.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Ne pas utiliser de bibliothèque cliente
Si vous utilisiez l'API Reporting v4 sans bibliothèque cliente et que vous souhaitez continuer à le faire avec Data API v1, vous pouvez quand même utiliser vos identifiants.
Vous devez utiliser le nouveau point de terminaison HTTP et le nouveau document de découverte fournis par l'API Data:
Si votre code exploite un document de découverte, vous devez le mettre à jour vers le document de découverte fourni par Data API v1:
Après avoir mis à jour le point de terminaison, vous devez vous familiariser avec la nouvelle structure de requête et les nouveaux concepts de l'API Data afin de mettre à jour votre requête JSON.
Principales fonctionnalités de création de rapports
Méthodes de signalement disponibles
L'API Reporting v4 proposait une seule méthode batchGet pour accéder à sa fonctionnalité principale de création de rapports. Data API v1 propose plusieurs méthodes de création de rapports principales:
- runReport Cette méthode renvoie un rapport personnalisé de vos données d'événement Google Analytics. Il ne prend pas en charge la fonctionnalité de pivot et constitue une méthode privilégiée pour les requêtes de rapport simples.
- runPivotReport Cette méthode renvoie un rapport croisé dynamique personnalisé de vos données d'événement Google Analytics. Comme pour les tableaux croisés dynamiques dans la version 4 de l'API Reporting, chaque tableau croisé dynamique décrit les colonnes et les lignes de dimension visibles dans la réponse du rapport.
- batchRunReports : il s'agit d'une version par lot de la méthode
runReport, qui permet de générer plusieurs rapports à l'aide d'un seul appel d'API. - batchRunPivotReports : il s'agit d'une version par lot de la méthode
runPivotReportqui permet de générer plusieurs rapports à l'aide d'un seul appel d'API.
L'objectif de plusieurs méthodes de création de rapports est principalement pratique, certaines méthodes prenant en charge des fonctionnalités plus complexes que d'autres (tableaux croisés dynamiques, traitement par lot), mais partageant par ailleurs une structure de requête similaire.
Modifications du schéma de l'API
Les fonctionnalités de création de rapports de l'API Reporting et de l'API Data sont principalement déterminées par leur schéma, c'est-à-dire par les dimensions et les métriques acceptées dans les requêtes de création de rapports. Il existe des différences importantes au niveau des schémas d'API entre les deux API, en raison des différences conceptuelles entre Universal Analytics et Google Analytics 4.
- Familiarisez-vous avec la liste actuelle des dimensions et des métriques compatibles avec l'API Data. Actuellement, toutes les dimensions et métriques sont compatibles les unes avec les autres. Il n'est donc pas nécessaire d'utiliser l'Explorateur de dimensions et de métriques pour déterminer les combinaisons compatibles. Ce comportement évoluera à l'avenir.
- Les dimensions personnalisées dans Google Analytics 4 sont accessibles à l'aide de la syntaxe des dimensions personnalisées de l'API Data v1, qui doit être utilisée à la place des emplacements de dimensions ga:dimensionXX de la version 4 de l'API Reporting.
- Les métriques personnalisées dans Google Analytics 4 sont accessibles à l'aide de la syntaxe des métriques personnalisées de l'API Data v1, qui doit être utilisée à la place des emplacements de métriques ga:metricXX de l'API Reporting v4.
- Certaines dimensions et métriques disponibles dans Universal Analytics ont un équivalent direct dans Google Analytics 4. Pour en savoir plus, consultez le tableau des équivalences de schéma d'API UA/GA4.
- Les noms de dimensions et de métriques n'ont plus le préfixe
ga:dans Google Analytics 4. - Certaines fonctionnalités présentes dans Universal Analytics ne sont pas encore disponibles dans GA4 (par exemple, l'intégration de Campaign Manager, DV360 ou Search Ads 360). Une fois cette fonctionnalité implémentée dans Google Analytics 4, elle sera compatible avec l'API Data. De nouvelles dimensions et métriques seront alors ajoutées au schéma de l'API.
Entités
Le concept de vues (profils) n'existe pas dans Google Analytics 4 dans Universal Analytics. Par conséquent, les requêtes de reporting de l'API Data v1 ne contiennent aucun paramètre viewId. À la place, vous devez spécifier un ID numérique de propriété Google Analytics 4 dans un chemin d'URL de requête lorsque vous appelez les méthodes de la version 1 des API Data.
Ce comportement est différent de la version 4 de l'API Reporting, qui repose sur des ID de vue (profil) pour identifier l'entité de reporting.
API Data v1
Dans le cas de la version 1 de l'API Data, vous devez spécifier un ID de propriété Google Analytics 4 numérique dans le chemin de l'URL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
API Reporting v4
Reporting API v4 nécessite la spécification d'un ID de vue (profil) Universal Analytics dans le corps d'une requête de rapport.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Si vous utilisez l'une des bibliothèques clientes des API Data, il n'est pas nécessaire de manipuler manuellement le chemin de l'URL de la requête. La plupart des clients d'API fournissent un paramètre property qui attend une chaîne au format properties/GA4_PROPERTY_ID. Consultez le guide de démarrage rapide pour obtenir des exemples d'utilisation des bibliothèques clientes.
Périodes
L'API Reporting v4 et l'API Data v1 acceptent plusieurs plages de dates spécifiées à l'aide du champ dateRanges dans une requête de création de rapports. Les deux API partagent le même format de saisie de date et acceptent les valeurs de date absolues sous la forme YYYY-MM-DD, ou les dates relatives telles que yesderday, today, 7daysAgo, etc.
Les requêtes de l'API Data v1 sont limitées à quatre plages de dates, tandis que la version 4 de l'API Reporting permet de définir deux plages de dates dans une seule demande de rapport.
Chaque dateRange dans Data API v1 peut comporter un champ name facultatif qui peut être utilisé pour référencer la plage de dates correspondante dans une réponse.
Si name n'est pas fourni, le nom de la plage de dates est généré automatiquement.
Lorsque plusieurs plages de dates sont spécifiées dans une requête de l'API Data v1, une nouvelle dimension dateRange est automatiquement ajoutée à une réponse et le nom de la plage de dates est utilisé comme valeur de dimension. Notez que ce comportement est différent de celui de l'API Reporting v4, qui renvoie les données d'une plage de dates sous la forme d'un groupe de valeurs de métriques sur chaque ligne.
Requête de l'API Data v1
Un champ name facultatif est utilisé pour chaque valeur dateRange dans une requête.
Ce nom de plage de dates sera utilisé comme valeur de la dimension dateRange dans la réponse.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Réponse de l'API Data v1
Une dimension dateRange supplémentaire est automatiquement incluse dans la réponse.
La valeur de dimension dateRange contient le nom d'une plage de dates, qui provient du champ dateRange.name ou qui est généré automatiquement.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Requête de l'API Reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Réponse de l'API Reporting v4
Dans la version 4 de l'API Reporting, les valeurs de chaque plage de dates sont regroupées dans le champ metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Tri
Le comportement d'ordre des requêtes de rapport de l'API Data v1 peut être contrôlé à l'aide du champ orderBys, semblable au champ orderBys de la version 4 de l'API Reporting.
La spécification OrderBy a été modifiée dans la version 1 de Data API.
Chaque OrderBy peut contenir l'un des éléments suivants:
- DimensionOrderBy, trie les résultats en fonction des valeurs d'une dimension.
- MetricOrderBy, trie les résultats en fonction des valeurs d'une métrique.
- PivotOrderBy, utilisé dans les requêtes de tableaux croisés dynamiques et trie les résultats en fonction des valeurs d'une métrique dans un groupe de colonnes de tableaux croisés dynamiques.
Les types d'ordre DELTA, SMART et HISTOGRAM_BUCKET acceptés par Reporting API v4 ne sont pas implémentés dans Data API v1.
Le type d'ordre OrderType.NUMERIC de la version 1 de l'API Data correspond à la valeur OrderType.DIMENSION_AS_INTEGER de la version 4 de l'API Reporting.
Requête de l'API Data v1
Cet exemple présente un exemple de requête qui génère un rapport sur le nombre de sessions par pays, en triant les lignes selon la métrique sessions dans l'ordre décroissant.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Réponse de l'API Data v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Requête de l'API Reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Réponse de l'API Reporting v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Filtrage
Les clauses dimensionFilter et metricFilter de l'API Data v1 permettent de demander à l'API de ne renvoyer que des données de dimensions ou de métriques spécifiques. Cette méthode est semblable aux clauses dimensionFilterClauses et metricFilterClauses de l'API Reporting v4.
Data API v1 n'est pas compatible avec les chaînes d'expressions de filtre telles que la clause filtersExpression de la version 4 de l'API Reporting. Ces expressions doivent être réécrites à l'aide des clauses dimensionFilter et metricFilter.
Requête de l'API Data v1
Cet exemple de requête renvoie une liste du nombre de sessions pour certains chemins de page consultés par les utilisateurs.
La clause dimensionFilter permet de ne renvoyer que les lignes avec les valeurs de dimension pagePath commençant par /webstore/ et contenant la chaîne action=a12345.
La clause metricFilter demande à la méthode runReport de ne renvoyer que les lignes dont les valeurs de métrique sessions sont supérieures à 1 000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Requête de l'API Reporting v4
Cet exemple de requête est semblable à l'exemple de la version 1 de l'API Data. Elle renvoie la liste du nombre de sessions pour certains chemins de pages consultés par les utilisateurs.
Le champ dimensionFilterClauses ne permet de renvoyer que les lignes dont les valeurs de dimension pagePath commencent par /webstore/ et contiennent la chaîne action=a12345.
Le champ metricFilterClauses permet de ne renvoyer que les lignes dont les valeurs de métrique ga:sessions sont supérieures à 1 000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Pagination
Data API v1 utilise les champs limit et offset pour paginer les résultats des réponses qui s'étendent sur plusieurs pages, tandis que la version v4 de l'API Reporting utilise pageToken et pageSize.
Pour les requêtes de tableau croisé dynamique de l'API Data v1, les champs limit et offset de l'objet Pivot doivent être utilisés afin d'implémenter la pagination individuellement pour chaque tableau croisé dynamique. Le champ limit est désormais obligatoire pour chaque objet Pivot.
Par défaut, Data API v1 renvoie au maximum les 10 000 premières lignes de données d'événement, tandis que la valeur par défaut de l'API Reporting v4 est de 1 000 lignes.
Le nombre total de lignes correspondant à la requête est renvoyé à l'aide du champ rowCount dans une réponse de l'API Data v1, semblable à l'API Reporting v4.
Requête de l'API Data v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Réponse de l'API Data v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Requête de l'API Reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Réponse de l'API Reporting v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Agrégations de métriques
Data API v1 ne calcule les valeurs d'agrégation que lorsque le champ metricAggregations est spécifié dans une requête. En revanche, la version 4 de l'API Reporting renvoie les valeurs totale, minimale et maximale de chaque métrique, sauf si les champs hideTotals et hideValueRanges sont définis sur true.
Requête de l'API Data v1
Les agrégations ne seront calculées que si le champ metricAggregations est spécifié dans une requête.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Réponse de l'API Data v1
Les lignes de métriques agrégées sont renvoyées dans les champs totals, minimum et maximum d'une réponse. Pour les lignes de métriques agrégées, le champ dimensionValues contient une valeur spéciale de RESERVED_TOTAL, RESERVED_MAX ou RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Requête de l'API Reporting v4
Exemple de requête permettant de renvoyer le nombre de sessions par pays
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Réponse de l'API Reporting v4
Les champs totals, minimums et maximums sont présents par défaut dans les réponses de l'API Reporting v4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Tableaux croisés dynamiques
Data API v1 est compatible avec la fonctionnalité de tableau croisé dynamique dans les méthodes de création de rapports runPivotReport et batchRunPivotReports.
Reporting API v4 permet d'inclure des pivots dans les requêtes de rapport à l'aide de la méthode batchGet.
Les tableaux croisés dynamiques sont implémentés différemment dans la version 1 de l'API Data et dans la version 4, dans la mesure où chaque ligne de réponse représente une seule cellule du tableau, tandis que dans la version 4 de l'API Reporting, une seule ligne de réponse représente une ligne de tableau complète.
API Data v1
Vous trouverez ci-dessous un fragment de la réponse de l'API Data v1 à la requête runPivotReport. Chaque cellule du rapport croisé dynamique est renvoyée individuellement:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
API Reporting v4
Vous trouverez ci-dessous un fragment de la réponse de l'API Reporting v4 à la requête batchGet. Une seule ligne de réponse représente une ligne de tableau complète contenant toutes les valeurs de métriques pour le tableau croisé dynamique dans pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
Dans l'API Data v1, chaque dimension de la requête runPivotReport ou batchRunPivotReports doit être définie dans un objet de tableau croisé dynamique. Une dimension ne sera pas visible dans un rapport si elle n'est utilisée dans aucun tableau croisé dynamique d'une requête de tableau croisé dynamique.
Les colonnes croisées de la version 1 de l'API Data sont spécifiées à l'aide du champ fieldNames au lieu du champ dimensions de l'API Reporting v4.
Vous devez utiliser un filtre de dimension dont la portée est définie au niveau de la requête si le filtrage des dimensions est souhaité dans une requête de rapport de l'API Data v1. Elle est différente de la version 4 de l'API Reporting, qui accepte la spécification dimensionFilterClauses dans un objet de tableau croisé dynamique.
D'un point de vue fonctionnel, le champ offset de l'API Data v1 est semblable au champ startGroup de l'API Reporting v4.
Le champ limit de Data API v1 est semblable au champ maxGroupCount de Reporting API v4 et doit être utilisé pour limiter la cardinalité du rapport.
Data API v1 accepte plusieurs tableaux croisés dynamiques tant que le produit du paramètre limit de chaque tableau croisé dynamique ne dépasse pas 100 000. La version 4 de l'API Reporting n'accepte
qu'une seule dimension de tableau croisé dynamique.
Par défaut, Data API v1 classe les dimensions dans un tableau croisé dynamique en fonction de la première métrique du rapport. Ce comportement est différent de la version 4 de l'API Reporting, dans laquelle l'ordre des tableaux croisés dynamiques est déterminé par ordre décroissant du "total" des métriques demandées. Pour spécifier l'ordre de tri dans la version 1 de l'API Data, utilisez le champ orderBys d'une spécification de tableau croisé dynamique.
Requête de l'API Data v1
Cette requête de tableau croisé dynamique Data API v1 génère un rapport sur le nombre de sessions par pays, avec un tableau croisé dynamique selon la dimension browser. Notez que la requête utilise les champs orderBys, limit et offset pour reproduire le comportement d'une requête similaire de l'API Reporting v4, afin de conserver les paramètres de tri et de pagination.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
},
{
"name": "browser"
}
]
}
Réponse de l'API Data v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Requête de l'API Reporting v4
Cette requête de tableau croisé dynamique v4 de l'API Reporting crée un rapport sur le nombre de sessions par pays, basé sur la dimension ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Réponse de l'API Reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Cohortes
Data API v1 utilise la spécification CohortSpec pour configurer les rapports sur les cohortes. Cette spécification est semblable à la spécification CohortGroup de l'API Reporting v4.
Toutes les métriques disponibles dans la version 1 de l'API Data sont actuellement compatibles avec les requêtes de cohorte, tandis que la version 4 de l'API Reporting ne permet d'utiliser qu'un sous-ensemble de métriques spéciales dans une requête de cohorte.
Dans une requête de cohorte Data API v1, la métrique cohortActiveUsers est requise.
Les API Data v1 et Reporting v4 autorisent jusqu'à 12 cohortes par requête.
Les métriques de valeur vie ne sont actuellement pas compatibles avec Data API v1.
Équivalence des métriques de cohorte
La plupart des métriques de cohorte définies dans la version 4 de l'API Reporting peuvent être remplacées par une expression pour obtenir un résultat équivalent dans la version 1 de l'API Data, comme indiqué dans le tableau ci-dessous.
| Nom de la métrique de l'API Reporting v4 | Nom ou expression de la métrique de l'API Data v1 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohorteUtilisateursActifs/CohorteTotalUtilisateurs" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohorteUtilisateursActifs" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers", en plus d'un filtre de dimension de eventName correspondant à l'événement de réalisation d'objectif souhaité. |
Requête de l'API Data v1
Exemple de requête qui configure une cohorte d'utilisateurs dont la première session a eu lieu la semaine du 03/01/2021. Le nombre d'utilisateurs actifs et le taux de fidélisation des utilisateurs sont calculés pour la cohorte sur cinq semaines, en utilisant une précision WEEKLY.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Réponse de l'API Data v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Requête de l'API Reporting v4
Exemple de requête qui configure une cohorte d'utilisateurs dont la première session a eu lieu la semaine du 03/01/2021. Le nombre d'utilisateurs actifs et le taux de fidélisation des utilisateurs sont calculés pour la cohorte sur cinq semaines, en utilisant la précision WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Réponse de l'API Reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Échantillonnage
Data API v1 utilise automatiquement l'échantillonnage de données lorsqu'elle prévoit que les limites de cardinalité réduiront la qualité des données. Si les résultats d'une plage de dates sont échantillonnés, l'élément metadata de RunReportResponse contiendra un élément SamplingMetadata correspondant, semblable au champ samplingLevel présent dans la version 4 de l'API Reporting.
Fraîcheur des données
L'API Data ne fournit pas d'équivalent du champ isDataGolden de la version 4 de l'API Reporting, qui était utilisé pour indiquer si tous les appels d'un rapport étaient traités. Il est toujours possible que le même rapport renvoie des résultats différents lorsqu'il est interrogé à une date ultérieure en raison d'un traitement supplémentaire.
(Non compatible) Segments
Les segments ne sont actuellement pas compatibles avec Data API v1.
Rapports "Temps réel"
Utilisez la méthode properties.runRealtimeReport de la version 1 de l'API Data pour générer des rapports en temps réel pour les propriétés Google Analytics 4. La fonctionnalité de création de rapports en temps réel pour les propriétés Universal Analytics était fournie par la méthode data.realtime.get de l'API Google Analytics v3.
Le schéma de reporting en temps réel de l'API Data est différent du schéma de création de rapports en temps réel de l'API Analytics v3, en raison de différences conceptuelles entre Universal Analytics et Google Analytics 4.
Requête de l'API Data v1
Dans l'exemple suivant, afin de conserver le comportement de tri par défaut de la version 3 de l'API Google Analytics, un élément orderBy facultatif a été ajouté à l'exemple de requête de la version 1 de l'API Data.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Réponse de l'API Data v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Requête pour l'API Google Analytics v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Réponse de l'API Google Analytics v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Non compatible) Rapports sur l'activité des utilisateurs
L'API Data v1 n'est actuellement pas compatible avec la fonctionnalité permettant de signaler l'activité d'un utilisateur spécifique, semblable à la méthode userActivity.search de la version 4 de l'API Reporting.
Modifications des quotas d'API
Catégories de quotas principaux et en temps réel
Pour les besoins des quotas, l'API Data comporte deux catégories de requêtes: les requêtes principales et les requêtes en temps réel. Les requêtes API envoyées aux méthodes de reporting principales (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) facturent des quotas principaux.
Les requêtes API envoyées à la méthode runRealtimeReport facturent des quotas en temps réel.
Quotas de jetons
En plus des quotas de projet, chaque requête consomme des quotas de jetons de propriété facturés en fonction de la complexité de la requête. Veuillez consulter la documentation sur les quotas de l'API Data v1 pour obtenir une description détaillée des quotas et limites de l'API.
Pour connaître l'état actuel de tous les quotas d'une propriété Analytics, définissez returnPropertyQuota sur true dans une requête de rapport principale ou en temps réel. L'état du quota est renvoyé dans PropertyQuota.
(Non compatible) Quota basé sur les ressources
Tous les rapports principaux de Google Analytics 4 étant basés sur des données non échantillonnées, le quota basé sur les ressources introduit dans la version 4 de l'API Reporting n'est plus applicable, et il n'existe aucun équivalent du champ useResourceQuotas présent dans une requête de rapport de l'API Data v1.
(Non compatible) Quota de requêtes par vue (profil) et par jour
Comme il n'y a pas de vues dans Google Analytics 4, le quota requests per view (profile) per day n'est pas présent dans la version 1 de l'API Data et est remplacé par des quotas de jetons.