Ce guide fournit des consignes pour migrer l'API Core Reporting v3 vers l'API Analytics Reporting v4.
Présentation
Pour profiter des nouvelles fonctionnalités introduites dans la version 4 de l'API Analytics Reporting, migrez votre code afin d'utiliser l'API. Ce guide présente les requêtes dans la version 3 de l'API Core Reporting et les requêtes équivalentes dans la version 4 de l'API Analytics Reporting pour faciliter la 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 l'API Core Reporting v3 de Google Analytics en requêtes de l'API Reporting version 4.
Points de terminaison
Les API Core Reporting v3 et Analytics Reporting v4 disposent de points de terminaison et de 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 à la requête équivalente dans la version 4:
v3
Documentation de référence de la version 3
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 de 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"
}]
}]
}
Service de découverte et de bibliothèques clientes
Si vous utilisez Python, JavaScript ou une autre bibliothèque cliente qui repose sur le service Google Discovery, vous devez indiquer l'emplacement du document de découverte pour 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 utiliser le service de découverte et le générateur d'API Google pour les générer.
Requêtes
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 les paramètres de requête v4.
ID des vues
Dans la version 3, un paramètre ids, qui accepte un "ID de table", se présente au format ga:XXXX, où XXXX correspond à 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 Analytics 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 dans une requête v3 et le champ metrics 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 \
&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 dans une requête v3 et le champ dimensions dans 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, pour trier les résultats en fonction d'une 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 tous deux les utilisateurs par ordre décroissant et les sources 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.
Notez que FASTER dans la version 3 est passé à SMALL dans la version 4, et HIGHER_PRECISION à 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 de segment
Dans la version 4, pour demander un segment par ID de segment, créez un objet Segment et indiquez son ID dans 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 segment 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 v3
Dans l'API v4, le champ segmentId est compatible avec la syntaxe de segment de la version 3.
Les exemples suivants montrent comment le paramètre segment d'une requête v3 est pris en charge par le champ segmentId dans 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 dimensionFilterClauses contient une liste d'objets DimensionFilter et un 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"]
}]
}]
}]
Syntaxe des filtres de la version 3 dans la version 4
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 pris en charge par le champ filtersExpression dans 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
Dans la version 3, le paramètre include-empty-rows correspond au champ includeEmptyRows dans la version 4. La valeur par défaut du paramètre v3 est true, tandis que dans la version 4, la valeur par défaut du champ est false. Si la valeur n'est pas définie dans la version 3, vous devez la définir sur true dans la version 4.
Les exemples suivants comparent le paramètre include-empty-rows dans une requête v3 au champ includeEmptyRows dans 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 dans 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
La version 4 de l'API Analytics Reporting 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 dans 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 demande ReportRequest envoyée, vous obtenez un rapport correspondant dans la réponse.
Rapports
Dans la version 4, un rapport comporte trois champs de premier niveau: columnHeader, data et nextPageToken.
Comme le corps de la réponse v4 n'inclut pas les réponses à tous les paramètres de requête comme le fait 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. Examinons donc d'abord 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.)
, qui vous aide à mettre en forme la sortie.
Les exemples suivants comparent le champ columnHeaders dans une réponse v3 au champ columnHeader dans 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 de rapport dans le tableau rows (lignes), qui contient les dimensions et métriques demandées.
La version 4 de l'API Analytics Reporting renvoie les données du rapport dans un objet ReportRow, qui contient un tableau de dimensions et un tableau 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, la version 3 de l'API Core Reporting renvoie le champ booléen containsSampledData, qui est défini sur true.
La version 4 de l'API Analytics Reporting ne renvoie pas de valeur booléenne si les données sont échantillonnées. Au lieu de cela, 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 un échantillon de données provenant d'une requête portant sur deux plages de dates. Les résultats ont été calculés à partir de près de 500 000 échantillons d'un 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 imprime la réponse de l'API Analytics 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
Étant donné que 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 à 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.\" }"
}
]
}
}