Daten schreiben

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:

1. Häufigkeit der Schreibvorgänge: Wie oft Ihre Anwendung neue Daten in Health Connect überträgt. Schreiben Sie beispielsweise alle 15 Minuten neue Daten.
2. 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	kcal	Alle 15 Minuten	23:15–23:30 – 16 kcal 23:30–23:45 – 16 kcal 23:45 – 00:00 – 16 kcal
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	kcal	Jede Minute	Jede Sekunde	23:14–23:15 – 20 kcal 23:16–23:17 – 20 kcal 23:17–23:18 – 25 kcal
Verbrannte Kalorien insgesamt	kcal	Jede Minute	Jede Sekunde	23:14–23:15 – 36 kcal 23:16–23:17 – 36 kcal 23:17–23:18 – 41 kcal
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%