Gestion des données dans l'API Google Health

L'utilisation des données dans l'API Google Health est avant tout un cycle de synchronisation des données entre le datastore de l'API Google Health dans le cloud et le datastore de votre propre application ou backend. Toutefois, ce cycle peut prendre différentes formes en fonction de plusieurs facteurs :

• Écrivez-vous des données dans l'API Google Health ? Ou effectuez-vous uniquement des lectures ? Ou les deux ?
• Votre datastore est-il local sur l'application ou l'appareil ? Ou dans votre propre cloud ?
• Devez-vous synchroniser les données de l'API Google Health entre l'application de l'utilisateur et un accessoire connecté ? À quelle fréquence synchronisez-vous les appareils ?
• Avec quels types de données travaillez-vous ? Des décomptes de base ? Des unités de mesure ? Des séries avec différents taux d'échantillonnage ?
• Prévoyez-vous de lire des données lorsque votre application est exécutée en arrière-plan ?
• Prévoyez-vous d'utiliser des données historiques enregistrées avant que votre application ne reçoive les autorisations de l'utilisateur ?

Pour comprendre comment tout cela s'articule, consultez le cycle de vie de la synchronisation de l'API Google Health. Il existe deux versions de ce cycle de vie : standard (lecture et écriture) et lecture seule.

Cycle de vie de la synchronisation standard

Figure 1 : Cycle de vie de la synchronisation standard dans l'API Google Health

L'intégration à l'API Google Health implique la copie de données dans un datastore d'application ou de backend. Pour faciliter l'utilisation de cette documentation, nous appellerons ce datastore le datastore du développeur.

Le terme "copie" peut ici remplacer n'importe quelle activité discrète, comme la lecture à partir de l'API Google Health (copie dans le datastore du développeur) ou l'écriture dans l'API Google Health (copie dans l'API Google Health). L'exécution répétée de ces actions dans un ordre spécifique constitue le cycle de vie de la synchronisation.

La figure 1 illustre le cycle de vie de la synchronisation standard qui implique des opérations de lecture et d'écriture, sans tenir compte des facteurs mentionnés précédemment.

Écriture

1. Préparer de nouvelles données pour l'écriture : transférez les données d'un appareil ou d'une application externe, puis mettez en forme les points de données dans des représentations JSON compatibles avec les types de données de l'API Google Health. Notez que les ID personnalisés attribués par le client pour les écritures ne sont pas compatibles avec l'API Health pour le moment. Ces ID peuvent être fournis dans une requête POST, mais ils sont ignorés.
2. Insérer ou mettre à jour des enregistrements : envoyez des points de données à l'API Google Health à l'aide de points de terminaison REST. Utilisez POST pour créer des enregistrements et PATCH pour insérer et mettre à jour des enregistrements existants. Les ID nécessaires à l'opération PATCH proviendront d'une opération POST précédente (étape suivante d'un cycle précédent).
3. Traiter les ID de ressource renvoyés : lorsque vous utilisez des ID générés par le serveur, extrayez et conservez le name ou l'ID de ressource renvoyé par le serveur dans votre datastore de développeur pour permettre de futures mises à jour (PATCH) ou suppressions (DELETE). Pour en savoir plus sur les deux types, consultez Stratégies d'identification.

Lecture

1. Lire les enregistrements : récupérez de nouvelles données et des modifications apportées aux données existantes dans l'API Google Health à l'aide de points de terminaison REST (GET avec des paramètres de requête filter et une pagination pageToken, ou des points de terminaison d'agrégation tels que rollUp et dailyRollUp), ou recevez des notifications en temps réel à l'aide d'abonnements Webhook (projects.subscribers). Une notification indique uniquement que de nouvelles données sont disponibles, et non la nature des données.
2. Réconcilier le datastore du développeur : réconciliez les données nouvelles et mises à jour avec votre datastore de développeur.

Ce cycle se répète ensuite à intervalles appropriés en fonction des besoins spécifiques des appareils ou applications externes. Il s'agit généralement de l'ordre que nous recommandons pour synchroniser les données entre votre propre datastore et l'API Google Health.

Stratégies d'identification

Si vous prévoyez d'écrire des données dans l'API Google Health, avant de créer votre intégration avec les API Google Health, vous devez choisir une stratégie d'identification des ressources lors de la création de points de données (unité de données de base).

Les ID attribués par le client pour les écritures ne sont pas compatibles avec l'API Health pour le moment. Ces ID peuvent être fournis dans une requête POST, mais ils sont ignorés. Des informations sur cette option sont fournies ici à titre informatif.

1. ID générés par le serveur (option par défaut) : le client envoie des données sans ID, et le backend de l'API Google Health génère et renvoie un identifiant système unique.
2. ID personnalisés attribués par le client (per AIP-133, non compatible pour le moment): l'application cliente génère un identifiant unique (par exemple, une clé primaire UUID ou de base de données locale) et le fournit dans le chemin d'accès à la ressource lors de la création.

Le tableau suivant compare les deux stratégies d'identification pour vous aider à choisir l'approche adaptée à votre intégration :

Fonctionnalité	ID générés par le serveur	ID personnalisés attribués par le client
Génération d'ID	Le serveur génère un ID système aléatoire lors de POST exécution.	Le client génère un ID stable localement (UUID v4 / clé primaire interne) avant l'écriture.
Chemin d'accès à la ressource	.../dataPoints/{server_id} (renvoyé dans la réponse)	.../dataPoints/{custom_id}
Étape locale après l'écriture	Obligatoire. Vous devez stocker le server_id renvoyé dans la base de données locale pour permettre de futures mises à jour/suppressions.	Aucune. L'application possède déjà l'ID.
Table de mappage des ID	Obligatoire. Le client doit maintenir un mappage bidirectionnel (local_id ↔ server_id).	Non nécessaire. Le client utilise directement sa propre clé primaire.
Comportement en cas de nouvelle tentative (réseau faible)	Risque de doublons. Une nouvelle tentative d'exécution d'une requête POST ayant expiré crée un enregistrement en double avec un nouvel ID de serveur.	Sûr et idempotent. Une nouvelle tentative d'exécution de POST avec le même custom_id empêche la création de doublons (renvoie 409 ALREADY_EXISTS).
Compatibilité avec la synchronisation hors connexion	Limitée. Vous devez attendre la réponse du serveur pour obtenir les ID de ressource officiels avant de les référencer.	Complète. Les entités peuvent être créées et modifiées hors connexion avec des ID stables puis synchronisées de manière transparente une fois la connexion rétablie.
Contraintes de format	Entièrement gérées par le serveur.	Doit suivre ^[a-z0-9-]{4,63}$ (4 à 63 caractères alphanumériques minuscules et tirets).
Quand choisir	Choisissez des ID générés par le serveur si : Votre application est en écriture seule / ajout seul (par exemple, envoi de données de télémétrie ou de décomptes de pas qui ne sont jamais mis à jour ni supprimés ultérieurement). Votre application ne gère pas de base de données persistante locale de points de données individuels. Vous préférez la simplicité sans gérer les contraintes de validation de chaîne (telles que 4-63 caractères).	Choisissez des ID personnalisés si : Vous utilisez une application de synchronisation bidirectionnelle qui lit, écrit et met à jour les dossiers médicaux sur tous les appareils. Votre application dispose d'une base de données locale (telle que Room ou SQLite) stockant des enregistrements avec des clés primaires locales. Vos utilisateurs enregistrent des données hors connexion ou via des connexions mobiles intermittentes où des nouvelles tentatives sécurisées sont nécessaires. Vous souhaitez éliminer les tables de mappage des ID entre votre base de données backend et l'API.

Cycle de vie de la synchronisation en lecture seule

Figure 2 : Cycle de vie de la synchronisation en lecture seule dans l'API Google Health

Une application qui ne prévoit de lire que des données à partir de l'API Google Health doit copier les données dans son datastore de développeur et gérer la partie réconciliation du cycle de vie.

Les mêmes tâches que celles décrites dans la section Lecture s'appliquent ici.

La figure 2 illustre le cycle de vie en lecture seule.