Rohdaten lesen

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

Daten lesen

Health Connect ermöglicht Apps, Daten aus dem Datenspeicher zu 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 sich Ihre App im Vordergrund befindet. 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.

• Lesevorgänge im Hintergrund: Wenn Sie vom Nutzer eine zusätzliche Berechtigung 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

Der Datentyp „Schritte“ in Health Connect erfasst die Anzahl der Schritte, die ein Nutzer zwischen den Messungen zurückgelegt hat. Schrittzahlen sind ein gängiger Messwert auf Gesundheits-, Fitness- und Wellnessplattformen. Mit Health Connect können Sie Daten zur Schrittzahl lesen und schreiben.

Wenn Sie Datensätze lesen möchten, erstellen Sie ein ReadRecordsRequest und geben Sie es beim Aufrufen von readRecords an.

Das folgende Beispiel zeigt, wie Schrittzahlendaten für einen Nutzer innerhalb eines bestimmten Zeitraums gelesen werden. Ein ausführliches Beispiel mit SensorManager finden Sie im Leitfaden zu Schrittzahldaten.

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 dem Smartphone lesen

Unter 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, beginnt Health Connect mit der Erfassung von Schritten auf dem Android-Gerät. Nutzer sehen dann automatisch Schrittdaten, die den Health Connect-Einträgen Schritte hinzugefügt wurden.

So prüfen Sie, ob die Schrittzählung auf dem Gerät verfügbar ist: Das Gerät muss Android 14 (API-Level 34) ausführen und mindestens SDK-Erweiterungsversion 20 haben:

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 Schrittzahlen mit aggregate liest und nicht nach DataOrigin filtert, werden die 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 dem Gerät

Ab dem Update vom Juni 2026 werden Schritte, die nativ von Health Connect erfasst werden, einem synthetischen Paketnamen (SPN) wie com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e zugewiesen.

Bisher wurden integrierte Schritte dem Paketnamen android zugeordnet. Bei Verlaufsdaten zu Schritten, die vor Juni 2026 aufgezeichnet wurden, wird der Paketname android beibehalten.

SPNs sind gerätespezifisch und werden pro Anwendung festgelegt, um den Datenschutz der Nutzer zu gewährleisten:

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

Nach Schritten auf dem Gerät suchen

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

Für die Schrittzählung auf dem Gerät ist die SDK-Erweiterungsversion 20 oder höher erforderlich. Die getCurrentDeviceDataSource() API ist jedoch unter Android 14 (API-Level 34) mit der SDK-Erweiterungsversion 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 Datensätze abfragen, bei denen DataOrigin android oder dem SPN des Geräts entspricht. Wenn in Ihrer App die Quellenangabe für Schrittdaten angezeigt wird, verwenden Sie metadata.device, um das Quellgerät für einzelne Datensätze zu identifizieren. Für On-Device-Schritte, die in aggregierten Daten durch einen SPN identifiziert werden, können Sie Gerätemetadaten wie model oder manufacturer aus DeviceDataSource für die Zuordnung verwenden oder ein generisches Label wie „Ihr Smartphone“ für On-Device-Schritte verwenden.

Das folgende Beispiel zeigt, wie aggregierte On-Device-Schrittzahl-Daten gelesen werden, indem sowohl nach android als auch nach dem aktuellen Geräte-SPN gefiltert wird:

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 Sensor TYPE_STEP_COUNTER von 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 den Akku zu schonen, werden Schrittdaten in der Regel in Batches zusammengefasst und höchstens einmal pro Minute in die Health Connect-Datenbank geschrieben.
• Attribution: Schritte, die vor Juni 2026 mit dieser Funktion aufgezeichnet wurden, werden in der DataOrigin dem Paketnamen android zugeordnet. Danach werden sie einem gerätespezifischen SPN zugeordnet. Weitere Informationen finden Sie unter Änderung der Zuordnung für Schritte auf dem Gerät.
• Aktivierung: Der Mechanismus zur Schrittzählung auf dem Gerät ist nur aktiv, wenn mindestens einer Anwendung auf dem Gerät die Berechtigung READ_STEPS 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 Schrittzahldaten für einen Nutzer in einem bestimmten Zeitraum im Hintergrund mit WorkManager gelesen werden:

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

@OptIn(ExperimentalFeatureAvailabilityApi::class)
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 Parameter ReadRecordsRequest hat den Standardwert pageSize von 1.000. Wenn die Anzahl der Datensätze in einem einzelnen readResponse das pageSize der Anfrage überschreitet, müssen Sie alle Seiten der Antwort durchlaufen, um alle Datensätze mit pageToken abzurufen. Achten Sie jedoch darauf, dass Sie das Ratenlimit nicht überschreiten.

Beispiel für das Lesen von „pageToken“

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

Im folgenden Beispiel wird gezeigt, wie alle Datensätze gelesen werden, bis alle Seitentokens erschöpft 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 Einträge in Health Connect geschrieben hat, kann sie auch 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 Leseeinschränkungen:

• Android 14 und höher

  • Es gibt kein bisheriges Limit für Apps, die ihre eigenen Daten lesen.
  • 30-Tage-Limit für das Lesen anderer Daten durch eine App.

• Android 13 und niedriger

  • 30-Tage-Limit für das Lesen von Daten durch Apps.

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

Wenn Sie Verlaufsdaten lesen möchten, müssen Sie den Paketnamen als DataOrigin-Objekt im Parameter dataOriginFilter Ihres ReadRecordsRequest angeben.

Im folgenden Beispiel wird gezeigt, wie ein Paketname beim Lesen von Herzfrequenzdatensätzen angegeben wird:

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 ersten Erteilen einer Berechtigung lesen.

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

Berechtigungsverlauf für eine gelöschte App

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

Angenommen, der Nutzer löscht Ihre App am 10. Mai 2023, installiert sie am 15. Mai 2023 neu und erteilt Leseberechtigungen. Das früheste Datum, ab dem Ihre App jetzt 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 abfangen und angemessen 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 abfangen: