In diesem Leitfaden wird das Schreiben oder Aktualisieren von Daten in Health Connect beschrieben.
Datenstruktur einrichten
Bevor wir Daten schreiben, müssen wir die Datensätze einrichten. Bei mehr als 50 Datentypen hat jeder eine entsprechende Struktur. Weitere Informationen zu den verfügbaren Datentypen finden Sie in der Jetpack-Referenz.
Grundlegende Einträge
Mit dem Datentyp Schritte in Health Connect wird die Anzahl der Schritte erfasst, die ein Nutzer zwischen den Messungen zurücklegt. Die Schrittzahl ist ein gängiger Messwert auf Gesundheits-, Fitness- und Wellness-Plattformen.
Das folgende Beispiel zeigt, wie Daten für die Schrittzahl festgelegt werden:
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
Datensätze mit Maßeinheiten
Health Connect kann Werte zusammen mit ihren Maßeinheiten speichern, um für Genauigkeit zu sorgen. Ein Beispiel hierfür ist der umfassende und umfassende Datentyp Nutrition. Es umfasst eine Vielzahl optionaler Nährstofffelder, von gesamten Kohlenhydraten bis hin zu Vitaminen. Jeder Datenpunkt stellt die Nährstoffe dar, die potenziell als Teil einer Mahlzeit oder eines Nahrungsmittels konsumiert wurden.
In diesem Datentyp werden alle Nährstoffe in Einheiten von Mass
dargestellt, während energy
in einer Einheit von Energy
dargestellt wird.
Das folgende Beispiel zeigt, wie Ernährungsdaten für einen Nutzer festgelegt werden, der eine Banane gegessen hat:
val banana = NutritionRecord(
name = "banana",
energy = 105.0.kilocalories,
dietaryFiber = 3.1.grams,
potassium = 0.422.grams,
totalCarbohydrate = 27.0.grams,
totalFat = 0.4.grams,
saturatedFat = 0.1.grams,
sodium = 0.001.grams,
sugar = 14.0.grams,
vitaminB6 = 0.0005.grams,
vitaminC = 0.0103.grams,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
Datensätze mit Reihendaten
Health Connect kann eine Liste mit Daten zu Buchreihen speichern. Ein Beispiel ist der Datentyp Herzfrequenz, mit dem eine Reihe von Herzschlagproben erfasst wird, die zwischen den Messungen erkannt wurden.
In diesem Datentyp wird der Parameter samples
durch eine Liste von Herzfrequenzproben dargestellt. Jede Stichprobe enthält einen beatsPerMinute
- und einen time
-Wert.
Das folgende Beispiel zeigt, wie Daten zur Herzfrequenzreihe festgelegt werden:
val heartRateRecord = HeartRateRecord(
startTime = START_TIME,
startZoneOffset = START_ZONE_OFFSET,
endTime = END_TIME,
endZoneOffset = END_ZONE_OFFSET,
// records 10 arbitrary data, to replace with actual data
samples = List(10) { index ->
HeartRateRecord.Sample(
time = START_TIME + Duration.ofSeconds(index.toLong()),
beatsPerMinute = 100 + index.toLong(),
)
}
)
Daten schreiben
Einer der häufigsten Workflows in Health Connect ist das Schreiben von Daten. Verwenden Sie insertRecords
, um Einträge hinzuzufügen.
Das folgende Beispiel zeigt, wie Daten geschrieben werden, bei denen Schrittzahlen eingefügt werden:
suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
try {
val stepsRecord = StepsRecord(
count = 120,
startTime = START_TIME,
endTime = END_TIME,
startZoneOffset = START_ZONE_OFFSET,
endZoneOffset = END_ZONE_OFFSET
)
healthConnectClient.insertRecords(listOf(stepsRecord))
} catch (e: Exception) {
// Run error handling here
}
}
Daten aktualisieren
Wenn Sie einen oder mehrere Einträge ändern müssen, insbesondere wenn Sie Ihren Anwendungsdatenspeicher mit Daten aus Health Connect synchronisieren müssen, können Sie Ihre Daten aktualisieren. Es gibt zwei Möglichkeiten, vorhandene Daten zu aktualisieren. Diese hängen von der Kennung ab, die zum Auffinden von Datensätzen verwendet wird.
Metadaten
Sie sollten zuerst die Klasse Metadata
untersuchen, da dies beim Aktualisieren von Daten erforderlich ist. Beim Erstellen hat jedes Record
in Health Connect ein metadata
-Feld. Die folgenden Attribute sind für die Synchronisierung relevant:
Properties | Beschreibung |
---|---|
id
|
Jeder Record in Health Connect hat einen eindeutigen id -Wert.Health Connect füllt dieses Feld automatisch beim Einfügen eines neuen Eintrags aus. |
lastModifiedTime
|
In jeder Record wird auch erfasst, wann der Datensatz zuletzt geändert wurde.Dies wird von Health Connect automatisch ausgefüllt. |
clientRecordId
|
Jeder Record kann eine eindeutige ID zugeordnet sein, die als Referenz in Ihrem Anwendungsdatenspeicher dient.
Ihre App stellt diesen Wert bereit. |
clientRecordVersion
|
Wenn ein Datensatz clientRecordId enthält, kann der clientRecordVersion verwendet werden, damit Daten mit der Version im Anwendungsdatenspeicher synchron bleiben.Ihre App stellt diesen Wert bereit. |
Über Datensatz-ID aktualisieren
Bereiten Sie zum Aktualisieren von Daten zuerst die erforderlichen Einträge vor. Nehmen Sie bei Bedarf Änderungen an den Datensätzen vor. Rufen Sie dann updateRecords
auf, um die Änderungen vorzunehmen.
Das folgende Beispiel zeigt, wie Daten aktualisiert werden. Zu diesem Zweck werden die Zonen-Offset-Werte jedes Eintrags in PST angepasst.
suspend fun updateSteps(
healthConnectClient: HealthConnectClient,
prevRecordStartTime: Instant,
prevRecordEndTime: Instant
) {
try {
val request = healthConnectClient.readRecords(
ReadRecordsRequest(
recordType = StepsRecord::class,
timeRangeFilter = TimeRangeFilter.between(
prevRecordStartTime,
prevRecordEndTime
)
)
)
val newStepsRecords = arrayListOf<StepsRecord>()
for (record in request.records) {
// Adjusted both offset values to reflect changes
val sr = StepsRecord(
count = record.count,
startTime = record.startTime,
startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
endTime = record.endTime,
endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
metadata = record.metadata
)
newStepsRecords.add(sr)
}
client.updateRecords(newStepsRecords)
} catch (e: Exception) {
// Run error handling here
}
}
Upsert über Client-Eintrags-ID
Wenn Sie die optionalen Werte „Client-Eintrags-ID“ und „Client-Eintragsversion“ verwenden, empfehlen wir die Verwendung von insertRecords
anstelle von updateRecords
.
Mit der Funktion insertRecords
kann ein Upsert von Daten ausgeführt werden.
Wenn die Daten in Health Connect basierend auf dem angegebenen Satz von Client-Eintrags-IDs vorhanden sind, werden sie überschrieben. Andernfalls werden sie als neue Daten geschrieben.
Dieses Szenario ist nützlich, wenn Sie Daten aus Ihrem Anwendungsdatenspeicher mit Health Connect synchronisieren müssen.
Das folgende Beispiel zeigt, wie ein Upsert für Daten durchgeführt wird, die aus dem Anwendungsdatenspeicher abgerufen wurden:
suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
val appStepsRecords = arrayListOf<StepsRecord>()
// Pull data from app datastore
// ...
// Make changes to data if necessary
// ...
// Store data in appStepsRecords
// ...
var sr = StepsRecord(
// Assign parameters for this record
metadata = Metadata(
clientRecordId = cid
)
)
appStepsRecords.add(sr)
// ...
return appStepsRecords
}
suspend fun upsertSteps(
healthConnectClient: HealthConnectClient,
newStepsRecords: ArrayList<StepsRecord>
) {
try {
healthConnectClient.insertRecords(newStepsRecords)
} catch (e: Exception) {
// Run error handling here
}
}
Danach können Sie diese Funktionen im Hauptthread aufrufen.
upsertSteps(healthConnectClient, pullStepsFromDatastore())
Wertprüfung in Client-Eintragsversion
Wenn Ihr Vorgang zum Upsert von Daten die Client-Eintragsversion enthält, führt Health Connect Vergleichsprüfungen in den clientRecordVersion
-Werten durch. Wenn die Version aus den eingefügten Daten höher ist als die Version aus den vorhandenen Daten, erfolgt das Upsert. Andernfalls wird die Änderung ignoriert und der Wert bleibt gleich.
Wenn Sie die Versionsverwaltung in die Daten aufnehmen möchten, müssen Sie Metadata.clientRecordVersion
mit einem Long
-Wert angeben, der auf Ihrer Versionierungslogik basiert.
val sr = StepsRecord(
count = count,
startTime = startTime,
startZoneOffset = startZoneOffset,
endTime = endTime,
endZoneOffset = endZoneOffset,
metadata = Metadata(
clientRecordId = cid,
clientRecordVersion = version
)
)
Upserts erhöhen version
nicht automatisch bei Änderungen. Dadurch werden unerwartete Instanzen des Überschreibens von Daten verhindert. Dafür müssen Sie manuell einen höheren Wert angeben.
Best Practices für das Schreiben von Daten
Apps dürfen nur eigene Daten in Health Connect schreiben.
Wenn Daten in Ihrer App aus einer anderen App importiert wurden, ist die andere App dafür verantwortlich, ihre eigenen Daten in Health Connect zu schreiben.
Es empfiehlt sich auch, eine Logik zu implementieren, die Schreibausnahmen wie Daten außerhalb der Grenzen oder einen internen Systemfehler verarbeitet. Sie können Ihre Backoff- und Wiederholungsstrategien auf einen Jobplanungsmechanismus anwenden. Wenn das Schreiben in Health Connect letztendlich nicht erfolgreich ist, prüfen Sie, ob Ihre App über diesen Punkt des Exports hinaus möglich ist. Vergessen Sie nicht, Fehler zu protokollieren und zu melden, um eine Diagnose zu ermöglichen.
Beim Daten-Tracking gibt es einige Vorschläge, denen Sie folgen können, je nachdem, wie Ihre App Daten schreibt.
Passives Tracking
Dazu gehören Apps, die ein passives Fitness- oder Gesundheits-Tracking durchführen, z. B. die kontinuierliche Aufzeichnung von Schritten oder Herzfrequenz im Hintergrund.
Ihre App muss auf folgende Weise regelmäßig Daten in Health Connect schreiben:
- Schreiben Sie bei jeder Synchronisierung nur neue Daten und aktualisierte Daten, die seit der letzten Synchronisierung geändert wurden.
- Chunk-Anfragen für maximal 1.000 Datensätze pro Schreibanfrage.
- Planen Sie mit
WorkManager
regelmäßige Hintergrundaufgaben mit einem Zeitraum von mindestens 15 Minuten. Aufgaben so einschränken, dass sie nur ausgeführt werden, wenn das Gerät inaktiv ist und der Akkustand nicht niedrig ist.
val constraints = Constraints.Builder() .requiresBatteryNotLow() .requiresDeviceIdle(true) .build() val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>( 15, TimeUnit.MINUTES, 5, TimeUnit.MINUTES ) .setConstraints(constraints) .build()
Aktives Tracking
Dazu gehören Apps, die ereignisbasiertes Tracking wie Training und Schlaf durchführen, oder manuelle Nutzereingaben, z. B. Ernährung. Diese Einträge werden erstellt, wenn die App im Vordergrund ausgeführt wird, oder in seltenen Fällen, in denen sie mehrmals am Tag verwendet wird.
Achten Sie darauf, dass Ihre App Health Connect nicht über die gesamte Dauer des Ereignisses am Laufen hält.
Es gibt zwei Möglichkeiten, Daten in Health Connect zu schreiben:
- Nach Abschluss der Veranstaltung kannst du die Daten mit Health Connect synchronisieren. Synchronisiere beispielsweise Daten, wenn der Nutzer eine aufgezeichnete Trainingssitzung beendet.
- Planen Sie eine einmalige Aufgabe mit
WorkManager
, um Daten später zu synchronisieren.
Best Practices für Granularität und Häufigkeit von Schreibvorgängen
Verwenden Sie beim Schreiben von Daten in Health Connect die entsprechende Auflösung. Die Verwendung der richtigen Auflösung trägt dazu bei, die Speicherlast zu reduzieren, während die Konsistenz und Genauigkeit der Daten beibehalten werden. Die Datenauflösung umfasst zwei Dinge:
- Häufigkeit der Schreibvorgänge: Wie oft Ihre Anwendung neue Daten in Health Connect überträgt. Schreiben Sie beispielsweise alle 15 Minuten neue Daten.
- Detaillierungsgrad der geschriebenen Daten: wie oft für die eingehenden Daten Stichproben erhoben wurden. Schreiben Sie beispielsweise alle 5 s Herzfrequenzproben. Nicht jeder Datentyp erfordert dieselbe Abtastrate. Die Aktualisierung der Daten zur Schrittzahl bringt wenig Vorteile – im Gegensatz zu einer weniger häufigen Uploadhäufigkeit wie z. B. alle 60 Sekunden. Bei höheren Stichprobenraten erhalten Nutzer jedoch möglicherweise einen detaillierteren und detaillierteren Einblick in ihre Gesundheits- und Fitnessdaten. Abtastraten sollten ein Gleichgewicht zwischen Detail und Leistung finden.
Schreiben von Daten, die über den Tag hinweg überwacht werden
Bei fortlaufend erhobenen Daten wie Schritten sollte Ihre Anwendung mindestens alle 15 Minuten pro Tag in Health Connect schreiben.
Datentyp |
Einheit |
Voraussichtliches |
Beispiel |
Schritte |
Schritte |
Jede Minute |
23:14–23:15 – 5 Schritte 23:16–23:17 – 22 Schritte 23:17–23:18 – 8 Schritte |
Schrittfrequenz |
Schritte/min |
Jede Minute |
23:14–23:15 – 5 SPM 23:16–23:17 – 22 SPM 23:17–23:18 – 8 SPM |
Rollstuhlanschübe |
Pushes |
Jede Minute |
23:14–23:15 – 5 Pushes 23:16–23:17 – 22 Pushes 23:17–23:18 – 8 Pushes |
Verbrannte Kalorien |
Kalorien |
Alle 15 Minuten |
23:15–23:30 – 2 Kalorien 23:30–23:45 – 25 Kalorien 23:45 – 00:00 – 5 Kalorien |
Verbrannte Kalorien insgesamt |
Kalorien |
Alle 15 Minuten |
23:15–23:30 – 16 Kalorien 23:30–23:45 – 16 Kalorien 23:45 - 00:00 - 16 Kalorien |
Strecke |
km/min |
Jede Minute |
23:14–23:15 – 0,008 km 23:16–23:16 – 0,021 km 23:17–23:18 – 0,012 km |
Gewonnene Höhe |
m |
Jede Minute |
20:36–20:37–3,048 m 20:39–20:40–3,048 m 23:23–23:24 – 9,144 m |
Etagen |
Stockwerke |
Jede Minute |
23:14–23:15 – 5 Etagen 23:16–23:16 – 22 Etagen 23:17–23:18 – 8 Etagen |
Herzfrequenz |
bpm |
Jede Minute |
6:11 – 55 SPM |
HeartRateVariabilityRmssd |
ms |
Jede Minute |
6:11–23 ms |
Atemfrequenz |
Atemzüge/Minute |
Jede Minute |
23:14–23:15 – 60 Atemzüge/Minute 23:16–23:16 – 62 Atemzüge/Minute 23:17–23:18 – 64 Atemzüge/Minute |
Sauerstoffsättigung |
% |
Stündlich |
6:11 – 95,208% |
Schreibsitzungen
Die Daten sollten am Ende des Trainings oder der Schlafeinheit in Health Connect geschrieben werden.
Als Best Practice sollten Schlaf- oder Trainingssitzungen mit dem Aufzeichnungsgerät und den entsprechenden Metadaten, einschließlich RecordingMethod
, geschrieben werden.
Ihre Anwendung sollte mindestens den Richtlinien in der nachstehenden Spalte „Erwartete“ entsprechen. Folgen Sie nach Möglichkeit der „besten“ Anleitung.
Daten, die während eines Trainings aufgezeichnet werden
Datentyp |
Einheit |
Voraussichtliches |
Viele Grüße |
Beispiel |
Schritte |
Schritte |
Jede Minute |
Jede Sekunde |
23:14-23:15 – 5 Schritte 23:16–23:17 – 22 Schritte 23:17–23:18 – 8 Schritte |
Schrittfrequenz |
Schritte/min |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 35 SPM 23:16–23:17–37 SPM 23:17–23:18 – 40 SPM |
Rollstuhlanschübe |
Pushes |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 5 Pushes 23:16–23:17 – 22 Pushes 23:17–23:18 – 8 Pushes |
Radfahren/Radfahren |
Atemzüge/Min. |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 65 U/min 23:16–23:17 – 70 U/min 23:17–23:18 – 68 U/min |
Leistung |
Watt |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 250 Watt 23:16–23:17 – 255 Watt 23:17–23:18 – 245 Watt |
Geschwindigkeit |
km/min |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 0,3 km/min 23:16–23:17 – 0,4 km/min 23:17–23:18 –0,4 km/min |
Strecke |
km/m |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 0,008 km 23:16–23:16 – 0,021 km 23:17–23:18 – 0,012 km |
Verbrannte Kalorien |
Kalorien |
Jede Minute |
Jede Sekunde |
23:14-23:15 - 20 Kalorien 23:16–23:17 – 20 Kalorien 23:17–23:18 – 25 Kalorien |
Verbrannte Kalorien insgesamt |
Kalorien |
Jede Minute |
Jede Sekunde |
23:14-23:15 - 36 Kalorien 23:16–23:17 – 36 Kalorien 23:17–23:18 – 41 Kalorien |
Gewonnene Höhe |
m |
Jede Minute |
Jede Sekunde |
20:36–20:37–3,048 m 20:39–20:40–3,048 m 23:23–23:24 – 9,144 m |
Trainingsrouten |
Breiten- und Längengrad/Alt |
Alle 3–5 Sekunden |
Jede Sekunde |
|
Herzfrequenz |
bpm |
Jede Minute |
Jede Sekunde |
23:14–23:15 – 150 SPM 23:16–23:17 –152 SPM 23:17–23:18 – 155 SPM |
Daten, die während des Schlafs aufgezeichnet werden
Datentyp |
Einheit |
Erwartete Beispiele |
Beispiel |
Schlafphasen |
Phase |
Detaillierter Zeitraum pro Schlafphase |
23:46–23:50 – wach 23:50–23:56 – leichter Schlaf 23:56–00:16 – Tiefschlaf |
Ruheherzfrequenz |
bpm |
Einzelner Tageswert (erwartet als Erstes am Morgen) |
6:11 – 60 SPM |
Sauerstoffsättigung |
% |
Einzelner Tageswert (erwartet als Erstes am Morgen) |
6:11 – 95,208% |