Guide de migration

Ce guide explique comment migrer de l'API Core Reporting v3 vers l'API Analytics Reporting v4.

Introduction

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 Analytics Reporting version 4.

Points de terminaison

Les API Core Reporting v3 et 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 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 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"
    }],
    "dimensions": [
    {
      "name":"ga:pagePath"
    }]
  }]
}

Bibliothèques clientes et service de découverte

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 de la version 3 vers les paramètres de requête de la version 4.

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, les paramètres start-date et end-date permettent de 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 (ASCENDING ou DESCENDING) via le champ sortOrder.

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 v3 dans la version 4

Le champ segmentId de la version 4 de l'API est compatible avec la syntaxe de segment de la version 3 de l'API.

Les exemples suivants montrent comment le paramètre segment d'une requête v3 est pris en charge par 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 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 dans 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 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

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 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 à celui du 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 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, la réponse contient un tableau d'objets de rapport. Pour chaque ReportRequest envoyée, vous obtenez un rapport correspondant dans la réponse.

Rapports

Les rapports de la version 4 comportent trois champs de premier niveau: columnHeader, data et nextPageToken.

Étant donné que 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 à formater 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.

L'API Analytics Reporting v4 renvoie les données de 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 du rapport

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 des échantillons 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'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 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.\" }"
   }
  ]
 }
}