API Metadata - Guide du développeur

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

Introduction

L'API Metadata renvoie la liste des colonnes (c'est-à-dire les dimensions et les métriques) exposées dans les API de création de rapports de Google Analytics, ainsi que leurs attributs. Si vous débutez avec l'API Metadata, consultez la page Présentation de l'API Metadata.

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 de langage de programmation compatibles avec l'API.
  • Consultez le guide de référence pour en savoir plus sur l'interface d'API et l'accès aux données sans bibliothèque cliente.

Chaque bibliothèque cliente fournit un objet de service d'analyse unique permettant d'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 suivre la procédure suivante:

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

Enregistrement et clé API

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

Obtenir et utiliser une clé API

Pour obtenir une clé API :

  1. Ouvrez 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, il vous faudra peut-être uniquement obtenir des clés API décrites ci-dessous. Toutefois, si votre application appelle d'autres API nécessitant une autorisation utilisateur, vous avez tout de même besoin des 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 colonne

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

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 (une dimension ou une métrique) est obsolète, son attribut status sera défini sur DEPRECATED.

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

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 le 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 des colonnes

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

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

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

Colonnes modélisées

Les colonnes de modèles comprennent des dimensions ou des métriques avec un index numérique. Par exemple, ga:goalXXStarts, ga:dimensionXX, ga:metricXX, etc. Une colonne de modèles comporte les 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 comporte un attribut calculation. Par exemple, le calcul de ga:percentNewSessions est de ga:newSessions / ga:sessions.

L'exemple suivant montre comment vérifier si une colonne est calculée et comment récupérer le calcul pour 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 la version 3 de l'API Core Reporting: 

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 (c'est-à-dire les dimensions et les métriques) peuvent rester inchangées pendant de longues périodes, et 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 les ETag d'une collection de colonnes, vous pouvez les utiliser principalement de deux manières: vérifier si une réponse de l'API Metadata mise en cache est à jour et l'inclure dans une requête 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 d'une ressource mise en cache, la version mise en cache est à jour. Si les ETags ne sont pas équivalents, mettez à jour votre application et actualisez le cache avec la dernière réponse.

Si vous souhaitez uniquement récupérer 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 d'API Metadata en définissant le champ d'en-tête HTTP If-None-Match. L'API Metadata vérifiera la valeur ETag et répondra avec une version mise à jour de la ressource et un état HTTP 200 OK ou une réponse vide avec un état 304 Not Modified si la version mise en cache est à jour.