Guide de migration

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 (ASCENDING ou DESCENDING) dans 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 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 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, 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.\" }"
   }
  ]
 }
}