Datenverwaltung in der Google Health API

Die Arbeit mit Daten in der Google Health API besteht im Wesentlichen aus einem Zyklus der Datensynchronisierung zwischen dem Datenspeicher der Google Health API in der Cloud und dem Datenspeicher Ihrer App oder Ihres Back-Ends. Dieser Zyklus kann jedoch je nach verschiedenen Faktoren unterschiedliche Formen annehmen:

• Schreiben Sie Daten in die Google Health API? Lesen Sie nur Daten? Oder beides?
• Befindet sich 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 synchronisieren Sie Geräte?
• Mit welchen Datentypen arbeiten Sie? Grundlegende Zählungen? Maßeinheiten? Reihen mit unterschiedlichen Abtastraten?
• Planen Sie, Daten zu lesen, während Ihre App im Hintergrund ausgeführt wird?
• Planen Sie, mit Verlaufsdaten zu arbeiten, die aufgezeichnet wurden, bevor Ihre App Nutzerberechtigungen erhalten hat?

Um zu verstehen, wie alles zusammenpasst, sehen Sie sich den Synchronisierungslebenszyklus der Google Health API an. Es gibt zwei Versionen dieses Lebenszyklus: Standard (Lesen und Schreiben) und Nur-Lesen.

Der Standard-Synchronisierungslebenszyklus

Abbildung 1: Standard-Synchronisierungslebenszyklus in der Google Health API

Bei der Integration in die Google Health API werden Daten in einen App- oder Back-End-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. Lesen aus der Google Health API (Kopieren in den Entwickler-Datenspeicher) oder 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 Standard-Synchronisierungslebenszyklus mit Lese- und Schreibvorgängen, unabhängig von den zuvor genannten Faktoren.

Schreiben

1. Neue Daten zum Schreiben vorbereiten : Übertragen Sie Daten von einem externen Gerät oder einer externen App und formatieren Sie Datenpunkte in JSON-Darstellungen, die mit den Google Health API-Datentypen kompatibel sind. Beachten Sie, dass benutzerdefinierte, vom Client zugewiesene IDs für Schreibvorgänge in der Health API derzeit nicht unterstützt werden. Solche IDs können in einer POST-Anfrage angegeben werden, werden aber ignoriert.
2. Datensätze einfügen oder aktualisieren : Senden Sie Datenpunkte über REST-Endpunkte an die Google Health API. Verwenden Sie POST zum Erstellen von Datensätzen und PATCH zum Einfügen und Aktualisieren vorhandener Datensätze. Die für den PATCH-Vorgang erforderlichen IDs stammen aus einem vorherigen POST-Vorgang (nächster Schritt in einem vorherigen Zyklus).
3. Zurückgegebene Ressourcen-IDs verarbeiten : Wenn Sie vom Server generierte IDs verwenden, extrahieren und speichern Sie den vom Server zurückgegebenen Ressourcen-name oder die ID in Ihrem Entwickler- Datenspeicher, um zukünftige Aktualisierungen (PATCH) oder Löschvorgänge (DELETE) zu ermöglichen. Weitere Informationen zu den beiden Typen finden Sie unter Identifikationsstrategien.

Lesen

1. Datensätze lesen : Rufen Sie neue Daten und Änderungen an vorhandenen Daten in der Google Health API über REST-Endpunkte ab (GET mit filter-Abfrageparametern und pageToken-Paginierung oder Aggregationsendpunkte wie rollUp und dailyRollUp) oder erhalten Sie Echtzeitbenachrichtigungen über Webhook-Abos (projects.subscribers). Eine Benachrichtigung gibt nur an, dass neue Daten verfügbar sind, nicht, welche Daten das sind.
2. Entwickler-Datenspeicher abgleichen : Gleichen Sie die neuen und aktualisierten Daten mit Ihrem Entwickler-Datenspeicher ab.

Dieser Zyklus wird dann in geeigneten Abständen entsprechend den spezifischen Anforderungen externer Geräte oder Apps wiederholt. 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 Sie Daten in die Google Health API schreiben möchten, müssen Sie vor der Entwicklung Ihrer Integration in die Google Health APIs eine Strategie zur Ressourcenidentifikation auswählen, wenn Sie Datenpunkte erstellen (die Grundeinheit der Daten).

Vom Client zugewiesene IDs für Schreibvorgänge werden in der Health API derzeit nicht unterstützt. Solche IDs können in einer POST-Anfrage angegeben werden, werden aber ignoriert. Details zu dieser Option werden hier nur zu Informationszwecken bereitgestellt.

1. 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.
2. Benutzerdefinierte, vom Client zugewiesene IDs (gemäß AIP-133, noch nicht unterstützt): Die Client-App generiert eine eindeutige ID (z. B. eine UUID oder einen primären Schlüssel der lokalen Datenbank) und gibt sie beim Erstellen im Ressourcenpfad an.

In der folgenden Tabelle werden die beiden Identifikationsstrategien verglichen, damit Sie den richtigen Ansatz für Ihre Integration auswählen können:

Funktion	Vom Server generierte IDs	Benutzerdefinierte, vom Client zugewiesene IDs
ID-Generierung	Der Server generiert während der POST Ausführung eine zufällige System-ID.	Der Client generiert lokal eine stabile ID (UUID v4 / interner primärer Schlüssel) vor dem Schreiben.
Ressourcenpfad	.../dataPoints/{server_id} (in der 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öschvorgänge zu ermöglichen.	Keine. Die App besitzt bereits die ID.
ID-Zuordnungstabelle	Erforderlich. Der Client muss eine bidirektionale Zuordnung (local_id ↔ server_id) verwalten.	Nicht erforderlich. Der Client verwendet direkt seinen eigenen primären Schlüssel.
Wiederholungsverhalten (schwaches Netzwerk)	Risiko von Duplikaten. Wenn eine POST -Anfrage mit Zeitüberschreitung wiederholt wird, wird ein doppelter Datensatz mit einer neuen Server-ID erstellt.	Sicher und idempotent. Wenn POST mit derselben custom_id wiederholt wird, wird die Erstellung von Duplikaten 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 darauf verweisen können.	Vollständig. Entitäten können offline mit stabilen IDs erstellt und geändert werden und werden dann bei der erneuten Verbindung nahtlos synchronisiert.
Formateinschränkungen	Wird vollständig vom Server verarbeitet.	Muss ^[a-z0-9-]{4,63}$ entsprechen (4–63 Kleinbuchstaben, Ziffern und Bindestriche).
Wann auswählen?	Wählen Sie vom Server generierte IDs aus, wenn: Ihre App ist nur zum Schreiben / Anhängen geeignet (z.B. zum Senden von Telemetriedaten oder Schrittzahlen, die später nie aktualisiert oder gelöscht werden). Ihre App verwaltet keine lokale persistente Datenbank mit einzelnen Datenpunkten. Sie bevorzugen Einfachheit, ohne Einschränkungen für die Stringvalidierung verwalten zu müssen (z. B. 4-63 Zeichen).	Wählen Sie benutzerdefinierte IDs aus, wenn: Sie eine bidirektionale Synchronisierungs-App betreiben, die Gesundheitsdaten geräteübergreifend liest, schreibt und aktualisiert. Ihre App verfügt über eine lokale Datenbank (z. B. Room oder SQLite), in der Datensätze mit lokalen primären Schlüsseln gespeichert werden. Ihre Nutzer zeichnen Daten offline oder über intermittierende Mobilfunkverbindungen auf, bei denen sichere Wiederholungen erforderlich sind. Sie möchten ID-Zuordnungstabellen zwischen Ihrer Back-End-Datenbank und der API vermeiden.

Der Nur-Lesen-Synchronisierungslebenszyklus

Abbildung 2: Nur-Lesen-Synchronisierungslebenszyklus in der Google Health API

Eine App, die nur aus der Google Health API lesen möchte, muss Daten in ihren Entwickler-Datenspeicher kopieren und den Abgleichsteil des Lebenszyklus verarbeiten.

Hier gelten dieselben Aufgaben wie im Abschnitt Lesen.

Abbildung 2 veranschaulicht den Nur-Lesen-Lebenszyklus.