L'utilisation des données dans l'API Google Health consiste essentiellement à synchroniser les données entre le datastore de l'API Google Health dans le cloud et votre propre application ou datastore de backend. Toutefois, ce cycle peut prendre différentes formes en fonction de plusieurs facteurs :
- Écrivez-vous des données dans l'API Google Health ? Vous voulez juste lire ? Ou les deux ?
- Votre datastore est-il local sur l'application ou l'appareil ? Ou dans votre propre cloud ?
- Avez-vous besoin de 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 ? Unités de mesure ? Séries avec des taux d'échantillonnage différents ?
- Prévoyez-vous de lire des données lorsque votre application est 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
L'intégration à l'API Google Health implique de copier des données dans une application ou un datastore de backend. Pour faciliter l'utilisation de cette documentation, nous appellerons ce datastore le datastore du développeur.
Ici, le terme "copie" peut remplacer n'importe quelle activité distincte, 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 synchronisation standard qui implique des opérations de lecture et d'écriture, sans tenir compte des facteurs mentionnés précédemment.
Écriture
- Préparer de nouvelles données pour l'écriture : transférez des données depuis un appareil ou une application externe, et formatez les points de données en 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 acceptés dans l'API Health pour le moment. Ces ID peuvent être fournis dans un
POST, mais ils sont ignorés. - Faire un upsert d'enregistrements : envoyez des points de données à l'API Google Health à l'aide de points de terminaison REST. Utilisez
POSTpour créer des enregistrements, etPATCHpour insérer et mettre à jour des enregistrements existants. Les ID nécessaires à l'opérationPATCHproviennent d'une opérationPOSTprécédente (étape suivante d'un cycle précédent). - Traiter les ID de ressources renvoyés : lorsque vous utilisez des ID générés par le serveur, extrayez et conservez l'ID ou la ressource
namerenvoyé par le serveur dans votre datastore de développeur pour permettre les futures mises à jour (PATCH) ou suppressions (DELETE). Pour en savoir plus sur les deux types, consultez Stratégies d'identification.
Lecture
- Lire des 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 (
GETavec les paramètres de requêtefilteret la paginationpageToken, ou des points de terminaison d'agrégation commerollUpetdailyRollUp), ou recevez des notifications à l'aide d'abonnements Webhook (projects.subscribers). Une notification indique uniquement que de nouvelles données sont disponibles, et non de quelles données il s'agit. - Rapprocher le datastore du développeur : rapprochez les données nouvelles et mises à jour de votre datastore de développeur. Les appareils connectés peuvent produire des intervalles qui se chevauchent lors des synchronisations. Pour savoir comment l'API Google Health les résout, consultez Codes temporels d'intervalle et synchronisation des appareils connectés.
Ce cycle se répète ensuite à des intervalles appropriés en fonction des besoins spécifiques des appareils ou des 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 avez l'intention 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 (l'unité de données de base).
Pour le moment, l'API Health ne prend pas en charge les ID attribués par le client pour les écritures.
Ces ID peuvent être fournis dans un POST, mais ils sont ignorés. Les détails de cette option sont fournis ici à titre d'information.
- 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.
- ID personnalisés attribués par le client (conformément à la norme AIP-133, pas encore compatible) : l'application cliente génère un identifiant unique (par exemple, un UUID ou une clé primaire 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 l'exécution de POST. |
Le client génère un ID stable localement (UUID v4/PK interne) avant l'écriture. |
| Chemin de la ressource | .../dataPoints/{server_id} (renvoyé dans la réponse) |
.../dataPoints/{custom_id} |
| Étape locale après l'écriture | Obligatoire. Vous devez stocker l'élément server_id renvoyé dans la base de données locale pour permettre les futures mises à jour/suppressions. |
Aucun : L'application possède déjà l'ID. |
| Table de mappage d'ID | Obligatoire. Le client doit maintenir un mappage bidirectionnel (local_id ↔ server_id). |
Non. Le client utilise directement sa propre clé primaire. |
| Comportement de nouvelle tentative (réseau faible) | Risque de doublons. Si vous relancez une requête POST ayant expiré, un enregistrement en double est créé avec un nouvel ID de serveur. |
Sûr et idempotent. Si vous relancez POST avec le même custom_id, vous évitez 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 ressources officiels avant de les référencer. | Full. Les entités peuvent être créées et modifiées hors connexion avec des ID stables, puis synchronisées de manière fluide une fois la connexion rétablie. |
| Contraintes de format | Entièrement géré par le serveur. | Doit respecter le format ^[a-z0-9-]{4,63}$ (4 à 63 caractères alphanumériques minuscules et traits d'union). |
| Quand choisir |
Choisissez des ID générés par le serveur si :
|
Choisissez des ID personnalisés si :
|
Cycle de vie de la synchronisation en lecture seule
Une application qui n'a l'intention que de lire 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 rapprochement du cycle de vie.
Les mêmes tâches que celles décrites dans la section Lire s'appliquent ici.
La figure 2 illustre le cycle de vie en lecture seule.
Codes temporels des intervalles et synchronisation des appareils connectés
Les données d'intervalle représentent les mesures collectées sur une période donnée, comme les pas, la fréquence cardiaque ou les séances d'exercice. En revanche, les mesures ponctuelles incluent les entrées manuelles, comme un journal alimentaire ou une lecture de balance. Les données d'intervalle proviennent généralement de la synchronisation d'appareils connectés, tels que les montres connectées et les bracelets d'activité.
Les codes temporels d'intervalle (startTime et endTime dans les charges utiles JSON REST, ou start_time et end_time dans les expressions de filtre et gRPC) introduisent des comportements uniques lorsque vous travaillez avec des données d'intervalle. Cette section explique pourquoi des intervalles qui se chevauchent se produisent et compare les points de terminaison list et reconcile.
Intervalles qui se chevauchent sur les appareils connectés
Les appareils connectés tels que les bracelets d'activité Fitbit et la Google Pixel Watch collectent en continu des mesures biométriques à haute fréquence lorsqu'ils sont portés. Une fois qu'un appareil a synchronisé des points de données avec Google Health, il ne modifie pas rétroactivement ces enregistrements existants. Les codes temporels d'intervalle stockés restent inchangés.
Toutefois, avant les cycles de synchronisation suivants, les algorithmes sur l'appareil réinterprètent souvent la télémétrie brute des capteurs. L'appareil regroupe les relevés collectés au cours des heures précédentes. Lorsque l'appareil se synchronise à nouveau, il importe de nouveaux points de données. Leurs limites de début et de fin peuvent chevaucher des intervalles précédemment stockés.
Par exemple, prenons le cas d'un utilisateur portant une montre connectée dont les données d'activité sont synchronisées en deux lots consécutifs :
- Lors de la première synchronisation, l'appareil importe un point de données couvrant la période du
10:00:00Zau10:14:59Z. - Après un nouveau calcul sur l'appareil, une deuxième synchronisation importe un autre point de données couvrant la période de
10:14:00Zà10:28:59Z.
Les deux enregistrements sont stockés indépendamment dans le backend Google Health. Par conséquent, les deux points de données couvrent l'intervalle de 10:14:00Z à 10:14:59Z.
Cela produit un chevauchement de 59 secondes lors de l'interrogation des enregistrements bruts.
Comparer les points de terminaison de liste et de rapprochement
Vous pouvez gérer ces intervalles qui se chevauchent à l'aide du point de terminaison list ou reconcile. Choisissez le point de terminaison qui correspond aux exigences de votre application :
| Fonctionnalité | list point de terminaison |
reconcile point de terminaison |
|---|---|---|
| Méthode HTTP | GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile |
| Comportement de chevauchement | Renvoie tous les enregistrements stockés tels qu'ils ont été importés, sans déduplication. Lorsque les intervalles se chevauchent, les deux enregistrements sont renvoyés. | Résout les conflits et déduplique les enregistrements qui se chevauchent sur les appareils et les sessions de synchronisation en un seul flux continu. |
| Avantages | Fournit une piste d'audit complète et non modifiée de chaque enregistrement importé par chaque appareil et lot de synchronisation. | Simplifie l'affichage de la chronologie et le calcul de la durée en gérant automatiquement les intervalles qui se chevauchent et les conflits entre plusieurs appareils. |
| Inconvénients | Votre application est chargée de détecter et de résoudre les intervalles qui se chevauchent, les conflits entre plusieurs appareils et les périodes où l'appareil n'est pas porté au poignet. | Les enregistrements subordonnés qui se chevauchent sont omis de la réponse. Par conséquent, les lots de synchronisation d'appareils individuels ne peuvent pas être audités de manière isolée. |
Le point de terminaison reconcile est conçu pour dessiner des interfaces utilisateur, afficher des chronologies d'activité et calculer des totaux de durée sans chevauchement. Il résout les conflits d'intervalles des sessions de synchronisation reclassées. Elle rapproche également l'activité enregistrée simultanément sur plusieurs appareils, comme une montre et un téléphone.
Le rapprochement résout les conflits de sessions en sélectionnant l'enregistrement faisant autorité plutôt qu'en synthétisant une union temporelle artificielle. Par exemple, il ne fusionne pas 11:00:00Z vers 11:30:00Z et 11:20:00Z vers 11:50:00Z en 11:00:00Z vers 11:50:00Z. La réponse rapprochée renvoie le point de données gagnant avec son intervalle d'enregistrement d'origine. Cela préserve l'intégrité de la télémétrie et des métriques mesurées de cette session.
La figure 3 illustre la manière dont le point de terminaison reconcile gère les sessions qui se chevauchent.
Il sélectionne l'enregistrement de référence plutôt que de créer une union temporelle artificielle.
Le guide Endpoints fournit des exemples complets de requêtes et de réponses. Pour comparer les enregistrements list bruts avec la sortie reconcile, consultez Obtenir une vue rapprochée des données d'intervalle.
Le point de terminaison list est conçu pour les diagnostics d'appareils et les audits de données. Utilisez-le lorsque votre workflow nécessite d'inspecter les enregistrements non modifiés tels qu'ils ont été importés par chaque appareil. Lorsque vous effectuez une requête avec list, votre logique client doit gérer les chevauchements d'intervalles dans les données brutes.
Mutabilité des codes temporels et mises à jour du propriétaire
Les appareils connectés ne modifient pas rétroactivement les codes temporels stockés lors des cycles de synchronisation normaux. Toutefois, les codes temporels d'intervalle (startTime et endTime dans les charges utiles JSON REST, ou start_time et end_time dans les expressions de filtre et gRPC) ne sont pas universellement immuables dans toutes les sources de données. Seul le créateur ou le propriétaire d'origine d'un enregistrement peut modifier ses champs. Les autres applications ne peuvent pas modifier les points de données qu'elles n'ont pas créés.
Une application propriétaire peut utiliser le point de terminaison patch pour mettre à jour ses enregistrements existants. Cela inclut la modification des codes temporels de début ou de fin, qui met à jour les champs UTC (startTime et endTime) et d'heure civile (civilStartTime et civilEndTime) sur le serveur. Pour obtenir un exemple de mise à jour des codes temporels avec PATCH, consultez Mettre à jour les codes temporels d'intervalle pour les données existantes dans le guide Endpoints.
De même, les points de données synchronisés à partir de plates-formes externes telles que Santé Connect ou des applications partenaires héritent des mises à jour de la source d'origine. Si Santé Connect reçoit par la suite une mise à jour d'un enregistrement synchronisé de l'application tierce d'origine, ces modifications sont propagées et écrasent l'enregistrement existant.