Die Arbeit mit Daten in der Google Health API ist im Grunde ein Zyklus der Synchronisierung von Daten zwischen dem Google Health API-Datenspeicher in der Cloud und dem Datenspeicher Ihrer eigenen App oder Ihres Backends. Dieser Zyklus kann jedoch je nach verschiedenen Faktoren unterschiedliche Formen annehmen:
- Schreiben Sie Daten in die Google Health API? Nur lesen? Oder beides?
- Ist der Datenspeicher lokal in der App oder auf dem Gerät? Oder in Ihrer eigenen Cloud?
- Müssen Google Health API-Daten zwischen der App des Nutzers und einem Wearable synchronisiert werden? Wie oft synchronisieren Sie Geräte?
- Mit welchen Arten von Daten arbeiten Sie? Grundlegende Zählungen? Maßeinheiten? Serien mit unterschiedlichen Abtastraten?
- Planen Sie, Daten zu lesen, während Ihre App im Hintergrund ausgeführt wird?
- Planen Sie, mit Verlaufsdaten zu arbeiten, die vor der Erteilung von Nutzerberechtigungen für Ihre App aufgezeichnet wurden?
Wie das alles zusammenhängt, sehen Sie im Synchronisierungszyklus der Google Health API. Es gibt zwei Versionen dieses Lebenszyklus: Standard (Lesen und Schreiben) und schreibgeschützt.
Der Standardlebenszyklus der Synchronisierung
Bei der Integration in die Google Health API werden Daten in eine App oder einen Backend-Datenspeicher kopiert. Der Einfachheit halber nennen wir diesen Datenspeicher in dieser Dokumentation Entwickler-Datenspeicher.
„Kopieren“ kann hier für jede einzelne Aktivität stehen, z. B. für 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 ist der Synchronisierungslebenszyklus.
Abbildung 1 veranschaulicht den Standardsynchronisierungszyklus mit Lese- und Schreibvorgängen, ohne Berücksichtigung der zuvor genannten Faktoren.
Schreiben
- Neue Daten für das Schreiben vorbereiten: Übertragen Sie Daten von einem externen Gerät oder einer externen App und formatieren Sie Datenpunkte in JSON-Darstellungen, die mit den Datentypen der Google Health API kompatibel sind. Benutzerdefinierte, vom Client zugewiesene IDs für Schreibvorgänge werden in der Health API derzeit nicht unterstützt. Solche IDs können in einem
POSTangegeben werden, werden aber ignoriert. - Datensätze einfügen oder aktualisieren: Sie können 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 denPATCH-Vorgang erforderlichen IDs stammen aus einem vorherigenPOST-Vorgang (nächster Schritt in einem vorherigen Zyklus). - Zurückgegebene Ressourcen-IDs verarbeiten: Wenn Sie serverseitig generierte IDs verwenden, extrahieren Sie die vom Server zurückgegebene Ressourcen-
nameoder ‑ID und speichern Sie sie 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 abrufen (
GETmitfilter-Abfrageparametern undpageToken-Paginierung oder Aggregationsendpunkte wierollUpunddailyRollUp) oder Echtzeitbenachrichtigungen über Webhook-Abos (projects.subscribers) erhalten. Eine Benachrichtigung gibt nur an, dass neue Daten verfügbar sind, nicht, welche Daten das sind. - Entwickler-Datenspeicher abgleichen: Gleichen Sie die neuen und aktualisierten Daten mit Ihrem Entwickler-Datenspeicher ab. Bei der Synchronisierung können sich Intervalle von verbundenen Geräten überschneiden. Weitere Informationen dazu, wie die Google Health API diese Probleme löst
Dieser Zyklus wird dann in angemessenen Intervallen wiederholt, je nach den spezifischen Anforderungen externer Geräte oder Apps. Im Allgemeinen empfehlen wir diese Reihenfolge für die Synchronisierung von Daten zwischen Ihrem eigenen Datenspeicher und der Google Health API.
Strategien zur Identifizierung
Wenn Sie Daten in die Google Health API schreiben möchten, müssen Sie vor dem Erstellen Ihrer Integration mit den Google Health APIs eine Strategie zur Ressourcenidentifizierung auswählen, wenn Sie Datenpunkte (die Grundeinheit von Daten) erstellen.
Clientseitig 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-Back-End generiert und gibt eine eindeutige System-ID zurück.
- Clientseitig zugewiesene benutzerdefinierte IDs (gemäß AIP-133, noch nicht unterstützt): Die Client-App generiert eine eindeutige ID (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 die beiden Identifizierungsstrategien 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 eine stabile ID lokal (UUID v4 / interner PK) vor dem Schreiben. |
| Ressourcenpfad | .../dataPoints/{server_id} (in der Antwort zurückgegeben) |
.../dataPoints/{custom_id} |
| Lokaler Schritt nach dem Schreiben | Erforderlich. Der zurückgegebene server_id muss in der lokalen Datenbank gespeichert werden, um zukünftige Aktualisierungen/Löschungen zu ermöglichen. |
Keine. Die App ist bereits Inhaber der ID. |
| ID-Zuordnungstabelle | Erforderlich. Der Client muss eine bidirektionale Zuordnung (local_id ↔ server_id) aufrechterhalten. |
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 noch einmal versuchen, wird ein doppelter Datensatz mit einer neuen Server-ID erstellt. |
Sicher und idempotent. Wenn Sie POST mit demselben custom_id noch einmal versuchen, wird die doppelte Erstellung verhindert (es wird 409
ALREADY_EXISTS zurückgegeben). |
| Unterstützung der Offlinesynchronisierung | Eingeschränkt Sie müssen auf die Serverantwort warten, um offizielle Ressourcen-IDs zu erhalten, bevor Sie darauf verweisen. | Vollständig Entitäten können offline mit stabilen IDs erstellt und geändert werden. Wenn die Verbindung wiederhergestellt wird, werden sie nahtlos synchronisiert. |
| Beschränkungen bei Formaten | Wird vollständig vom Server verarbeitet. | Muss ^[a-z0-9-]{4,63}$ entsprechen (4–63 Kleinbuchstaben, alphanumerische Zeichen und Bindestriche). |
| Wann sollte ich diese Option wählen? |
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 möchte, muss Daten in den Entwickler-Datenspeicher kopieren und den Abgleichsteil des Lebenszyklus verarbeiten.
Hier gelten dieselben Aufgaben wie im Abschnitt Lesen.
Abbildung 2 veranschaulicht den schreibgeschützten Lebenszyklus.
Zeitstempel für Intervalle und Synchronisierung mit verbundenen Geräten
Intervall-Daten stellen Messungen dar, die über einen bestimmten Zeitraum hinweg erfasst werden, z. B. Schritte, Herzfrequenz oder Trainingseinheiten. Im Gegensatz dazu enthalten Momentaufnahmen manuelle Einträge wie ein Ernährungsprotokoll oder eine Waagenmessung. Intervall-Daten stammen in der Regel von der Synchronisierung verbundener Geräte wie Smartwatches und Fitnesstrackern.
Bei der Arbeit mit Intervall-Daten gibt es einige Besonderheiten, die durch die Zeitstempel für Intervalle (startTime und endTime) entstehen. In diesem Abschnitt wird erläutert, warum sich Intervalle überschneiden, 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 biometrische Daten mit hoher Frequenz, während sie getragen werden. Nachdem ein Gerät Datenpunkte mit Google Health synchronisiert hat, werden die vorhandenen Datensätze nicht nachträglich geändert. Die gespeicherten Intervall-Zeitstempel bleiben unverändert.
Vor nachfolgenden Synchronisierungszyklen interpretieren On-Device-Algorithmen jedoch oft die Rohdaten der Sensoren neu. Das Gerät ordnet Messwerte, die in den vorangegangenen Stunden erfasst wurden, neu zu. Wenn das Gerät wieder synchronisiert wird, werden neue Datenpunkte hochgeladen. Die 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 für den Zeitraum
10:00:00Zbis10:14:59Zhoch. - Nach der Neuberechnung auf dem Gerät wird durch eine zweite 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.
Beim Abfragen von Rohdatensätzen ergibt sich dadurch eine Überschneidung von 59 Sekunden.
Endpunkte vergleichen und abstimmen
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/<var>dataType</var>/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints:reconcile |
| Verhalten bei Überschneidungen | Gibt alle gespeicherten Datensätze als hochgeladen ohne Deduplizierung zurück. Wenn sich Intervalle überschneiden, werden beide Datensätze zurückgegeben. | Konflikte werden behoben und sich überschneidende Datensätze werden geräte- und synchronisierungsübergreifend in einem einzigen kontinuierlichen Stream zusammengeführt. |
| Vorteile | Bietet einen vollständigen, unveränderten Audit-Trail für jeden Datensatz, der von jedem Gerät und jeder Synchronisierungsbatch hochgeladen wird. | Vereinfacht das Rendern von Zeitachsen und die Berechnung von Zeiträumen, da sich die API automatisch um sich überschneidende Intervalle und Konflikte für verschiedene Geräte kümmert. |
| Nachteile | Ihre Anwendung ist für das Erkennen und Beheben von sich überschneidenden Intervallen, Konflikten für verschiedene Geräte und Zeiträumen, in denen das Gerät nicht am Handgelenk getragen wird, verantwortlich. | Untergeordnete sich überschneidende Datensätze werden aus der Antwort ausgelassen, sodass einzelne Synchronisierungsbatches für Geräte nicht isoliert geprüft werden können. |
Der reconcile-Endpunkt ist für das Zeichnen von Benutzeroberflächen, das Rendern von Aktivitätszeitachsen und das Berechnen von nicht überlappenden Gesamtdauern vorgesehen. Dadurch werden widersprüchliche Intervalle aus neu gruppierten Synchronisierungssitzungen behoben. Außerdem werden Aktivitäten abgeglichen, die gleichzeitig auf mehreren Geräten wie einer Smartwatch und einem Smartphone aufgezeichnet wurden.
Bei der Abstimmung werden in Konflikt stehende Sitzungen aufgelöst, indem der maßgebliche Datensatz ausgewählt wird, anstatt eine künstliche Zeitvereinigung zu erstellen. Beispiel: 11:00:00Z bis 11:30:00Z und 11:20:00Z bis 11:50:00Z werden nicht in 11:00:00Z bis 11:50:00Z zusammengeführt. Die abgeglichene Antwort gibt den Gewinner-Datenpunkt mit dem ursprünglich aufgezeichneten Intervall zurück. So wird die Integrität der Telemetrie und Messwerte für diese Sitzung gewahrt.
Abbildung 3 veranschaulicht, wie der reconcile-Endpunkt überlappende Sitzungen verarbeitet.
Es wird der maßgebliche Datensatz ausgewählt, anstatt eine künstliche Zeitvereinigung zu erstellen.
Im Endpoints-Leitfaden finden Sie vollständige Beispiele für Anfragen und Antworten. Wenn Sie list-Rohdatensätze mit der reconcile-Ausgabe vergleichen möchten, lesen Sie den Abschnitt Abgestimmte Ansicht von Intervall-Daten abrufen.
Der list-Endpunkt ist für Gerätediagnosen und Datenprüfungen vorgesehen. Verwenden Sie ihn, wenn in Ihrem Workflow unveränderte Datensätze geprüft werden müssen, die von den einzelnen Geräten hochgeladen wurden. Wenn Sie Abfragen mit list ausführen, muss Ihre Clientlogik alle Intervallüberschneidungen in den Rohdaten verarbeiten.
Änderbarkeit von Zeitstempeln und Aktualisierungen des Inhabers
Verbundene Geräte ändern gespeicherte Zeitstempel während normaler Synchronisierungszyklen nicht rückwirkend. Intervall-Zeitstempel (startTime und endTime) sind jedoch nicht für alle Datenquellen universell 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 selbst erstellt haben.
Eine Eigentümeranwendung kann den patch-Endpunkt verwenden, um ihre vorhandenen Datensätze zu aktualisieren. Dazu gehört auch das Ändern von Start- oder Endzeitstempeln.
Ein Beispiel für das Aktualisieren von Zeitstempeln mit PATCH finden Sie im Endpoints-Leitfaden unter Intervallzeitstempel für vorhandene Daten aktualisieren.
Ebenso werden Datenpunkte, die von externen Plattformen wie Health Connect oder Partner-Apps synchronisiert werden, von der ursprünglichen Quelle aktualisiert. Wenn die ursprüngliche Anwendung einen vorhandenen Datensatz ändert, werden diese Änderungen an Google Fit weitergegeben.