API de métadonnées – Guide du développeur

Ce document explique des concepts importants concernant l'utilisation de l'API Metadata pour accéder à la liste et aux attributs des colonnes Google Analytics.

Présentation

L'API Metadata renvoie la liste des colonnes (dimensions et métriques) affichées dans les API de création de rapports Google Analytics, ainsi que leurs attributs. Si vous débutez avec l'API, lisez la présentation de l'API Metadata pour en savoir plus.

Avant de commencer

Toutes les API Google Analytics sont accessibles de la même manière. Avant de commencer à utiliser l'API Metadata, vous devez:

  • Consultez la page Bibliothèques clientes pour obtenir la liste complète des bibliothèques clientes spécifiques aux langages de programmation qui fonctionnent avec l'API.
  • Lisez le guide de référence pour en savoir plus sur l'interface API et pour accéder aux données sans bibliothèque cliente.

Chaque bibliothèque cliente fournit un seul objet de service d'analyse pour accéder à toutes les données de l'API Metadata. Pour créer l'objet de service à utiliser avec l'API Metadata, vous devez généralement procéder comme suit:

  1. Enregistrez votre application dans la console Google APIs.
  2. Créez un objet de service Analytics et définissez la clé API.

Enregistrement et clé d'API

Votre application doit s'identifier chaque fois qu'elle envoie une requête à l'API Analytics en incluant une clé API dans chaque requête.

Obtenir et utiliser une clé API

Pour obtenir une clé API :

  1. Accédez à la page Identifiants dans la console API.
  2. Deux types d'identifiants sont disponibles pour cette API. Créez les identifiants adaptés à votre projet :

    • OAuth 2.0 : chaque fois que votre application demande des données utilisateur privées, elle doit envoyer un jeton OAuth 2.0 en même temps que la requête. Votre application envoie d'abord un identifiant client, puis éventuellement un code secret du client pour obtenir un jeton. Vous pouvez générer des identifiants OAuth 2.0 pour des applications Web, des comptes de service ou des applications installées.

      Remarque:Comme cette API ne dispose d'aucune méthode nécessitant une autorisation OAuth 2.0, vous n'aurez peut-être besoin que des clés API décrites ci-dessous. Toutefois, si votre application appelle d'autres API nécessitant une autorisation utilisateur, vous avez toujours besoin d'identifiants OAuth 2.0.

      Pour en savoir plus, consultez la documentation OAuth 2.0.

    • Clés API : une demande qui ne fournit pas de jeton OAuth 2.0 doit envoyer une clé API. Cette clé identifie votre projet et vous donne accès à l'API, aux quotas et aux rapports.

      L'API propose plusieurs types de restrictions applicables aux clés API. Si la clé API dont vous avez besoin n'existe pas déjà, créez-en une dans la console en cliquant sur Créer des identifiants  > Clé API. Vous pouvez restreindre la clé avant de l'utiliser en production en cliquant sur Restreindre la clé et en sélectionnant l'une des restrictions.

Pour sécuriser vos clés API, suivez les bonnes pratiques pour utiliser des clés API en toute sécurité.

Une fois la clé API obtenue, votre application peut ajouter le paramètre de requête key=yourAPIKey à toutes les URL de requête.

La clé API peut s'intégrer aux URL en toute sécurité et ne nécessite pas d'encodage.

Les extraits de code suivants montrent comment définir la clé API pour différentes bibliothèques clientes:

Java

import com.google.api.client.json.jackson2.JacksonFactory;
import com.google.api.client.http.javanet.NetHttpTransport;

import com.google.api.services.analytics.Analytics;
import com.google.api.services.analytics.AnalyticsRequestInitializer;

public class ApiKeySample {
  private static final String API_KEY = "YOUR API KEY";

  public static void main(String[] args) {
    NetHttpTransport netHttpTransport = new NetHttpTransport();
    JacksonFactory jacksonFactory = new JacksonFactory();

    // Set the API Key
    AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY);

    // Build the Analytics Service object
    Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null)
        .setAnalyticsRequestInitializer(analyticsInitializer)
        .setApplicationName("ApiKeySample")
        .build();

    // Start coding cool things.
  }
}

Python

from apiclient.discovery import build

API_KEY = 'YOUR API KEY'

def main(argv):
  # Set the API Key and build the Analytics service object.
  service = build('analytics', 'v3', developerKey=API_KEY)

  # Start coding cool things.

PHP

require_once 'google-api-php-client/src/Google_Client.php';
require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php';

const API_KEY = 'YOUR API KEY'

$client = new Google_Client();

// Set the API Key
$client->setDeveloperKey($API_KEY);

// Build the Analytics Service object.
$analytics = new google_AnalyticsService($client);

// Start coding cool things.

JavaScript

<!--
  Method 1:
  Using the Google APIs Client Library for JavaScript
-->
<script>
var apiKey = 'YOUR API KEY';

function handleClientLoad() {
  gapi.client.setApiKey(apiKey);
  gapi.client.load('analytics', 'v3', makeRequest);
}

function makeRequest() {
  // Start coding cool things.
}
</script>
<script src="//apis.google.com/js/client.js?onload=handleClientLoad"></script>


<!--
  Method 2:
  Using REST and callback parameter
-->
<script>
function render() {
  // Place your awesome code here.
}
</script>

<!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. -->
<script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>

Attributs de la colonne

La réponse de l'API Metadata inclut une propriété attributeNames qui répertorie tous les attributs de colonne valides. Chaque colonne comporte une propriété attributes qui inclut un sous-ensemble d'attributs qui lui sont applicables.

Le tableau suivant présente la liste complète des attributs valides:

Cas d'utilisation

L'API Metadata peut être utilisée pour résoudre les cas d'utilisation suivants:

Colonnes obsolètes

Si une colonne (c'est-à-dire une dimension ou une métrique) est obsolète, son attribut status sera défini sur DEPRECATED.

L'extrait de code suivant montre comment vérifier si une colonne est obsolète à l'aide de l'attribut status:

function isDeprecated(column) {
  return column.attributes.status == 'DEPRECATED';
}

Si une colonne est renommée/supprimée, son attribut status sera défini sur DEPRECATED, et un attribut replacedBy peut être défini sur la Id de la colonne de remplacement.

L'extrait de code suivant montre comment utiliser l'attribut replacedBy pour obtenir l'ID de la colonne de remplacement:

function getReplacementId(column) {
  return column.attributes.replacedBy;
}

Noms de colonnes

L'attribut uiName correspond au nom de la dimension ou de la métrique utilisé dans les interfaces utilisateur Google Analytics (par exemple, l'interface Web).

L'extrait de code suivant montre comment récupérer le nom de l'interface utilisateur d'une colonne:

function getColumnName(column) {
  return column.attributes.uiName;
}

Colonnes modélisées

Les colonnes modélisées incluent des dimensions ou des métriques associées à un indice numérique. (par exemple, ga:goalXXStarts, ga:dimensionXX, ga:metricXX, etc.). Une colonne modélisée comporte des attributs minTemplateIndex et maxTemplateIndex qui définissent la plage d'index.

L'extrait de code suivant montre comment vérifier si une colonne est modélisée:

function isTemplatized(column) {
  return !!column.attributes.minTemplateIndex ||
         !!column.attributes.maxTemplateIndex;
}

L'extrait de code suivant montre comment récupérer la liste des ID valides pour une colonne modélisée:

function getTemplatizedIdList(column) {
  var columnIdList = [];
  var columnId = column.id;

  if (isTemplatized(column)) {
    minIndex = parseInt(column.attributes.minTemplateIndex);
    maxIndex = parseInt(column.attributes.maxTemplateIndex);

    for (var i = minIndex; i <= maxIndex; i++) {
      columnIdList.push(columnId.replace('XX', i));
    }
  }
  return columnIdList;
}

Colonnes calculées

Une colonne dérivée d'un calcul d'autres colonnes possède un attribut calculation. Par exemple, le calcul pour ga:percentNewSessions est ga:newSessions / ga:sessions.

L'exemple suivant montre comment vérifier si une colonne est calculée et comment récupérer le calcul d'une colonne:

function isCalculated(column) {
  return !!column.attributes.calculation;
}

function getCalculation(column) {
  return column.attributes.calculation;
}

Colonnes et segments

L'attribut allowedInSegments vous permet de vérifier si une colonne peut être utilisée dans le paramètre de requête de segment.

L'exemple suivant montre comment déterminer si une colonne peut être utilisée dans des segments:

function isAllowedInSegments(column) {
  return !!column.attributes.allowedInSegments;
}

Ajouté à la version de l'API

Utilisez l'attribut addedInApiVersion pour vérifier si une colonne peut être utilisée dans une API de création de rapports d'une version spécifiée. Par exemple, appelez la fonction suivante pour vérifier que la colonne peut être utilisée dans l'API Core Reporting V3: 

function isAllowedInV3(column) {
  return column.attributes.addedInApiVersion < 4;
}

ETag

Un ETag est inclus dans chaque réponse de l'API Metadata. L'ETag est un identifiant qui peut être utilisé pour mettre en cache et mettre à jour les réponses de l'API Metadata. Ce point est important, car les données des colonnes (dimensions et métriques) peuvent rester inchangées pendant de longues périodes.De plus, il est inefficace d'effectuer des requêtes et des mises à jour inutiles lorsque des données mises en cache peuvent être utilisées.

Si vous stockez l'ETag d'une collection de colonnes, vous pouvez principalement l'utiliser de deux manières: pour vérifier si une réponse de l'API Metadata mise en cache est à jour et pour l'inclure dans une requête d'API Metadata.

Vérifier une réponse mise en cache

Si vous comparez la valeur ETag renvoyée par une réponse de l'API Metadata et qu'elle est équivalente à l'ETag pour une ressource mise en cache, la version mise en cache est à jour. Si les ETag ne sont pas équivalents, mettez à jour votre application et actualisez le cache avec la dernière réponse.

Si vous souhaitez ne récupérer que la valeur ETag de l'API Metadata, définissez le paramètre de requête fields sur etag lorsque vous effectuez une requête. Voir un exemple

Utiliser un ETag avec une requête API

Si vous disposez d'une version mise en cache d'une collection de colonnes, vous pouvez inclure sa valeur ETag dans une requête de l'API Metadata en définissant le champ d'en-tête HTTP If-None-Match. L'API Metadata vérifie la valeur ETag et renvoie une version mise à jour de la ressource et l'état HTTP 200 OK, ou une réponse vide avec l'état 304 Not Modified si votre version mise en cache est à jour.