Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Lire des données brutes

L'exemple suivant vous montre comment lire des données brutes dans le cadre du workflow commun.

Lire des données

Santé Connect permet aux applications de lire des données à partir du datastore lorsqu'elles sont au premier plan et en arrière-plan :

Lecture au premier plan : vous pouvez normalement lire les données de Santé Connect lorsque votre application est au premier plan. Dans ce cas, vous pouvez envisager d'utiliser un service de premier plan pour exécuter cette opération si l'utilisateur ou le système place votre application en arrière-plan pendant une opération de lecture.
Lecture en arrière-plan : en demandant une autorisation supplémentaire à l'utilisateur, vous pouvez lire les données une fois que l'utilisateur ou le système a placé votre application en arrière-plan. Consultez l'exemple complet de lecture en arrière-plan.

Le type de données Pas dans Santé Connect enregistre le nombre de pas qu'un utilisateur a effectués entre deux lectures. Le nombre de pas est une unité de mesure courante pour les plates-formes de santé, de remise en forme et de bien-être. Santé Connect vous permet de lire et d'écrire des données sur le nombre de pas.

Pour lire des enregistrements, créez une ReadRecordsRequest et fournissez la lorsque vous appelez readRecords.

L'exemple suivant montre comment lire les données sur le nombre de pas d'un utilisateur dans un intervalle de temps spécifique. Pour obtenir un exemple plus complet avec SensorManager, consultez le guide sur les données relatives au nombre de pas.

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

Vous pouvez également lire des données agrégées à l'aide de aggregate.

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

Lire les pas sur mobile

Avec Android 14 (niveau d'API 34) et la version 20 ou ultérieure de l'extension SDK, Santé Connect fournit le comptage des pas sur l'appareil. Si une application a reçu l'autorisation READ_STEPS, Santé Connect commence à enregistrer les pas à partir de l'appareil Android, et les utilisateurs voient les données sur les pas ajoutées automatiquement aux entrées Pas de Santé Connect.

Pour vérifier si le comptage des pas sur l'appareil est disponible, assurez-vous que l'appareil exécute Android 14 (niveau d'API 34) et qu'il dispose au moins de la version 20 de l'extension SDK :

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

Si votre application lit les nombres de pas agrégés à l'aide de aggregate et ne filtre pas par DataOrigin, les pas sur l'appareil sont automatiquement inclus dans le total, et aucune modification n'est requise pour la mise à jour de juin 2026.

Modification de l'attribution des pas sur l'appareil

À partir de la mise à jour de juin 2026, les pas suivis de manière native par Santé Connect sont attribués à un nom de package synthétique (SPN), tel que com.android.healthconnect.phone.jd5bdd37e1a8d3667a05d0abebfc4a89e.

Auparavant, les pas intégrés étaient attribués au nom de package android. Les données historiques sur les pas enregistrées avant juin 2026 conservent le nom de package android.

Les SPN sont spécifiques à l'appareil et sont limités à une application pour protéger la confidentialité des utilisateurs :

Stable : le SPN de l'appareil actuel est stable pour votre application.
Limité à l'application : différentes applications sur le même appareil voient différents SPN pour les données sur les pas sur l'appareil.

Requête pour les pas sur l'appareil

Étant donné que les SPN sont limités et spécifiques à l'appareil, vous ne devez pas coder en dur les valeurs de SPN. Utilisez plutôt l'API getCurrentDeviceDataSource() pour récupérer le SPN de l'appareil actuel.

Bien que le comptage des pas sur l'appareil nécessite la version 20 ou ultérieure de l'extension SDK, l'API getCurrentDeviceDataSource() est disponible sur Android 14 (niveau d'API 34) avec la version 11 ou ultérieure de l'extension SDK.

L'API getCurrentDeviceDataSource() n'est pas encore disponible dans la bibliothèque Health Connect Jetpack. Les exemples suivants utilisent plutôt l'API du framework Android :

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

Si votre application doit lire les pas sur l'appareil ou si elle affiche les données sur les pas ventilées par application ou appareil source, vous devez interroger les enregistrements où DataOrigin est android ou correspond au SPN de l'appareil. Si votre application affiche l'attribution des données sur les pas, utilisez metadata.device pour identifier l'appareil source des enregistrements individuels. Pour les pas sur l'appareil identifiés par un SPN dans les données agrégées, vous pouvez utiliser des métadonnées d'appareil telles que model ou manufacturer de DeviceDataSource pour l'attribution, ou utiliser un libellé générique tel que "Votre téléphone" pour les pas sur l'appareil.

L'exemple suivant montre comment lire les données agrégées sur le nombre de pas sur l'appareil en filtrant à la fois android et le SPN de l'appareil actuel :

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.
    }
}

Comptage des pas sur l'appareil

Utilisation des capteurs : Santé Connect utilise le TYPE_STEP_COUNTER capteur de SensorManager. Ce capteur est optimisé pour une faible consommation d'énergie, ce qui le rend idéal pour le suivi continu des pas en arrière-plan.
Granularité des données : pour préserver l'autonomie de la batterie, les données sur les pas sont généralement regroupées et écrites dans la base de données Santé Connect au maximum une fois par minute.
Attribution : les pas enregistrés par cette fonctionnalité avant juin 2026 sont attribués au nom de package android dans DataOrigin. Après cette date, ils sont attribués à un SPN spécifique à l'appareil. Consultez Modification de l'attribution des pas sur l'appareil.
Activation : le mécanisme de comptage des pas sur l'appareil n'est actif que lorsqu'au moins une application sur l'appareil a reçu l'autorisation READ_STEPS dans Santé Connect.

Exemple de lecture en arrière-plan

Pour lire les données en arrière-plan, déclarez l'autorisation suivante dans votre fichier manifeste :

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

L'exemple suivant montre comment lire les données sur le nombre de pas en arrière-plan pour un utilisateur dans un intervalle de temps spécifique à l'aide de WorkManager :

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

Le paramètre ReadRecordsRequest a une valeur pageSize par défaut de 1 000. Si le nombre d'enregistrements dans une seule readResponse dépasse le pageSize de la requête, vous devez parcourir toutes les pages de la réponse pour récupérer tous les enregistrements à l'aide de pageToken. Toutefois, veillez à éviter les problèmes de limitation du débit.

Exemple de lecture pageToken

Il est recommandé d'utiliser pageToken pour lire les enregistrements afin de récupérer toutes les données disponibles pour la période demandée.

L'exemple suivant montre comment lire tous les enregistrements jusqu'à ce que tous les jetons de page aient été épuisés :

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

Pour en savoir plus sur les bonnes pratiques à suivre lors de la lecture de grands ensembles de données, consultez Planifier pour éviter la limitation du débit.

Lire les données déjà écrites

Si une application a déjà écrit des enregistrements sur Santé Connect, elle peut lire les données historiques. Cela s'applique aux scénarios dans lesquels l'application doit se resynchroniser avec Santé Connect après que l'utilisateur l'a réinstallée.

Certaines restrictions de lecture s'appliquent :

Pour Android 14 et versions ultérieures
- Aucune limite historique pour une application qui lit ses propres données.
- Limite de 30 jours pour une application qui lit d'autres données.
Pour Android 13 et versions antérieures
- Limite de 30 jours pour une application qui lit des données.

Les restrictions peuvent être supprimées en demandant une autorisation de lecture.

Pour lire les données historiques, vous devez indiquer le nom du package en tant qu'objet DataOrigin dans le paramètre dataOriginFilter de votre ReadRecordsRequest.

L'exemple suivant montre comment indiquer un nom de package lors de la lecture des enregistrements de la fréquence cardiaque :

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

Lire les données datant de plus de 30 jours

Par défaut, toutes les applications peuvent lire les données de Santé Connect remontant jusqu'à 30 jours avant la date d'octroi de la première autorisation.

Si vous devez étendre les autorisations de lecture au-delà des restrictions par défaut, demandez le PERMISSION_READ_HEALTH_DATA_HISTORY. Sinon, sans cette autorisation, toute tentative de lecture d'enregistrements datant de plus de 30 jours génère une erreur.

Historique des autorisations pour une application supprimée

Si un utilisateur supprime votre application, toutes les autorisations, y compris l'autorisation d'historique, sont révoquées. Si l'utilisateur réinstalle votre application et accorde de nouveau l'autorisation, les mêmes restrictions par défaut s'appliquent, et votre application peut lire les données de Santé Connect remontant jusqu'à 30 jours avant cette nouvelle date.

Par exemple, supposons que l'utilisateur supprime votre application le 10 mai 2023, puis la réinstalle le 15 mai 2023 et accorde des autorisations de lecture. La date la plus ancienne à laquelle votre application peut désormais lire des données par défaut est le 15 avril 2023.

Gérer les exceptions

Santé Connect génère des exceptions standards pour les opérations CRUD en cas de problème. Votre application doit détecter et gérer chacune de ces exceptions de manière appropriée.

Chaque méthode sur HealthConnectClient indique les exceptions qui peuvent être levées. En général, votre application doit gérer les exceptions suivantes :

*Tableau 1 : Exceptions Santé Connect et bonnes pratiques recommandées*
Exception	Description	Bonne pratique recommandée
`IllegalStateException`	L'un des scénarios suivants s'est produit : Le service Santé Connect n'est pas disponible. La requête n'est pas une construction valide (par exemple, une requête globale dans des buckets périodiques où un objet `Instant` est utilisé pour `timeRangeFilter`).	Traitez d'abord les problèmes potentiels liés aux entrées avant d'effectuer une requête. De préférence, attribuez des valeurs aux variables ou utilisez-les comme paramètres dans une fonction personnalisée plutôt que de les utiliser directement dans vos requêtes afin de pouvoir appliquer des stratégies de gestion des erreurs.
`IOException`	Des problèmes surviennent lors de la lecture et de l'écriture des données sur le disque.	Pour éviter cela, voici quelques suggestions : Sauvegardez les entrées utilisateur. Soyez prêt à gérer les problèmes qui surviennent lors des opérations d'écriture groupée. Par exemple, assurez-vous que le processus ne reste pas bloqué par le problème et qu'il poursuit les opérations restantes. Appliquez des stratégies spécifiques aux nouvelles tentatives et aux intervalles entre les tentatives pour gérer les problèmes de requête.
`RemoteException`	Des erreurs se sont produites au sein du service sous-jacent auquel le SDK se connecte, ou lors de sa communication avec celui-ci. (par exemple, votre application tente de supprimer un enregistrement associé à un `uid` donné). Toutefois, l'exception est générée lorsque l'application découvre que l'enregistrement n'existe pas après avoir vérifié le service sous-jacent.	Pour éviter cela, voici quelques suggestions : Effectuez des synchronisations régulières entre le datastore de votre application et Santé Connect. Appliquez des stratégies spécifiques aux nouvelles tentatives et aux intervalles entre les tentatives pour gérer les problèmes de requête.
`SecurityException`	Des problèmes surviennent lorsque les requêtes nécessitent des autorisations qui ne sont pas accordées.	Pour éviter cela, assurez-vous d'avoir déclaré l'utilisation des types de données Santé Connect pour l'application que vous avez publiée. Vous devez également déclarer les autorisations Santé Connect dans le fichier manifeste et dans votre activité.

Écrire des données

Lire les données agrégées