Rohdaten lesen

Das folgende Beispiel zeigt, wie Sie im Rahmen des allgemeinen Workflows Rohdaten lesen.

Daten lesen

Mit Health Connect können Apps Daten aus dem Datenspeicher lesen, wenn die App im Vordergrund und im Hintergrund ausgeführt wird:

• Lesen im Vordergrund: Normalerweise können Sie Daten aus Health Connect lesen, wenn Ihre App im Vordergrund ausgeführt wird. In diesen Fällen sollten Sie einen Dienst im Vordergrund verwenden, um diesen Vorgang auszuführen, falls der Nutzer oder das System Ihre App während eines Lesevorgangs in den Hintergrund verschiebt.

• Lesen im Hintergrund: Wenn Sie eine zusätzliche Berechtigung vom Nutzer anfordern, können Sie Daten lesen, nachdem der Nutzer oder das System Ihre App in den Hintergrund verschoben hat. Vollständiges Beispiel für das Lesen im Hintergrund ansehen.

Der Datentyp „Schritte“ in Health Connect erfasst die Anzahl der Schritte, die ein Nutzer zwischen den Messungen zurückgelegt hat. Die Anzahl der Schritte ist eine gängige Messung auf Gesundheits-, Fitness- und Wellnessplattformen. Mit Health Connect können Sie Schrittzahldaten lesen und schreiben.

Um Datensätze zu lesen, erstellen Sie eine ReadRecordsRequest und geben Sie sie beim Aufruf von readRecords an.

Das folgende Beispiel zeigt, wie Sie Schrittzahlendaten für einen Nutzer innerhalb eines bestimmten Zeitraums lesen. Ein ausführliches Beispiel mit SensorManager, finden Sie in der Anleitung zu Schrittzahl.

val response = healthConnectClient.readRecords(
    ReadRecordsRequest(
        HeartRateRecord::class,
        timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
    )
)
response.records.forEach { record ->
    /* Process records */
}
HealthConnectManager.kt

Sie können Ihre Daten auch aggregiert mit aggregate lesen.

suspend fun readStepsAggregate(startTime: Instant, endTime: Instant): Long {
    val response = healthConnectClient.aggregate(
        AggregateRequest(
            metrics = setOf(StepsRecord.COUNT_TOTAL),
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
        )
    )
    return response[StepsRecord.COUNT_TOTAL] ?: 0L
}
HealthConnectManager.kt

Schritte auf Mobilgeräten lesen

Mit Android 14 (API-Level 34) und SDK-Erweiterung Version 20 oder höher bietet Health Connect eine Schrittzählung auf dem Gerät. Wenn einer App die Berechtigung READ_STEPS erteilt wurde, erfasst Health Connect Schritte vom Android-Gerät und Nutzer sehen, dass den Schrittzählerdaten in Health Connect automatisch Schrittdaten hinzugefügt werden.

Prüfen Sie, ob die Schrittzählung auf dem Gerät verfügbar ist, indem Sie prüfen, ob auf dem Gerät Android 14 (API-Level 34) ausgeführt wird und mindestens die SDK-Erweiterung Version 20 vorhanden ist:

val isStepTrackingAvailable =
    Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE &&
        SdkExtensions.getExtensionVersion(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) >= 20

Wenn Ihre App aggregierte Schrittzählerdaten mit aggregate liest und nicht nach DataOrigin filtert, werden Schritte auf dem Gerät automatisch in die Gesamtzahl einbezogen. Für das Update im Juni 2026 sind keine Änderungen erforderlich.

Änderung der Attribution für Schritte auf Geräten

Ab dem Update im Juni 2026 werden Schritte, die nativ von Health Connect erfasst werden, einem synthetischen Paketnamen (Synthetic Package Name, SPN) zugeschrieben, z. B. com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

Bisher wurden integrierte Schritte dem Paketnamen android zugeschrieben. Für Verlaufsdaten zu Schritten, die vor Juni 2026 erfasst wurden, bleibt der Paketname android erhalten.

SPNs sind gerätespezifisch und werden pro Anwendung festgelegt, um die Privatsphäre der Nutzer zu schützen:

• Stabil:Der SPN für das aktuelle Gerät ist für Ihre Anwendung stabil.
• Anwendungsspezifisch:Für verschiedene Anwendungen auf demselben Gerät werden unterschiedliche SPNs für Schrittdaten auf dem Gerät angezeigt.

Abfrage für Schritte auf Geräten

Da SPNs gerätespezifisch sind und nur für eine bestimmte Anwendung gelten, dürfen Sie SPN-Werte nicht fest codieren. Verwenden Sie stattdessen die getCurrentDeviceDataSource() API, um den SPN für das aktuelle Gerät abzurufen.

Für die Schrittzählung auf dem Gerät ist die SDK-Erweiterung Version 20 oder höher erforderlich. Die getCurrentDeviceDataSource() API ist jedoch auf Android 14 (API-Level 34) mit SDK-Erweiterung Version 11 oder höher verfügbar.

Die getCurrentDeviceDataSource() API ist noch nicht in der Health Connect Jetpack-Bibliothek verfügbar. In den folgenden Beispielen wird stattdessen die Android-Framework-API verwendet:

import android.content.Context
import android.health.connect.HealthConnectManager

val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)
val deviceDataSource = healthConnectManager?.getCurrentDeviceDataSource()
val currentDeviceSpn = deviceDataSource?.deviceDataOrigin?.packageName

Wenn Ihre App Schritte auf dem Gerät lesen muss oder Schrittdaten nach Quellanwendung oder Gerät aufgeschlüsselt anzeigt, müssen Sie nach Datensätzen suchen, bei denen DataOrigin android ist oder mit dem SPN des Geräts übereinstimmt. Wenn Ihre App die Attribution für Schrittdaten anzeigt, verwenden Sie metadata.device um das Quellgerät für einzelne Datensätze zu identifizieren. Für Schritte auf dem Gerät, die in aggregierten Daten durch einen SPN identifiziert werden, können Sie Gerätemetadaten wie model oder manufacturer aus DeviceDataSource für die Attribution verwenden oder ein allgemeines Label wie „Ihr Smartphone“ für Schritte auf dem Gerät verwenden.

Das folgende Beispiel zeigt, wie Sie aggregierte Schrittzählerdaten auf dem Gerät lesen, indem Sie sowohl nach android als auch nach dem SPN des aktuellen Geräts filtern:

import android.content.Context
import android.health.connect.HealthConnectManager
import android.os.Build
import android.os.ext.SdkExtensions
import androidx.health.connect.client.HealthConnectClient
import androidx.health.connect.client.records.StepsRecord
import androidx.health.connect.client.records.metadata.DataOrigin
import androidx.health.connect.client.request.AggregateRequest
import androidx.health.connect.client.time.TimeRangeFilter
import java.time.Instant

suspend fun readDeviceStepsByTimeRange(
    healthConnectClient: HealthConnectClient,
    context: Context,
    startTime: Instant,
    endTime: Instant
) {
    // 1. Check if SDK Extension 11+ is available for getCurrentDeviceDataSource()
    val isDataSourceApiAvailable = Build.VERSION.SDK_INT >= Build.VERSION_CODES.U &&
            SdkExtensions.getExtensionVersion(Build.VERSION_CODES.U) >= 11

    try {
        val healthConnectManager = context.getSystemService(HealthConnectManager::class.java)

        // 2. Safely fetch the package name only if API is available and data exists
        val currentDeviceSpn = if (isDataSourceApiAvailable) {
            healthConnectManager?.getCurrentDeviceDataSource()?.deviceDataOrigin?.packageName
        } else {
            null
        }

        val dataOriginFilters = mutableSetOf(DataOrigin("android"))

        // 3. Explicit null-safety check using .let
        currentDeviceSpn?.let {
            dataOriginFilters.add(DataOrigin(it))
        }

        val response = healthConnectClient.aggregate(
            AggregateRequest(
                metrics = setOf(StepsRecord.COUNT_TOTAL),
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
                dataOriginFilter = dataOriginFilters
            )
        )

        val stepCount = response[StepsRecord.COUNT_TOTAL]

    } catch (e: Exception) {
        // Now this catch block only handles actual runtime exceptions, 
        // rather than Errors from missing methods.
    }
}

Schrittzählung auf dem Gerät

• Sensornutzung: Health Connect verwendet den TYPE_STEP_COUNTER Sensor aus SensorManager. Dieser Sensor ist für einen geringen Stromverbrauch optimiert und eignet sich daher ideal für die kontinuierliche Schrittzählung im Hintergrund.
• Datengranularität: Um die Akkulaufzeit zu verlängern, werden Schrittdaten in der Regel in Batches verarbeitet und höchstens einmal pro Minute in die Health Connect-Datenbank geschrieben.
• Attribution: Schritte, die mit dieser Funktion vor Juni 2026 erfasst wurden, werden in DataOrigin dem Paketnamen android zugeschrieben. Nach diesem Datum werden sie einem gerätespezifischen SPN zugeschrieben. Weitere Informationen finden Sie unter Änderung der Attribution für Schritte auf Geräten.
• Aktivierung: Der Mechanismus zur Schrittzählung auf dem Gerät ist nur aktiv, wenn mindestens einer Anwendung auf dem Gerät die READ_STEPSBerechtigung in Health Connect erteilt wurde.

Beispiel für das Lesen im Hintergrund

Wenn Sie Daten im Hintergrund lesen möchten, deklarieren Sie die folgende Berechtigung in Ihrer Manifestdatei:

<application>
  <uses-permission android:name="android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND" />
...
</application>

Das folgende Beispiel zeigt, wie Sie mit WorkManager Schrittzahlendaten im Hintergrund für einen Nutzer innerhalb eines bestimmten Zeitraums lesen:

class ScheduleWorker(appContext: Context, workerParams: WorkerParameters) :
    CoroutineWorker(appContext, workerParams) {

    override suspend fun doWork(): Result {
        val healthConnectClient = HealthConnectClient.getOrCreate(applicationContext)
        // Perform background read logic here
        return Result.success()
    }
}
HealthConnectWorker.kt

fun enqueueBackgroundReadWorker(context: Context, healthConnectClient: HealthConnectClient) {
    if (healthConnectClient
            .features
            .getFeatureStatus(
                HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
            ) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE
    ) {

        val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
            .build()

        WorkManager.getInstance(context).enqueueUniquePeriodicWork(
            "read_health_connect",
            ExistingPeriodicWorkPolicy.KEEP,
            periodicWorkRequest
        )
    }
}
HealthConnectWorker.kt

Der ReadRecordsRequest Parameter hat einen Standardwert von 1000 für pageSize. Wenn die Anzahl der Datensätze in einer einzelnen readResponse den Wert von pageSize der Anfrage übersteigt, müssen Sie alle Seiten der Antwort durchlaufen, um alle Datensätze mit pageToken abzurufen. Achten Sie jedoch darauf, Ratenbegrenzungen zu vermeiden.

Beispiel für das Lesen mit pageToken

Es wird empfohlen, pageToken zum Lesen von Datensätzen zu verwenden, um alle verfügbaren Daten aus dem angeforderten Zeitraum abzurufen.

Das folgende Beispiel zeigt, wie Sie alle Datensätze lesen, bis alle Seitentokens aufgebraucht sind:

val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))

try {
    var pageToken: String? = null
    do {
        val readResponse =
            healthConnectClient.readRecords(
                ReadRecordsRequest(
                    recordType = type,
                    timeRangeFilter = TimeRangeFilter.between(
                        startTime,
                        endTime
                    ),
                    pageToken = pageToken
                )
            )
        val records = readResponse.records
        // Do something with records
        pageToken = readResponse.pageToken
    } while (pageToken != null)
} catch (quotaError: IllegalStateException) {
    // Backoff
}
HealthConnectManager.kt

Zuvor geschriebene Daten lesen

Wenn eine App bereits Datensätze in Health Connect geschrieben hat, kann sie Verlaufsdaten lesen. Dies gilt für Szenarien, in denen die App nach der Neuinstallation durch den Nutzer mit Health Connect synchronisiert werden muss.

Es gelten einige Einschränkungen für das Lesen:

• Android 14 und höher

  • Keine zeitliche Beschränkung für eine App, die ihre eigenen Daten liest.
  • 30-Tage-Limit für eine App, die andere Daten liest.

• Android 13 und niedriger

  • 30-Tage-Limit für eine App, die beliebige Daten liest.

Die Einschränkungen können aufgehoben werden, indem Sie eine Leseberechtigung anfordern.

Um Verlaufsdaten zu lesen, müssen Sie den Paketnamen als DataOrigin Objekt im dataOriginFilter Parameter Ihrer ReadRecordsRequest angeben.

Das folgende Beispiel zeigt, wie Sie einen Paketnamen angeben, wenn Sie Herzfrequenzdatensätze lesen:

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = HeartRateRecord::class,
            timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
            dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
        )
    )
    for (record in response.records) {
        // Process each record
    }
} catch (e: Exception) {
    // Run error handling here
}
HealthConnectManager.kt

Daten lesen, die älter als 30 Tage sind

Standardmäßig können alle Anwendungen Daten aus Health Connect für bis zu 30 Tage vor dem Zeitpunkt lesen, an dem eine Berechtigung zum ersten Mal erteilt wurde.

Wenn Sie die Leseberechtigungen über die Standardeinschränkungen hinaus erweitern möchten, fordern Sie die PERMISSION_READ_HEALTH_DATA_HISTORY an. Andernfalls führt ein Versuch, Datensätze zu lesen, die älter als 30 Tage sind, ohne diese Berechtigung zu einem Fehler.

Berechtigungsverlauf für eine gelöschte App

Wenn ein Nutzer Ihre App löscht, werden alle Berechtigungen, einschließlich der Berechtigung für den Verlauf, widerrufen. Wenn der Nutzer Ihre App neu installiert und die Berechtigung wieder erteilt, gelten dieselben Standardeinschränkungen. Ihre App kann Daten aus Health Connect für bis zu 30 Tage vor diesem neuen Datum lesen.

Beispiel: Der Nutzer löscht Ihre App am 10. Mai 2023 und installiert sie dann am 15. Mai 2023 neu und erteilt Leseberechtigungen. Das früheste Datum, ab dem Ihre App standardmäßig Daten lesen kann, ist der 15. April 2023.

Ausnahmen behandeln

Health Connect löst Standardausnahmen für CRUD-Vorgänge aus, wenn ein Problem auftritt. Ihre App sollte jede dieser Ausnahmen entsprechend abfangen und behandeln.

Für jede Methode in HealthConnectClient werden die Ausnahmen aufgeführt, die ausgelöst werden können. Im Allgemeinen sollte Ihre App die folgenden Ausnahmen behandeln: