Ce guide fournit des consignes pour migrer la version 3 de l'API Core Reporting vers la version 4 de l'API Reporting.
Introduction
Pour profiter des nouvelles fonctionnalités introduites dans l'API Analytics Reporting v4, migrez votre code pour utiliser l'API. Ce guide présente les requêtes dans l'API Core Reporting version 3 et les requêtes équivalentes dans l'API Reporting d'Analytics v4 pour faciliter votre migration.
Migration Python
Si vous êtes un développeur Python, utilisez la bibliothèque d'aide GAV4 sur GitHub pour convertir les requêtes de la version 3 de l'API Core Reporting de Google Analytics en requêtes 4 de l'API Reporting.
Points de terminaison
L'API Core Reporting v3 et l'API Analytics Reporting v4 utilisent des points de terminaison et des méthodes HTTP différents:
Point de terminaison v3
GET https://www.googleapis.com/analytics/v3/data/ga
Point de terminaison v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
Les exemples suivants comparent une requête dans la version 3 et la requête équivalente dans la version 4:
v3
Documentation de référence sur v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
Documentation de référence sur la version 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
Bibliothèques clientes et service de découverte
Si vous utilisez le code Python, JavaScript ou une autre bibliothèque cliente qui repose sur Google Discovery Service, vous devez indiquer l'emplacement du document de découverte de l'API Reporting v4.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
Les bibliothèques clientes Java et PHP sont prédéfinies, mais vous pouvez les générer à l'aide du service de découverte et du générateur d'API Google.
Requests
La documentation de référence de l'API v4 décrit en détail la structure du corps de la requête. Les sections suivantes décrivent la migration des paramètres de requête v3 vers la version 4.
Afficher les ID
Dans la version 3, un paramètre ids, qui accepte un "ID de table", est au format ga:XXXX, où XXXX est l'ID de la vue (profil). Dans la version 4, un ID de vue (profil) est spécifié dans le champ viewId du corps de la requête.
Les exemples suivants comparent le paramètre ids dans une requête v3 et le champ viewId dans une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Périodes
L'API Reporting v4 vous permet de spécifier plusieurs plages de dates dans une seule requête. Le champ dateRanges accepte une liste d'objets DateRange.
Dans la version 3, vous utilisez les paramètres start-date et end-date pour spécifier une plage de dates dans une requête.
Les exemples suivants comparent les paramètres start-date et end-date dans une requête v3 et le champ dateRanges dans une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
Métriques
Le paramètre metrics de la version 3 correspond au champ metrics de la version 4, qui accepte une liste d'objets Metric.
Les exemples suivants comparent les paramètres metrics d'une requête v3 et le champ metrics d'une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
Dimensions
Le paramètre dimensions de la version 3 correspond au champ dimensions de la version 4, qui accepte une liste d'objets Dimension.
Les exemples suivants comparent les paramètres dimensions d'une requête v3 et le champ dimensions d'une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Tri
Le paramètre sort de la version 3 est équivalent au champ orderBys de la version 4, qui accepte une liste d'objets OrderBy.
Dans la version 4, vous pouvez trier les résultats par valeur de dimension ou de métrique:
- Indiquez son nom ou son alias dans le champ
fieldName. - Spécifiez l'ordre de tri (
ASCENDINGouDESCENDING) dans le champsortOrder.
Les exemples suivants comparent le paramètre sort dans une requête v3 et le champ orderBy dans une requête v4. Ils trient les utilisateurs par ordre décroissant et par ordre alphabétique:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
Niveau d'échantillonnage
Le paramètre samplingLevel de la version 3 correspond au champ samplingLevel de la version 4. Dans la version 3, les valeurs samplingLevel acceptées sont FASTER, HIGHER_PRECISION et DEFAULT. Dans la version 4, les valeurs samplingLevel acceptées sont SMALL, LARGE et DEFAULT.
Dans la version 3, FASTER est passé à SMALL dans la version 4, HIGHER_PRECISION étant remplacé par LARGE.
Les exemples suivants comparent le paramètre samplingLevel dans une requête v3 et le champ samplingLevel dans une requête v4:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
Segments
Le paramètre segment de la version 3 correspond au champ segments de la version 4, qui accepte une liste d'objets Segment.
ID des segments
Dans la version 4, pour demander un segment par ID de segment, créez un objet Segment et fournissez son ID via le champ segmentId.
Les exemples suivants comparent le paramètre segment dans une requête v3 et le champ segments dans une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
Segments dynamiques
Dans la version 4, pour exprimer des définitions de segments plus complexes, utilisez le champ segments qui inclut un objet DynamicSegment.
Les exemples suivants comparent le paramètre segment dans une requête v3 et le champ segments contenant un objet DynamicSegment dans une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
Vous pouvez combiner des conditions et des séquences dans un segment:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
Syntaxe des segments dans la version 4
Le champ segmentId de l'API v4 est compatible avec la syntaxe de segment dans l'API v3.
Les exemples suivants montrent comment le paramètre segment d'une requête v3 est compatible avec le champ segmentId de la requête équivalente dans la version 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filtres
la version 4 utilise dimensionFilterClauses pour filtrer les dimensions et metricFilterClauses pour filtrer les métriques. Un objet dimensionFilterClauses contient une liste d'objets DimensionFilter et un élément metricFilterClauses contient une liste d'objets MetricFilter.
Les exemples suivants comparent le paramètre filters dans une requête v3 et le champ dimensionFilterClauses dans une requête v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
v3 : syntaxe des filtres dans la v4
Bien que le champ filtersExpression dans la version 4 soit compatible avec la syntaxe filters dans la version 3, utilisez dimensionFilterClauses et metricFilterClauses pour filtrer les dimensions et les métriques.
Les exemples suivants montrent comment le paramètre filters d'une requête v3 est compatible avec le champ filtersExpression de la requête équivalente dans la version 4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
Lignes vides
Le paramètre include-empty-rows de la version 3 correspond au champ includeEmptyRows dans la version 4. Le paramètre v3 est défini par défaut sur true, tandis que dans le cas de la version 4, le champ est défini par défaut sur false. Si la valeur n'est pas définie dans la version 3, vous devez définir la valeur sur true dans la version 4.
Les exemples suivants comparent le paramètre include-empty-rows d'une requête v3 au champ includeEmptyRows d'une requête v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Pagination
La version 4 utilise les champs pageToken et pageSize pour paginer un grand nombre de résultats. Le pageToken est obtenu à partir de la propriété nextPageToken d'un objet de réponse.
Les exemples suivants comparent les paramètres start-index et max-results d'une requête v3 aux champs pageToken et pageSize d'une requête v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Paramètres standards
L'API Analytics Reporting v4 est compatible avec la plupart des paramètres de requête standards de l'API v3, à l'exception des paramètres userIp et callback.
Les exemples suivants comparent le paramètre quotaUser d'une requête v3 à celui d'une requête v4:
Point de terminaison v3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
Point de terminaison v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Réponses
Étant donné que la version 4 vous permet d'envoyer plusieurs objets ReportRequest dans une seule requête HTTP, vous obtenez un tableau d'objets de rapport dans la réponse. Pour chaque ReportRequest envoyé, vous recevez un rapport correspondant dans la réponse.
Rapports
Un rapport v4 comporte trois champs de premier niveau: columnHeader, data et nextPageToken.
Comme le corps de la réponse v4 n'inclut pas de réponses à tous les paramètres de requête, contrairement à la réponse v3, l'application cliente doit ajouter ce paramètre à ReportRequest pour obtenir une réponse à un paramètre de requête spécifique.
Nous avons déjà abordé nextPageToken dans la section Pagination. Commençons donc par examiner l'objet columnHeader.
En-tête de colonne
L'en-tête de colonne contient une liste de dimensions nommées et un objet MetricHeader, qui contient une liste d'objets MetricHeaderEntry. Chaque objet MetricHeaderEntry spécifie la métrique name et son type (devise, pourcentage, etc.)
, ce qui vous permet de mettre en forme le résultat.
Les exemples suivants comparent le champ columnHeaders d'une réponse v3 au champ columnHeader d'une réponse v4:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Lignes du rapport
L'API Core Reporting v3 renvoie les données du rapport dans le tableau rows, qui contient les dimensions et métriques demandées.
L'API Analytics Reporting v4 renvoie les données de rapport dans un objet ReportRow, qui contient un tableau de dimensions et d'objets DateRangeValues, chacun contenant une ou deux plages de dates, comme le montre le schéma suivant:
Lignes
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
Échantillon de données
Si les résultats sont échantillonnés, l'API Core Reporting v3 renvoie le champ booléen containsSampledData, qui est défini sur true.
L'API Analytics v4 ne renvoie pas de valeur booléenne si les données sont échantillonnées. En revanche, l'API renvoie les champs samplesReadCounts et samplingSpaceSizes.
Si les résultats ne sont pas échantillonnés, ces champs ne seront pas définis.
L'exemple Python suivant montre comment calculer si un rapport contient des données échantillonnées:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
Vous trouverez ci-dessous un exemple de réponse contenant des données échantillonnées à partir d'une requête comportant deux plages de dates. Les résultats ont été calculés à partir de près de 500 000 échantillons d'une taille d'espace d'échantillonnage d'environ 15 millions de sessions:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Analyser la réponse v4
L'exemple de code suivant analyse et affiche la réponse de l'API Reporting v4:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
Gestion des exceptions
Comme le format de réponse d'erreur de la version 4 est différent de celui de la version 3, mettez à jour votre code pour qu'il gère les réponses d'erreur de la version 4.
Les exemples suivants comparent une réponse d'erreur dans la version 3 et la réponse d'erreur équivalente dans la version 4:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}