Die Arbeit mit Daten in der Google Health API ist im Wesentlichen ein Zyklus, bei dem Daten zwischen dem Google Health API-Datenspeicher in der Cloud und Ihrer eigenen App oder Ihrem Backend-Datenspeicher synchronisiert werden. Dieser Zyklus kann jedoch je nach einer Vielzahl von Faktoren unterschiedliche Formen annehmen:
- Schreiben Sie Daten in die Google Health API? Lesezugriff? Oder beides?
- Ist Ihr Datenspeicher lokal in der App oder auf dem Gerät? Oder in Ihrer eigenen Cloud?
- Müssen Sie Google Health API-Daten zwischen der App des Nutzers und einem Wearable synchronisieren? Wie oft synchronisierst du Geräte?
- Mit welchen Datentypen arbeiten Sie? Grundlegende Zählungen? Maßeinheiten? Reihen mit unterschiedlichen Abtastraten?
- Haben Sie vor, Daten zu lesen, während Ihre App im Hintergrund ausgeführt wird?
- Möchten Sie mit Verlaufsdaten arbeiten, die aufgezeichnet wurden, bevor Ihre App Nutzerberechtigungen erhalten hat?
Sehen Sie sich den Synchronisierungslebenszyklus der Google Health API an, um zu verstehen, wie das alles zusammenpasst. Es gibt zwei Versionen dieses Lebenszyklus: Standard (Lesen und Schreiben) und Lesezugriff.
Der standardmäßige Synchronisierungslebenszyklus
Die Einbindung der Google Health API bedeutet, dass Daten in eine App oder einen Backend-Datenspeicher kopiert werden. Der Einfachheit halber wird dieser Datastore in dieser Dokumentation als Entwickler-Datastore bezeichnet.
„Kopieren“ kann hier für jede einzelne Aktivität stehen, z. B. das Lesen aus der Google Health API (Kopieren in den Entwicklerdatenspeicher) oder das Schreiben in die Google Health API (Kopieren in die Google Health API). Die wiederholte Ausführung dieser Aktionen in einer bestimmten Reihenfolge wird als Synchronisierungslebenszyklus bezeichnet.
Abbildung 1 zeigt den standardmäßigen Synchronisierungslebenszyklus mit Lese- und Schreibvorgängen, ohne Berücksichtigung der zuvor genannten Faktoren.
Schreiben
- Neue Daten zum Schreiben vorbereiten: Daten von einem externen Gerät oder einer externen App übertragen und Datenpunkte in JSON-Darstellungen formatieren, die mit den Datentypen der Google Health API kompatibel sind. Benutzerdefinierte, vom Client zugewiesene IDs für Schreibvorgänge werden derzeit in der Health API nicht unterstützt. Solche IDs können in einer
POSTangegeben werden, werden aber ignoriert. - Upsert-Datensätze: Datenpunkte über REST-Endpunkte an die Google Health API senden. Verwenden Sie
POSTzum Erstellen von Datensätzen undPATCHzum Einfügen und Aktualisieren vorhandener Datensätze. Die für den VorgangPATCHerforderlichen IDs stammen aus einem vorherigenPOST-Vorgang (nächster Schritt in einem vorherigen Zyklus). - Zurückgegebene Ressourcen-IDs verarbeiten: Wenn Sie vom Server generierte IDs verwenden, extrahieren und speichern Sie die vom Server zurückgegebene Ressource
nameoder ID in Ihrem Entwicklerdatenspeicher, um zukünftige Aktualisierungen (PATCH) oder Löschungen (DELETE) zu ermöglichen. Weitere Informationen zu den beiden Typen finden Sie unter Identifikationsstrategien.
Lesen
- Datensätze lesen: Neue Daten und Änderungen an vorhandenen Daten in der Google Health API über REST-Endpunkte (
GETmitfilter-Abfrageparametern undpageToken-Paginierung oder Aggregationsendpunkte wierollUpunddailyRollUp) abrufen oder Benachrichtigungen über Webhook-Abos (projects.subscribers) erhalten. Eine Benachrichtigung gibt nur an, dass neue Daten verfügbar sind, nicht, um welche Daten es sich handelt. - Entwickler-Datenspeicher abgleichen: Gleichen Sie die neuen und aktualisierten Daten mit Ihrem Entwickler-Datenspeicher ab. Verbundene Geräte können bei der Synchronisierung überlappende Intervalle erzeugen. Informationen dazu, wie die Google Health API diese Probleme löst, findest du unter Intervallzeitstempel und Synchronisierung verbundener Geräte.
Dieser Zyklus wird dann in geeigneten Intervallen wiederholt, je nach den spezifischen Anforderungen externer Geräte oder Apps. Dies ist im Allgemeinen die Reihenfolge, die wir für die Synchronisierung von Daten zwischen Ihrem eigenen Datenspeicher und der Google Health API empfehlen.
Identifikationsstrategien
Wenn du Daten in die Google Health API schreiben möchtest, musst du vor dem Erstellen deiner Integration mit den Google Health APIs eine Strategie zur Ressourcenidentifikation auswählen, wenn du Datenpunkte (die grundlegende Dateneinheit) erstellst.
Vom Client zugewiesene IDs für Schreibvorgänge werden in der Health API derzeit nicht unterstützt.
Solche IDs können in einem POST angegeben werden, werden aber ignoriert. Details zu dieser Option werden hier zu Informationszwecken bereitgestellt.
- Vom Server generierte IDs (Standardoption): Der Client sendet Daten ohne ID und das Google Health API-Backend generiert eine eindeutige Systemkennung und gibt sie zurück.
- Vom Client zugewiesene benutzerdefinierte IDs (gemäß AIP-133, noch nicht unterstützt): Die Client-Anwendung generiert eine eindeutige Kennung (z. B. eine UUID oder einen Primärschlüssel der lokalen Datenbank) und gibt sie beim Erstellen im Ressourcenpfad an.
In der folgenden Tabelle werden beide Identifikationsstrategien verglichen, damit Sie den richtigen Ansatz für Ihre Integration auswählen können:
| Funktion | Vom Server generierte IDs | Vom Kunden zugewiesene benutzerdefinierte IDs |
|---|---|---|
| ID-Generierung | Der Server generiert während der Ausführung von POST eine zufällige System-ID. |
Der Client generiert vor dem Schreiben lokal eine stabile ID (UUID v4 / interner PK). |
| Ressourcenpfad | .../dataPoints/{server_id} (in Antwort zurückgegeben) |
.../dataPoints/{custom_id} |
| Lokaler Schritt nach dem Schreiben | Erforderlich. Die zurückgegebene server_id muss in der lokalen Datenbank gespeichert werden, um zukünftige Aktualisierungen/Löschungen zu ermöglichen. |
Keine. Die App hat die ID bereits. |
| ID-Zuordnungstabelle | Erforderlich. Der Client muss eine bidirektionale Zuordnung (local_id ↔ server_id) beibehalten. |
Nicht erforderlich. Der Client verwendet seinen eigenen Primärschlüssel direkt. |
| Wiederholungsverhalten (schwaches Netzwerk) | Risiko von Duplikaten: Wenn Sie einen POST-Vorgang mit Zeitüberschreitung wiederholen, wird ein doppelter Eintrag mit einer neuen Server-ID erstellt. |
Sicher und idempotent. Wenn Sie POST mit derselben custom_id wiederholen, wird eine doppelte Erstellung verhindert (409
ALREADY_EXISTS wird zurückgegeben). |
| Unterstützung für die Offlinesynchronisierung | Eingeschränkt: Sie müssen auf die Serverantwort warten, um offizielle Ressourcen-IDs zu erhalten, bevor Sie auf sie verweisen können. | Voll. Entitäten können offline mit stabilen IDs erstellt und geändert und dann nahtlos synchronisiert werden, wenn die Verbindung wiederhergestellt ist. |
| Beschränkungen bei Formaten | Wird vollständig vom Server verarbeitet. | Muss ^[a-z0-9-]{4,63}$ entsprechen (4–63 alphanumerische Kleinbuchstaben und Bindestriche). |
| Wann Sie sich für diese Option entscheiden sollten |
Wählen Sie vom Server generierte IDs aus, wenn:
|
Wählen Sie benutzerdefinierte IDs aus, wenn:
|
Der schreibgeschützte Synchronisierungslebenszyklus
Eine App, die nur Daten aus der Google Health API lesen soll, muss Daten in ihren Entwicklerdatenspeicher kopieren und den Abgleichsteil des Lebenszyklus verarbeiten.
Hier gelten dieselben Aufgaben wie im Abschnitt Lesen.
Abbildung 2 veranschaulicht den Lebenszyklus mit Lesezugriff.
Intervallzeitstempel und Synchronisierung verbundener Geräte
Intervalldaten sind Messwerte, die über einen bestimmten Zeitraum erfasst werden, z. B. Schritte, Herzfrequenz oder Trainingseinheiten. Im Gegensatz dazu umfassen punktuelle Messungen manuelle Einträge wie ein Ernährungsprotokoll oder einen Messwert von einer Waage. Intervalldaten stammen in der Regel aus der Synchronisierung verbundener Geräte wie Smartwatches und Fitness-Trackern.
Intervallzeitstempel (startTime und endTime in REST-JSON-Nutzlasten oder start_time und end_time in Filterausdrücken und gRPC) führen zu einem einzigartigen Verhalten bei der Arbeit mit Intervalldaten. In diesem Abschnitt wird erläutert, warum sich überschneidende Intervalle auftreten, und die Endpunkte list und reconcile werden verglichen.
Sich überschneidende Intervalle von verbundenen Geräten
Verbundene Geräte wie Fitbit-Tracker und die Google Pixel Watch erfassen kontinuierlich hochfrequente biometrische Messwerte, während sie getragen werden. Nachdem ein Gerät Datenpunkte mit Google Health synchronisiert hat, werden diese vorhandenen Datensätze nicht rückwirkend geändert. Die gespeicherten Intervallzeitstempel bleiben unverändert.
Vor nachfolgenden Synchronisierungszyklen werden die Sensorrohdaten jedoch häufig von Algorithmen auf dem Gerät neu interpretiert. Das Gerät ordnet die in den vorherigen Stunden erfassten Messwerte neu zu. Wenn das Gerät wieder synchronisiert wird, werden neue Datenpunkte hochgeladen. Ihre Start- und Endgrenzen können sich mit zuvor gespeicherten Intervallen überschneiden.
Angenommen, ein Nutzer trägt eine Smartwatch, deren Aktivitätsdaten in zwei aufeinanderfolgenden Batches synchronisiert werden:
- Bei der ersten Synchronisierung lädt das Gerät einen Datenpunkt hoch, der den Zeitraum von
10:00:00Zbis10:14:59Zabdeckt. - Nach der Neuberechnung auf dem Gerät wird bei einer zweiten Synchronisierung ein weiterer Datenpunkt hochgeladen, der den Zeitraum von
10:14:00Zbis10:28:59Zabdeckt.
Beide Datensätze werden unabhängig voneinander im Google Health-Backend gespeichert. Daher decken beide Datenpunkte das Intervall von 10:14:00Z bis 10:14:59Z ab.
Dies führt zu einer Überschneidung von 59 Sekunden bei der Abfrage von Rohdatensätzen.
Listen- und Abgleichsendpunkte vergleichen
Sie können diese sich überschneidenden Intervalle entweder mit dem Endpunkt list oder reconcile verarbeiten. Wählen Sie den Endpunkt aus, der den Anforderungen Ihrer Anwendung entspricht:
| Funktion | list Endpunkt |
reconcile Endpunkt |
|---|---|---|
| HTTP-Methode | GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile |
| Überlappungsverhalten | Gibt alle gespeicherten Datensätze so zurück, wie sie hochgeladen wurden, ohne Deduplizierung. Wenn sich Intervalle überschneiden, werden beide Datensätze zurückgegeben. | Löst Konflikte und entfernt doppelte, sich überschneidende Datensätze auf verschiedenen Geräten und in verschiedenen Synchronisierungssitzungen, um einen einzigen kontinuierlichen Stream zu erstellen. |
| Vorteile | Bietet einen vollständigen, unveränderten Audit-Trail für jeden Datensatz, der von jedem Gerät und Synchronisierungsbatch hochgeladen wurde. | Vereinfacht das Rendern der Zeitachse und die Berechnung der Dauer, indem sich überschneidende Intervalle und Konflikte für verschiedene Geräte automatisch verarbeitet werden. |
| Nachteile | Deine Anwendung ist für die Erkennung und Lösung von überlappenden Intervallen, Konflikten zwischen mehreren Geräten und Zeiträumen, in denen das Gerät nicht am Handgelenk getragen wird, verantwortlich. | Untergeordnete überlappende Datensätze werden in der Antwort weggelassen, sodass einzelne Batches für die Gerätesynchronisierung nicht isoliert geprüft werden können. |
Der Endpunkt reconcile ist für das Zeichnen von Benutzeroberflächen, das Rendern von Aktivitätszeitachsen und das Berechnen von nicht überlappenden Gesamtdauern vorgesehen. Es löst Konflikte zwischen Intervallen aus neu gruppierten Synchronisierungssitzungen. Außerdem werden Aktivitäten abgeglichen, die gleichzeitig auf mehreren Geräten aufgezeichnet wurden, z. B. auf einer Smartwatch und einem Smartphone.
Beim Abgleich werden widersprüchliche Sitzungen aufgelöst, indem der maßgebliche Datensatz ausgewählt wird, anstatt eine künstliche Zeitunion zu erstellen. Beispielsweise werden 11:00:00Z bis 11:30:00Z und 11:20:00Z bis 11:50:00Z nicht zu 11:00:00Z bis 11:50:00Z zusammengeführt. Die abgeglichene Antwort gibt den gewinnenden Datenpunkt mit dem ursprünglich aufgezeichneten Intervall zurück. So bleibt die Integrität der gemessenen Telemetriedaten und Messwerte dieser Sitzung erhalten.
Abbildung 3 zeigt, wie der Endpunkt reconcile mit sich überschneidenden Sitzungen umgeht.
Es wird der autoritative Eintrag ausgewählt, anstatt eine künstliche Zeitunion zu erstellen.
Der Endpoints-Leitfaden enthält vollständige Anfrage- und Antwortbeispiele. Informationen zum Vergleichen von list-Rohdatensätzen mit der reconcile-Ausgabe finden Sie unter Abgeglichene Ansicht von Intervalldaten abrufen.
Der Endpunkt list ist für die Gerätediagnose und Datenprüfungen vorgesehen. Verwenden Sie ihn, wenn Ihr Workflow die Prüfung unveränderter Datensätze erfordert, die von jedem Gerät hochgeladen wurden. Wenn Sie mit list abfragen, muss Ihre Clientlogik alle Intervallüberschneidungen in den Rohdaten verarbeiten.
Änderbarkeit von Zeitstempeln und Aktualisierungen durch Inhaber
Verbundene Geräte ändern gespeicherte Zeitstempel während normaler Synchronisierungszyklen nicht rückwirkend. Intervallzeitstempel (startTime und endTime in REST-JSON-Nutzlasten oder start_time und end_time in Filterausdrücken und gRPC) sind jedoch nicht für alle Datenquellen unveränderlich. Nur der ursprüngliche Ersteller oder Inhaber eines Datensatzes kann seine Felder ändern. Andere Anwendungen können keine Datenpunkte bearbeiten, die sie nicht erstellt haben.
Eine Inhaber-Anwendung kann den patch-Endpunkt verwenden, um ihre vorhandenen Einträge zu aktualisieren. Dazu gehört auch das Ändern von Start- oder Endzeitstempeln, wodurch sowohl die UTC-Felder (startTime und endTime) als auch die Felder für die bürgerliche Zeit (civilStartTime und civilEndTime) auf dem Server aktualisiert werden. Ein Beispiel für das Aktualisieren von Zeitstempeln mit PATCH finden Sie im Endpunkte-Leitfaden unter Intervallzeitstempel für vorhandene Daten aktualisieren.
Datenpunkte, die von externen Plattformen wie Health Connect oder Partner-Apps synchronisiert werden, übernehmen ebenfalls Aktualisierungen von der ursprünglichen Quelle. Wenn Health Connect anschließend ein Update für einen synchronisierten Datensatz von der ursprünglichen Drittanbieter-App erhält, werden diese Änderungen übernommen und der vorhandene Datensatz wird überschrieben.