Guide du développeur

Ce document explique comment utiliser l'API de création de rapports en temps réel pour obtenir des données Google Analytics.

Introduction

L'API Real Time Reporting vous permet de créer des rapports sur l'activité en cours sur votre propriété. Pour accéder aux données en temps réel, créez une requête qui spécifie une vue (profil) et au moins une métrique. Vous pouvez également fournir des paramètres de requête supplémentaires tels que des dimensions et des filtres pour affiner votre requête. Cette requête est envoyée à l'API Real Time Reporting, qui renvoie les données sous forme de table.

Si vous débutez avec l'API, lisez la présentation de l'API Real Time Reporting pour en savoir plus sur cette API et sur les données qu'elle fournit.

Prérequis

Avant d'utiliser l'API de création de rapports en temps réel pour obtenir des données Google Analytics:

  • 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 découvrir comment utiliser l'API seule (sans bibliothèque cliente) afin d'obtenir des données Google Analytics.

Chaque bibliothèque cliente fournit un seul objet de service d'analyse pour accéder à toutes les données de l'API Real Time Reporting. Pour créer un objet de service, procédez comme suit:

  1. Enregistrez votre application dans la console Google APIs.
  2. Autorisez l'accès aux données Google Analytics.
  3. Créez un objet de service Analytics.

Si vous n'avez pas effectué ces étapes, veuillez lire le tutoriel Hello Google Analytics API, qui vous guide à travers les premières étapes de la création d'une application à l'aide de l'API Google Analytics. Vous saurez ensuite comment utiliser l'API pour obtenir des données Google Analytics.

Utiliser l'API Real Time Reporting

Pour utiliser l'API de création de rapports en temps réel, une application doit:

  1. Interroge l'API Real Time Reporting.
  2. Gère la réponse de l'API.

Interroger l'API Real Time Reporting

L'objet de service d'analyse fournit une méthode pour créer une requête de l'API de création de rapports en temps réel. Pour en savoir plus sur les données et les paramètres de requête disponibles pour l'API, consultez les pages suivantes:

Après avoir défini une requête, appelez sa méthode execute pour l'envoyer aux serveurs Google Analytics.

Gérer la réponse de l'API

Si une requête adressée à l'API Real Time Reporting aboutit, l'API renvoie les données demandées dans une ressource de données en temps réel. Consultez la documentation de référence de l'API Real Time Reporting pour en savoir plus sur la structure et le format des réponses de l'API.

Si une erreur se produit, l'API renvoie un code d'état spécifique et un message décrivant l'erreur. Toutes les applications doivent détecter et gérer les erreurs. Consultez Réponses d'erreur pour obtenir une liste détaillée des erreurs et des recommandations concernant les nouvelles tentatives.

Exemples de code

La section Exemples de la page Données en temps réel: get fournit un exemple de code dans différents langages de programmation permettant d'interroger l'API Real Time Reporting et de gérer la réponse de l'API.

Contraintes de requête

Les restrictions qui s'appliquent aux requêtes de l'API Real Time sont les suivantes:

  • Si la métrique rt:activeUsers est incluse dans une requête avec les filtres de dimension suivants, seuls l'opérateur AND et le type de correspondance d'égalité (==) sont acceptés.
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Étant donné que la métrique rt:activeUsers ne récupère que le nombre d'utilisateurs actifs sur le site pour le moment, n'utilisez pas rt:minutesAgo avec rt:activeUsers. Autrement dit, rt:activeUsers implique que rt:minutesAgo est égal à 0.

  • Les filtres de métriques ne sont pas compatibles.
  • Le paramètre fields n'est pas compatible.

Gestion des quotas

Comme décrit dans la section Limites et quotas, des quotas quotidiens s'appliquent à l'API Real Time Reporting. Ils sont partagés avec d'autres API Google Analytics. Si vous interrogez l'API Real Time Reporting à de courts intervalles, vous atteindrez très rapidement les limites de quota quotidiennes. Dans ce cas, les requêtes provenant d'autres API Google Analytics cessent également de fonctionner jusqu'à ce que le quota soit actualisé.

Voici quelques exemples de mises en œuvre susceptibles d'épuiser très rapidement le quota:

  • Vous disposez de plusieurs tableaux de bord en temps réel interrogeant les données d'une seule vue Google Analytics (profil) à des intervalles très courts et sur une base quotidienne.
  • Vous disposez d'une propriété comptant de nombreux utilisateurs et vous avez implémenté un widget en temps réel. Chaque fois que le widget s'affiche pour un utilisateur, vous interrogez directement Google Analytics au lieu d'utiliser un cache.

Pour minimiser l'utilisation des quotas et les gérer efficacement:

  • Implémentez la mise en cache côté serveur. Lorsque plusieurs utilisateurs effectuent une requête portant sur les mêmes données en temps réel, vous devez renvoyer une réponse mise en cache au lieu d'interroger directement l'API Real Time Reporting pour chaque requête utilisateur. Actualisez ensuite régulièrement le cache avec les dernières données en temps réel à un intervalle d'actualisation raisonnable pour éviter de dépasser les limites de quota quotidiennes.
  • Combinez plusieurs requêtes en spécifiant des dimensions supplémentaires, puis analysez la réponse côté serveur ou côté client.
  • Augmentez l'intervalle de temps auquel vous demandez des données en temps réel.

Exemple: Calcul d'un intervalle d'actualisation

Si vous prévoyez d'envoyer des requêtes régulières pour obtenir des données en temps réel, sélectionnez un intervalle d'actualisation raisonnable en fonction de votre utilisation prévue.

Par exemple, une vue Google Analytics (profil) est limitée à 10 000 requêtes par jour. Au cours d'une même journée, si vous prévoyez d'envoyer 6 000 requêtes à l'API Core Reporting pour une vue (profil) unique, votre quota restant pour cette vue (profil) est de 4 000 requêtes.

Supposons que vous décidiez d'utiliser l'API Real Time Reporting pour mettre en œuvre trois tableaux de bord en temps réel qui exécutent toute la journée des requêtes portant sur les données en temps réel de la même vue (profil). Chaque tableau de bord peut effectuer environ 1 333 requêtes par jour (4 000 requêtes / 3). Une journée compte 86 400 secondes. Ainsi, l'intervalle d'actualisation de chaque tableau de bord doit être supérieur à 65 secondes (86 400 / 1 333) afin que le nombre total de requêtes quotidiennes pour la vue (profil) soit inférieur à la limite quotidienne de 4 000.