La version 1 de l'API Google Analytics Data vous permet de générer des tableaux croisés dynamiques. Tableau croisé dynamique tableaux sont un outil de synthèse des données qui visualise les données en réorganisant les les informations du tableau en croisant les données sur un ou plusieurs .
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, en décomposant les les données de sessions par navigateur, avec les dimensions de pays et de langue sélectionnées en tant que pivots supplémentaires.
Fonctionnalités partagées avec les rapports principaux
Les demandes de rapports croisés dynamiques ont la même sémantique que les demandes de rapport principales pour de nombreuses fonctionnalités partagées. Exemples : "pagination", "Filtres de dimensions" et "Utilisateurs" Les propriétés se comportent de la même manière dans les rapports croisés que les rapports principaux. Ce se concentre sur les fonctionnalités de création de rapports croisés dynamiques. Pour vous familiariser avec le Noyau la fonctionnalité de création de rapports de l'API Data v1, consultez le guide de base sur la création de rapports ; ainsi que les cas d'utilisation avancés.
Méthodes de reporting croisés
Data API v1 prend en charge les fonctionnalités de tableau croisé dynamique dans les méthodes de création de rapports suivantes:
runPivotReport. Cette méthode renvoie un rapport croisé personnalisé contenant vos données d'événement Google Analytics. Chaque Le tableau croisé dynamique décrit les colonnes et les lignes des dimensions visibles dans la réponse du rapport.
batchRunPivotReports : est une version traitement 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 la version 1 de l'API Data nécessitent l'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/v1beta/properties/GA_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 spécifiée.
Si vous utilisez l'une des bibliothèques clientes de l'API Data,
il n'est pas nécessaire de manipuler manuellement le chemin de l'URL de la requête. La plupart des clients API
fournissez un paramètre property qui attend une chaîne au format suivant :
properties/GA_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 élaborer une demande à partir d'un tableau croisé dynamique, utilisez l'une des méthodes runPivotReport ou batchRunPivotReports .
Pour demander des données croisées dynamiques, vous pouvez créer une 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 tableaux croisés dynamiques valides dans le champ pivots
Voici un exemple de requête avec les champs recommandés:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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
}
]
}
Pivots
Utiliser des objets Pivot dans le champ pivot de la requête
pour définir des rapports croisés. Chaque Pivot décrit la dimension visible
de colonnes et de lignes
dans la réponse du rapport.
La version 1 de l'API Data permet d'utiliser plusieurs tableaux croisés dynamiques si le produit de la limite de 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, en fonction de la dimension browser. Notez que
utilise le champ orderBys pour
tri, et les limites et
Champs 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 pour vos
votre site Web ou application. Par exemple, la dimension city indique la ville ("Paris"
ou "New York") d'où provient l'événement. Dans une demande de rapport, vous pouvez :
spécifiez zéro, une ou plusieurs dimensions.
Les dimensions doivent être définies à l'intérieur des
dimensions
du corps d'une requête. Pour être visibles dans un rapport, ces dimensions doivent également
être répertoriés dans le champ fieldNames ;
d'un objet Pivot.
Une dimension ne sera pas visible dans un rapport si elle n'est utilisée dans aucune
le tableau croisé dynamique
d'une requête de tableau croisé dynamique. Toutes les dimensions ne doivent pas être présentes dans le tableau croisé dynamique
fieldNames Les dimensions ne peuvent être utilisées que dans les filtres et non dans les
fieldNames de n'importe quel tableau croisé dynamique.
Vous trouverez ci-dessous un extrait illustrant l'utilisation des champs dimension et fieldNames
Pour un tableau 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 d'API. pouvant être spécifiées dans les requêtes.
Dans les demandes de rapport de tableau croisé dynamique, les métriques sont définies à l'aide du champ metrics du
corps de la requête. Il est semblable aux méthodes principales de création de rapports.
L'exemple ci-dessous indique le nombre de sessions à utiliser comme valeur de métrique dans un rapport:
"metrics": [
{
"name": "sessions"
}
],
Agrégations de métriques
Utiliser metricAggregations champ d'un objet Pivot pour calculer la métrique agrégée pour chaque tableau croisé dynamique.
Les agrégations ne seront calculées que si metricAggregations est spécifié dans une requête.
Vous trouverez ci-dessous un extrait d'une requête demandant les totaux pour
browser dimension de tableau croisé dynamique:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Les métriques calculées sont renvoyées sous forme d'agrégations.
de 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
Tout comme les méthodes principales de création de rapports, les demandes de tableau croisé dynamique vous permettent
pour spécifier la limite
et offset dans le
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 le
la cardinalité des rapports.
La version 1 de l'API Data permet d'utiliser plusieurs tableaux croisés dynamiques si le produit de la 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érez les cinq dimensions language suivantes avec un décalage de 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtrage
À l'instar de la fonctionnalité principale de création de rapports, filtre de dimension avec portée de la requête doit être utilisé si vous souhaitez filtrer les dimensions dans un rapport croisé dynamique requête.
Tri
L'ordre des requêtes de rapport de tableau croisé dynamique peut être contrôlé pour chaque tableau croisé dynamique individuellement à l'aide de la commande orderBys d'un objet Pivot, qui contient une liste de 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 en fonction des valeurs d'une métrique.
- PivotOrderBy, utilisé dans Faire pivoter les requêtes et trier les résultats en fonction des valeurs d'une métrique au sein d'un groupe de colonnes de tableau croisé dynamique.
Cet exemple montre l'extrait d'une définition de tableau croisé dynamique utilisant le rapport sous forme de tableau croisé dynamique
la dimension browser, en triant les résultats en fonction de la métrique sessions dans
ordre décroissant.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Signaler la réponse
Réponse au rapport croisé dynamique d'un tableau croisé dynamique la requête API report est principalement un en-tête et des lignes.
En-têtes de réponse
L'en-tête d'un rapport croisé se compose des éléments PivotHeaders, DimensionHeaders et MetricHeaders, qui répertorient les colonnes des sous forme de tableau croisé dynamique.
Par exemple, un rapport avec les dimensions de tableau croisé dynamique browser, country et language
et la métrique sessions générera des en-têtes comme ceux-ci:
{
"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 du rapport croisé dynamique. Réponse lors de l'affichage du rapport croisé dynamique:
Lignes de réponse
Réponse de runPivotReport au rapport de tableau croisé dynamique et batchRunPivotReports diffère de la réponse obtenue pour les méthodes de création de rapports principales comme runReport et batchRunReports car chaque ligne de réponse d'un rapport croisé représente une seule cellule de la de données, alors que dans un rapport standard, une seule ligne de réponse représente ligne de tableau.
Vous trouverez ci-dessous un fragment de réponse à un rapport de tableau croisé dynamique pour une
requête avec les dimensions de tableau croisé dynamique browser, country et language, et la
Métrique sessions. Chaque cellule du rapport croisé 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 en savoir plus sur les comment installer et configurer des bibliothèques clientes.
Les exemples suivants utilisent la bibliothèque cliente pour exécuter une requête de tableau croisé dynamique afin de créer une rapport du nombre de sessions par pays, en fonction de la dimension "Navigateur".
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient;
use Google\Analytics\Data\V1beta\DateRange;
use Google\Analytics\Data\V1beta\Dimension;
use Google\Analytics\Data\V1beta\Metric;
use Google\Analytics\Data\V1beta\OrderBy;
use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy;
use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy;
use Google\Analytics\Data\V1beta\Pivot;
use Google\Analytics\Data\V1beta\RunPivotReportRequest;
use Google\Analytics\Data\V1beta\RunPivotReportResponse;
/**
* Runs a pivot query to build a report of session counts by country,
* pivoted by the browser dimension.
* @param string $propertyId Your GA-4 Property ID
*/
function run_pivot_report(string $propertyId)
{
// Create an instance of the Google Analytics Data API client library.
$client = new BetaAnalyticsDataClient();
// Make an API call.
$request = (new RunPivotReportRequest())
->setProperty('properties/' . $propertyId)
->setDateRanges([new DateRange([
'start_date' => '2021-01-01',
'end_date' => '2021-01-30',
]),
])
->setPivots([
new Pivot([
'field_names' => ['country'],
'limit' => 250,
'order_bys' => [new OrderBy([
'dimension' => new DimensionOrderBy([
'dimension_name' => 'country',
]),
])],
]),
new Pivot([
'field_names' => ['browser'],
'offset' => 3,
'limit' => 3,
'order_bys' => [new OrderBy([
'metric' => new MetricOrderBy([
'metric_name' => 'sessions',
]),
'desc' => true,
])],
]),
])
->setMetrics([new Metric(['name' => 'sessions'])])
->setDimensions([
new Dimension(['name' => 'country']),
new Dimension(['name' => 'browser']),
]);
$response = $client->runPivotReport($request);
printPivotReportResponse($response);
}
/**
* Print results of a runPivotReport call.
* @param RunPivotReportResponse $response
*/
function printPivotReportResponse(RunPivotReportResponse $response)
{
print 'Report result: ' . PHP_EOL;
foreach ($response->getRows() as $row) {
printf(
'%s %s' . PHP_EOL,
$row->getDimensionValues()[0]->getValue(),
$row->getMetricValues()[0]->getValue()
);
}
}
Python
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your
// Google Analytics 4 property ID before running the sample.
// propertyId = 'YOUR-GA4-PROPERTY-ID';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Initialize client that will be used to send requests. This client only
// needs to be created once, and can be reused for multiple requests.
const analyticsDataClient = new BetaAnalyticsDataClient();
// Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.
async function runPivotReport() {
const [response] = await analyticsDataClient.runPivotReport({
property: `properties/${propertyId}`,
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',
},
],
});
printPivotReportResponse(response);
}
runPivotReport();
// Prints results of a runReport call.
function printPivotReportResponse(response) {
console.log('Report result:');
response.rows.forEach(row => {
row.dimensionValues.forEach(dimensionValue => {
console.log(dimensionValue.value);
});
row.metricValues.forEach(metricValue => {
console.log(metricValue.value);
});
});
}
Application de démonstration
Voir la démonstration du rapport "Tableau croisé dynamique" de l'API Google Analytics v1 l'application pour voir un exemple de création et d'affichage d'un rapport de tableau croisé dynamique en utilisant JavaScript.