Configurer Google Cloud et OAuth

L'accès à l'API Google Health est fourni par le biais de Google Cloud. Pour activer l'API et autoriser un compte Google, vous aurez besoin d'un projet Google Cloud.

Que vous soyez un développeur d'API Fitbit existant ou que vous découvriez l'API Google Santé, vous devrez effectuer cette étape pour pouvoir appeler l'API.

Créer un projet et un client OAuth

Cliquez sur le bouton Activer l'API et obtenir un ID client OAuth 2.0 pour activer l'API Google Health et obtenir un ID client OAuth 2.0 :

  1. Si vous disposez déjà d'un projet Google Cloud que vous souhaitez utiliser pour l'API Google Health, assurez-vous d'abord d'être connecté au compte administrateur de ce projet. Ensuite, sélectionnez le projet existant dans la liste des projets disponibles après avoir cliqué sur le bouton. Sinon, créez un projet.
  2. Sélectionnez Web Server (Serveur Web) lorsque vous êtes invité à indiquer "Where are you calling from?" (D'où appelez-vous ?).
  3. Saisissez https://www.google.com comme valeur pour URI de redirection autorisés. Un URI de redirection est nécessaire pour obtenir un code d'autorisation à l'aide d'OAuth 2.0.
  4. Une fois la configuration terminée, copiez les valeurs de l'ID client et du code secret du client OAuth 2.0, puis téléchargez le fichier JSON des identifiants sur votre ordinateur local.
Activer l'API et obtenir un ID client OAuth 2.0

Si vous souhaitez configurer manuellement votre projet Google Cloud, ou vérifier la configuration et récupérer à nouveau vos identifiants :

  1. Activez l'API Google Health sur la page Activation des API.
  2. Obtenez un ID client OAuth 2.0 sur la page Identifiants.

Pour en savoir plus sur la configuration d'OAuth 2.0 à l'aide de la console Google, consultez Utiliser OAuth 2.0 pour accéder aux API Google.

Utiliser des projets distincts pour la préproduction et la production

L'API Google Health ne fournit pas d'environnement de bac à sable ni de préproduction distinct. Tous vos environnements appellent l'API Google Health de production. Vous gérez donc la séparation des environnements au niveau du projet Google Cloud.

Lorsque vous configurez des environnements pour votre application, suivez ces bonnes pratiques :

  • Créez des projets Google Cloud distincts pour vos environnements de développement, de préproduction et de production. Chaque projet gère son propre client OAuth 2.0, son écran de consentement et ses abonnés aux webhook.
  • N'utilisez pas votre projet Google Cloud de production ni son client OAuth 2.0 pour les tests, car les modifications apportées à ce projet affectent directement votre application de production.
  • Développez et testez d'abord dans un projet hors production, puis appliquez vos modifications à votre projet de production lorsque vous êtes prêt.
  • Utilisez des tags dans la console Google Cloud pour distinguer visuellement vos projets par environnement. Pour en savoir plus, consultez Désigner des environnements de projet avec des tags.

Ajouter des utilisateurs de test

Par défaut, les clients OAuth nouvellement créés sont dans un état non validé et sont limités à 100 utilisateurs à des fins de test et de production. Pour activer l'autorisation pendant cette période, vous devez ajouter manuellement l'adresse e-mail de chaque utilisateur à la liste des utilisateurs de test dans la configuration de votre projet.

Mettez à jour la liste des utilisateurs de test sur la page Audience :

  1. Sur cette page, vous devriez voir l'état de publication défini sur Test et le type d'utilisateur défini sur Externe.
  2. Dans la section "Test users" (Utilisateurs de test), cliquez sur + Add users (+ Ajouter des utilisateurs). Saisissez l'adresse e-mail des utilisateurs de test qui doivent être autorisés à accorder à votre application l'autorisation d'accéder à leurs données de santé.
  3. Cliquez sur Enregistrer.

Pour prendre en charge plus de 100 utilisateurs avec l'API Google Health, vous devez effectuer un examen de sécurité par un tiers. Pour en savoir plus, consultez le Centre d'aide sur la validation des applications OAuth.

Ajouter des niveaux d'accès

Vous devez spécifier les niveaux d'accès que votre client est autorisé à appeler sur la page Accès aux données :

  1. Sur cette page, cliquez sur Ajouter ou supprimer des niveaux d'accès.
  2. Dans la colonne "API", recherchez "API Google Health". Sélectionnez les niveaux d'accès dont vous avez besoin pour votre application.
  3. Après avoir sélectionné tous les niveaux d'accès dont vous avez besoin, cliquez sur Mettre à jour pour revenir à la page "Accès aux données".
  4. Cliquez sur Enregistrer.

Avant de sélectionner vos niveaux d'accès, consultez l'implémentation des niveaux d'accès.

Vous avez terminé de configurer votre ID client et devriez maintenant pouvoir effectuer des appels à l'API Google Health.

Mettre à jour les niveaux d'accès

Vous pouvez inviter l'utilisateur à réautoriser votre application en définissant le paramètre "prompt" sur "consent" dans votre demande d'authentification. Lorsque prompt=consent est inclus, l'écran de consentement s'affiche chaque fois que votre application demande l'autorisation des niveaux d'accès, même si tous les niveaux ont déjà été accordés à votre projet Google APIs.

Pour ajouter ou modifier des niveaux d'accès à l'aide du paramètre prompt=consent, procédez comme suit :

  1. Identifiez la liste complète des scopes dont votre application a besoin. Cela doit inclure les niveaux d'accès existants et tous ceux que vous devez ajouter.

  2. Modifiez le paramètre "scope" dans l'URL d'autorisation pour inclure la liste mise à jour des valeurs de portée séparées par des espaces.

  3. Ajoutez prompt=consent à vos paramètres d'URI d'authentification. Cela oblige le serveur d'autorisation à demander le consentement de l'utilisateur avant de renvoyer des informations à votre client.

    L'exemple suivant montre une requête GET HTTPS au point de terminaison d'autorisation OAuth 2.0 de Google demandant plusieurs niveaux d'accès avec prompt=consent ajouté :

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Lorsque l'utilisateur suit le lien mis à jour, une page de consentement listant tous les niveaux d'accès demandés s'affiche. Une fois que l'utilisateur a cliqué sur "Continuer" ou "Autoriser", vous recevrez un nouveau code d'autorisation qui pourra être échangé contre des jetons couvrant l'ensemble des niveaux d'accès.

    N'incluez prompt=consent que lorsque cela est nécessaire, par exemple lorsque vous devez obtenir un nouveau jeton d'actualisation ou lorsque les niveaux d'accès demandés ont changé.

Bibliothèques clientes OAuth2

La liste des bibliothèques clientes OAuth2 disponibles utilisées pour l'intégration aux frameworks populaires est disponible sur la page Utiliser OAuth 2.0 pour accéder aux API Google.

Lorsque vous implémentez Google OAuth dans des applications mobiles ou de bureau, utilisez toujours des navigateurs système (tels que les onglets personnalisés Chrome sur Android ou ASWebAuthenticationSession sur iOS). N'utilisez jamais de composants WebView intégrés, qui bloquent les clés d'accès et interrompent les flux Google OAuth. Consultez les bonnes pratiques de connexion avec Google pour obtenir des conseils.

Avant qu'un utilisateur ne suive le flux de consentement Google OAuth 2.0 dans votre application, il doit se connecter à l'application mobile Google Health pour associer Google Health à son compte Google. Google OAuth 2.0 authentifie tout compte Google valide et ne peut pas vérifier si le compte dispose d'un profil Google Health actif sur l'écran de consentement.

Demandez aux utilisateurs de suivre les étapes ci-dessous dans l'application mobile Google Health avant de lancer le flux de consentement OAuth dans votre application :

  1. Téléchargez et ouvrez l'application mobile Google Health depuis le Google Play Store ou l'App Store d'Apple.
  2. Appuyez sur Se connecter avec Google, puis sélectionnez le compte Google qu'ils souhaitent associer à votre application.
  3. Suivez les instructions dans l'application pour créer un profil Google Health ou suivez la procédure de migration de compte Fitbit pour migrer un compte Fitbit existant vers votre compte Google.

Après avoir échangé le code d'autorisation contre des jetons OAuth, appelez le point de terminaison users.getIdentity (GET https://health.googleapis.com/v4/users/me/identity) pour vérifier que le compte Google de l'utilisateur est associé à Google Health avant de marquer le compte comme connecté dans votre application. Pour en savoir plus sur la gestion des comptes non associés (400 ACCOUNT_NOT_LINKED), consultez Gérer les comptes Google non associés.

Jetons d'actualisation

Pour conserver un accès à long terme aux API Google sans nécessiter une réauthentification constante de l'utilisateur, votre application doit utiliser un jeton d'actualisation. Pour obtenir des informations détaillées sur l'implémentation, y compris les requêtes HTTP et les paramètres spécifiques requis, consultez la documentation Google Identity Platform.

Pour échanger un jeton d'actualisation contre un jeton d'accès, effectuez un appel HTTPS POST au point de terminaison de jeton Google OAuth 2.0. L'extrait suivant montre un exemple de requête et de réponse :

Requête

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Réponse

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Quand actualiser un jeton

Actualisez les jetons d'actualisation à la demande dans le cadre de la progression naturelle d'une session active d'un utilisateur lorsque les jetons d'accès ont expiré ou sont sur le point d'expirer. Évitez d'actualiser les jetons par lots (par exemple, en utilisant un job ou un service cron planifié pour actualiser les jetons de tous les utilisateurs à une heure fixe).

Nous vous déconseillons d'actualiser les jetons par lots pour les raisons suivantes :

  • L'actualisation par lot empêche d'aligner les mises à jour des jetons sur les modèles de synchronisation des utilisateurs actifs. Vous pouvez utiliser l'appel Get Devices pour afficher la dernière heure de synchronisation d'un utilisateur, mais cela nécessite un niveau d'accès OAuth supplémentaire que les utilisateurs ne sont pas tenus d'approuver.
  • Le traitement par lot met à jour les jetons qui n'ont pas besoin d'être actualisés, ce qui entraîne une surcharge de traitement redondante pour vos systèmes et les serveurs de Google.
  • Si un problème de réseau ou une panne de serveur se produit lors d'une actualisation par lot, tous les jetons utilisateur concernés sont affectés en même temps. L'actualisation individuelle des jetons lors de la progression naturelle des synchronisations d'utilisateurs isole l'impact des échecs temporaires sur un seul utilisateur.
  • Il est plus difficile de diagnostiquer les problèmes avec les jobs par lot. Étant donné que les requêtes par lot sont moins fréquentes et génèrent un grand nombre d'entrées de journal en même temps, il est plus difficile de déterminer le début d'un incident.
  • Les pics de concurrence élevée dans les demandes de jetons lors des exécutions par lot augmentent la probabilité d'atteindre les limites de débit ou de rencontrer des erreurs d'authentification intermittentes.

Comportement des jetons pendant les tests

Tenez compte du comportement des jetons d'actualisation en fonction de l'état de publication de votre projet Google Cloud :

  • Mode Test : si l'état de publication de votre écran de consentement OAuth est défini sur "Test", les jetons d'actualisation émis sont basés sur le temps et expirent au bout de sept jours. Pendant cette période, vous recevrez un seul jeton d'actualisation qui restera valide et utilisable pour obtenir de nouveaux jetons d'accès jusqu'à sa date d'expiration.
  • Mode publié : une fois que votre application est passée à l'état "En production", les jetons d'actualisation n'expirent généralement pas, sauf s'ils sont révoqués ou restent inutilisés pendant une période prolongée (généralement six mois).

Pour une expérience utilisateur fluide, assurez-vous de publier votre application avant de la déplacer dans un environnement de production afin d'éviter l'expiration des jetons au bout de 7 jours.

Générer des exemples de données

Google ne fournit pas d'échantillons ni de données de santé fictives préremplies. Pour tester votre intégration, vous devez générer vos propres données de test. Utilisez l'une des méthodes suivantes pour générer des exemples de données pour vos utilisateurs de test :

  • Portez un bracelet d'activité : portez un bracelet d'activité Fitbit, une Pixel Watch ou une autre montre connectée compatible avec l'application Google Health et marchez pour générer des données sur les pas, la fréquence cardiaque et les entraînements.
  • Activez le suivi mobile : activez MobileTrack dans l'application Google Health et déplacez-vous avec votre appareil mobile.
  • Enregistrer des données manuellement : saisissez manuellement des métriques de santé (comme le sommeil, le poids, la consommation d'eau ou l'apport alimentaire) dans l'application Google Health.
  • Écrire des données à l'aide de l'API : envoyez des requêtes d'écriture (telles que POST ou PATCH) directement aux points de terminaison de l'API REST pour remplir les données de manière programmatique. Pour en savoir plus sur la création et la mise à jour de points de données, consultez la documentation de référence REST.

Protection multicompte (API RISC)

Activez le partage et la coordination des risques et des incidents (RISC) si vous souhaitez être averti des modifications apportées aux jetons d'événement ou à l'association de comptes, comme les comptes dissociés ou les jetons révoqués, afin de nettoyer les jetons stockés et de mettre à jour l'état de connexion de l'UI. L'activation de l'API RISC est facultative.

Pour activer l'API RISC pour votre projet Google Cloud :

  1. Ouvrez la page API RISC dans la console Google Cloud. Assurez-vous que le projet que vous utilisez pour l'API Google Health est sélectionné.
  2. Lisez les Conditions d'utilisation de RISC et assurez-vous de comprendre les exigences.
  3. Si vous acceptez les conditions, cliquez sur Activer.

Après avoir activé l'API, vous devez créer et enregistrer un point de terminaison HTTPS pour recevoir et valider les jetons d'événement envoyés par Google.

Pour en savoir plus sur la protection multicompte et RISC, consultez Protéger les comptes utilisateur avec la protection multicompte.