L'API Data de Google Analytics v1 vous permet de générer des tableaux croisés dynamiques. Les tableaux croisés dynamiques sont un outil de synthèse de données qui visualise les données en réorganisant les informations du tableau en faisant pivoter vos données selon une ou plusieurs dimensions.
Prenons l'exemple de la table de données brutes suivante:
À l'aide de ces données, il est possible de créer un tableau croisé dynamique détaillant les données de session par navigateur, en sélectionnant des dimensions de pays et de langue comme tableaux croisés dynamiques supplémentaires.
Fonctionnalités partagées avec les rapports principaux
Les requêtes de rapport croisé dynamique ont la même sémantique que les requêtes de rapports principaux pour de nombreuses fonctionnalités partagées. Par exemple, la pagination, les filtres de dimensions et les propriétés utilisateur se comportent de la même manière dans les rapports croisés dynamiques que dans les rapports principaux. Ce guide est consacré aux fonctionnalités de création de rapports croisés dynamiques. Pour vous familiariser avec la fonctionnalité principale de reporting de la version 1 de l'API Data, consultez le guide sur les principes de base des rapports, ainsi que le guide des cas d'utilisation avancés.
Méthodes de reporting pivot
Data API v1 est compatible avec la fonctionnalité de tableau croisé dynamique dans les méthodes de création de rapports suivantes:
runPivotReport Cette méthode renvoie un rapport croisé dynamique personnalisé de vos données d'événement Google Analytics. Chaque tableau croisé dynamique décrit les colonnes et les lignes de dimensions visibles dans la réponse du rapport.
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.
Sélection d'une entité à l'origine du signalement
Toutes les méthodes de l'API Data v1 nécessitent que l'identifiant de propriété Google Analytics 4 soit spécifié dans un chemin de requête d'URL au format properties/GA4_PROPERTY_ID, par exemple:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Le rapport obtenu sera généré en fonction des données d'événement Google Analytics collectées dans la propriété Google Analytics 4 spécifiée.
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.
Demande de rapport croisé dynamique
Pour créer une requête avec un tableau croisé dynamique, utilisez la méthode runPivotReport ou batchRunPivotReports.
Pour demander des données croisées dynamiques, vous pouvez créer un objet RunPivotReportRequest. Nous vous recommandons de commencer par les paramètres de requête suivants:
- Une entrée valide dans le champ dateRanges.
- Au moins une entrée valide dans le champ dimensions.
- Au moins une entrée valide dans le champ metrics.
- Au moins deux entrées de tableau croisé dynamique valides dans le champ pivots
Voici un exemple de requête avec les champs recommandés:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Tableaux croisés dynamiques
Utilisez des objets Pivot dans le champ pivot du corps de la requête pour définir des tableaux croisés dynamiques dans les rapports. Chaque Pivot décrit les colonnes et les lignes de dimension visibles dans la réponse du rapport.
Data API v1 accepte plusieurs tableaux croisés dynamiques tant que le produit du paramètre limit pour chaque tableau croisé dynamique ne dépasse pas 100 000.
Vous trouverez ci-dessous un extrait illustrant l'utilisation de pivots pour créer un rapport sur le nombre de sessions par pays, pivoté par la dimension browser. Notez que la requête utilise le champ orderBys pour le tri, et les champs limit et offset pour implémenter la pagination.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Dimensions
Les dimensions décrivent et regroupent les données d'événement de votre site Web ou application. La dimension city, par exemple, indique la ville ("Paris" ou "New York") d'où provient chaque événement. Dans une demande de rapport, vous pouvez
spécifier zéro, une ou plusieurs dimensions.
Les dimensions doivent être définies dans le champ dimensions du corps de la requête. Pour être visibles dans un rapport, ces dimensions doivent également être répertoriées dans le champ fieldNames d'un objet Pivot.
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. Toutes les dimensions ne doivent pas être présentes dans le fieldNames d'un tableau croisé dynamique. Les dimensions ne peuvent être utilisées que dans les filtres, et non dans l'élément fieldNames d'un tableau croisé dynamique.
Vous trouverez ci-dessous un extrait illustrant l'utilisation des champs dimension et fieldNames pour une table avec des tableaux croisés dynamiques browser, country et language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Métriques
Les métriques sont des mesures quantitatives des données d'événements pour votre site Web ou votre application. Dans une demande de rapport, vous pouvez spécifier une ou plusieurs métriques. Consultez la page Métriques d'API pour obtenir la liste complète des noms de métriques API pouvant être spécifiés dans les requêtes.
Dans les requêtes de rapport croisé dynamique, les métriques sont définies à l'aide du champ metrics du corps de la requête, ce qui est semblable aux méthodes principales de création de rapports.
L'exemple ci-dessous spécifie le nombre de sessions à utiliser comme valeur de métrique dans un rapport:
"metrics": [
{
"name": "sessions"
}
],
Agrégations de métriques
Utilisez le champ metricAggregations d'un objet Pivot pour calculer les valeurs de métriques agrégées pour chaque tableau croisé dynamique.
Les agrégations ne seront calculées que si le champ metricAggregations est spécifié dans une requête.
Voici un extrait d'une requête qui demande les totaux pour la dimension pivot browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Les métriques calculées sont renvoyées dans le champ aggregates de l'objet RunPivotReportResponse. 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.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Pagination
Comme les méthodes principales de création de rapports, les requêtes de tableau croisé dynamique vous permettent de spécifier les champs limit et offset dans l'objet Pivot pour implémenter la pagination.
Les paramètres de pagination sont appliqués individuellement à chaque tableau croisé dynamique.
Le champ limit est obligatoire pour chaque objet Pivot afin de 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.
Vous trouverez ci-dessous un extrait illustrant l'utilisation des champs offset et limit pour récupérer les cinq dimensions language suivantes avec un décalage de 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtrage
Comme pour la fonctionnalité principale de reporting, vous devez utiliser un filtre de dimension avec un champ d'application de requête si vous souhaitez filtrer les dimensions dans une requête de rapport croisé dynamique.
Tri
Le comportement de classement des requêtes de rapport croisé dynamique peut être contrôlé pour chaque tableau croisé dynamique individuellement à l'aide du champ orderBys d'un objet Pivot, qui contient une liste d'objets OrderBy.
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 tableau croisé dynamique et trie les résultats en fonction des valeurs d'une métrique dans un groupe de colonnes de tableau croisé dynamique.
Cet exemple montre un extrait de définition de tableau croisé dynamique permettant de faire pivoter le rapport selon la dimension browser, en classant les résultats par ordre décroissant en fonction de la métrique sessions.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Signaler la réponse
La réponse de rapport croisé dynamique d'une requête d'API de rapport croisé dynamique se compose principalement d'un en-tête et de lignes.
En-têtes de réponse
L'en-tête du rapport croisé dynamique comprend les en-têtes PivotHeaders, DimensionHeaders et MetricHeaders qui répertorient les colonnes du rapport.
Par exemple, un rapport avec les dimensions croisées browser, country et language et la métrique sessions affichera les en-têtes suivants:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
Le graphique ci-dessous illustre le rôle de chaque composant de la réponse du rapport de tableau croisé dynamique dans le rendu du rapport de tableau croisé dynamique:
Lignes de réponse
La réponse du rapport de tableau croisé dynamique des méthodes runPivotReport et batchRunPivotReports diffère d'une réponse pour les méthodes principales de création de rapports, telles que runReport et batchRunReports, dans la mesure où chaque ligne de réponse de rapport croisé dynamique représente une seule cellule du tableau, tandis que dans un rapport standard, une seule ligne de réponse représente une ligne de tableau complète.
Vous trouverez ci-dessous un fragment de réponse de rapport de tableau croisé dynamique pour une requête avec les dimensions de tableau croisé dynamique browser, country et language, ainsi que la métrique sessions. Chaque cellule du rapport croisé dynamique est renvoyée individuellement:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Ces données correspondent aux deux cellules mises en surbrillance dans le tableau ci-dessous:
Bibliothèques clientes
Consultez le guide de démarrage rapide pour découvrir comment installer et configurer les bibliothèques clientes.
Vous trouverez ci-dessous un exemple d'utilisation de la bibliothèque cliente Python qui exécute une requête de tableau croisé dynamique pour créer un rapport sur le nombre de sessions par pays, pivoté en fonction de la dimension "Navigateur".
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Application de démonstration
Consultez l'application de démonstration des rapports croisés dynamiques de l'API Google Analytics v1 pour découvrir comment créer et afficher un rapport croisé dynamique à l'aide de JavaScript.