API de gestion - Autorisation

Ce guide décrit comment une application autorise les requêtes adressées à l'API Management.

Autoriser les requêtes

Pour pouvoir consulter les informations de leur compte sur le site Web Google Analytics, les utilisateurs doivent d'abord se connecter à leur compte Google. De même, lorsque les utilisateurs accèdent à votre application pour la première fois, ils doivent autoriser votre application à accéder à leurs données.

Chaque demande envoyée par votre application à l'API Analytics doit inclure un jeton d'autorisation. Celui-ci permet également d'identifier votre application auprès de Google.

À propos des protocoles d'autorisation

Votre application doit autoriser les requêtes via le protocole OAuth 2.0. Les autres protocoles d'autorisation ne sont pas acceptés. Si votre application utilise la fonctionnalité Se connecter avec Google, certains aspects de l'autorisation sont traités pour vous.

Autoriser des requêtes avec OAuth 2.0

Toutes les demandes envoyées à l'API Analytics doivent être autorisées par un utilisateur authentifié.

Les détails de la procédure d'autorisation (ou "flux") concernant OAuth 2.0 varient légèrement selon le type d'application que vous développez. La procédure générale suivante s'applique à tous les types d'applications :

  1. Lorsque vous créez votre application, vous l'enregistrez dans la console d'API Google. Google fournit ensuite des informations dont vous aurez besoin ultérieurement, dont un ID client et un code secret du client.
  2. Activez l'API Analytics dans la console Google APIs. Si l'API ne figure pas dans la console, ignorez cette étape.
  3. Lorsque votre application doit accéder à des données utilisateur, elle demande à Google un champ d'application d'accès particulier.
  4. Google affiche alors un écran d'autorisation, dans lequel l'utilisateur est invité à autoriser votre application à demander certaines de ses données.
  5. Si l'utilisateur accepte, Google attribue à votre application un jeton d'accès temporaire.
  6. Votre application demande des données utilisateur en joignant le jeton d'accès à la requête.
  7. Dès lors que Google valide la requête et le jeton, les données demandées sont renvoyées.

Certains flux comportent d'autres étapes, comme l'utilisation de jetons d'actualisation afin d'obtenir de nouveaux jetons d'accès. Pour en savoir plus sur les flux concernant divers types d'applications, consultez la documentation OAuth 2.0 de Google.

Voici les informations relatives au champ d'application OAuth 2.0 pour l'API Analytics:

Portée Signification
https://www.googleapis.com/auth/analytics.readonly Accès en lecture seule à l'API Analytics.
https://www.googleapis.com/auth/analytics.edit Modifiez les entités de gestion Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users Affichez et gérez les autorisations des utilisateurs pour les comptes Analytics.
https://www.googleapis.com/auth/analytics.manage.users.readonly Affichez les autorisations des utilisateurs Google Analytics.

Pour demander l'accès via OAuth 2.0, vous avez besoin du champ d'application ainsi que des informations fournies par Google lors de l'enregistrement de l'application (l'ID client et le code secret du client, par exemple).

Conseil : Les bibliothèques clientes des API Google peuvent gérer une partie de la procédure d'autorisation à votre place. Elles sont proposées pour une grande variété de langages de programmation. Pour en savoir plus, explorez les bibliothèques clientes et les exemples de code présentés sur la page Installer les bibliothèques clientes.

Flux OAuth 2.0 courants

Voici la liste des cas d'utilisation courants pour des flux OAuth 2.0 spécifiques:

Serveur Web

Ce flux est idéal pour un accès automatisé, hors connexion ou planifié des données Google Analytics d'un utilisateur.

Exemple :

  • Mise à jour automatique des tableaux de bord des utilisateurs avec les dernières données Google Analytics

Côté client

Ce flux est idéal pour les applications qui permettent aux utilisateurs d'accéder directement à leurs données Google Analytics à partir d'un navigateur. Elle élimine le recours aux fonctionnalités côté serveur, mais elle rend peu pratiques les rapports automatisés, hors connexion et planifiés.

Exemple :

Applications installées

Ce flux est destiné aux applications distribuées en tant que package et installées par l'utilisateur. Ce flux nécessite que l'application ou l'utilisateur ait accès à un navigateur pour terminer le processus d'authentification.

Exemples :

  • Widget de bureau sur PC ou Mac.
  • Plug-in pour un système de gestion de contenu : l'avantage de ce flux par rapport au serveur Web ou côté client est qu'un seul projet de console API peut être utilisé pour votre application. Cela permet de regrouper les rapports et de simplifier l'installation pour les utilisateurs.

Service Accounts

Les comptes de service permettent d'accéder de manière automatisée, hors connexion ou planifiée aux données Google Analytics pour votre propre compte. Par exemple, vous pouvez créer un tableau de bord en direct de vos données Google Analytics et le partager avec d'autres utilisateurs.

Pour commencer à utiliser l'API Analytics, vous devez d'abord utiliser l'outil de configuration. Celui-ci vous explique comment créer un projet dans la console Google APIs, activer l'API et créer des identifiants.

Pour configurer un nouveau compte de service:

  1. Cliquez sur Créer des identifiants > Clé de compte de service.
  2. Choisissez de télécharger la clé publique/privée du compte de service sous la forme d'un fichier P12 standard ou d'un fichier JSON pouvant être chargé par une bibliothèque cliente des API Google.

Votre nouvelle paire de clés publique et privée est générée et téléchargée sur votre ordinateur. Il s'agit de la seule copie de cette clé. Vous êtes responsable de leur stockage sécurisé.

Dépannage

Votre autorisation échoue dans les situations suivantes:

  • Vous recevrez un code d'état 401 si votre access_token a expiré ou si vous utilisez le champ d'application incorrect pour l'API.

  • Vous obtiendrez un code d'état 403 si l'utilisateur autorisé n'a pas accès à la vue (profil). Assurez-vous d'être autorisé avec la bonne personne et qu'elle dispose bien de la vue (profil) que vous avez sélectionnée.

OAuth 2.0 Playground

Cet outil vous permet de parcourir l'intégralité du processus d'autorisation via une interface Web. L'outil affiche également tous les en-têtes de requêtes HTTP requis pour exécuter une requête autorisée. Si vous n'êtes pas autorisé à travailler dans votre propre application, essayez de la faire fonctionner dans OAuth 2.0 Playground. Vous pouvez ensuite comparer les en-têtes HTTP et les requêtes provenant de Playground à ce que votre application envoie à Google Analytics. Cette vérification est un moyen simple de vous assurer que vos requêtes sont correctement formatées.

Octroi non valide

Lorsque vous essayez d'utiliser un jeton d'actualisation, le message suivant renvoie une erreur invalid_grant:

Les applications peuvent demander plusieurs jetons d'actualisation pour accéder à un même compte Google Analytics.

Par exemple, si un utilisateur souhaite installer une application sur plusieurs machines et accéder au même compte Google Analytics, il aura besoin d'un jeton distinct pour chaque machine. Lorsque le nombre de jetons d'actualisation dépasse la limite, les plus anciens ne sont plus valides. Si l'application tente d'utiliser un jeton d'actualisation non valide, une réponse d'erreur invalid_grant est renvoyée.

Chaque paire de client OAuth 2.0 et de compte Google Analytics est limitée à 25 jetons d'actualisation. Si l'application continue à demander des jetons d'actualisation pour la même paire client/compte, une fois le 26e jeton émis, le premier jeton d'actualisation précédemment émis n'est plus valide. Le 27e jeton d'actualisation demandé invalidera le deuxième jeton précédemment émis, et ainsi de suite.