Cette page a été traduite par l'API Cloud Translation.

Écrire des données

Ce guide explique comment écrire ou mettre à jour des données dans Santé Connect.

Configurer la structure des données

Avant d'écrire des données, nous devons configurer les enregistrements. Pour plus de 50 types de données, chacun présente sa propre structure. Consultez la documentation de référence de Jetpack pour en savoir plus sur les types de données disponibles.

Enregistrements de base

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.

L'exemple suivant montre comment définir les données relatives au nombre de pas :

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Enregistrements avec unités de mesure

Pour plus de précision, Santé Connect peut stocker les valeurs avec leur unité de mesure. Par exemple, le type de données Nutrition est vaste et complet. Il comprend une grande variété de champs de nutriments facultatifs, tels que la quantité totale de glucides ou les vitamines. Chaque point de données représente les nutriments qui ont pu être consommés dans le cadre d'un repas ou d'un aliment.

Dans ce type de données, tous les nutriments sont représentés par des unités de masse (Mass), alors que l'energy est représentée en unité d'Energy.

L'exemple suivant montre comment définir des données nutritionnelles pour un utilisateur qui a mangé une banane :

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
)

Enregistrements avec données séquentielles

Santé Connect peut stocker une liste de données séquentielles. Le type de données Fréquence cardiaque en est un bon exemple. Il capture une série d'échantillons de pulsation détectés entre les lectures.

Dans ce type de données, le paramètre samples est représenté par une liste d'échantillons de la fréquence cardiaque. Chaque exemple contient une valeur beatsPerMinute et une valeur time.

L'exemple suivant montre comment définir des données séquentielles pour la fréquence cardiaque :

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(),
        )
    }
)

Écrire des données

L'un des workflows courants de Santé Connect consiste à écrire des données. Pour ajouter des enregistrements, utilisez insertRecords.

L'exemple suivant montre comment écrire des données pour insérer le nombre de pas :

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

Mettre à jour des données

Si vous devez modifier un ou plusieurs enregistrements, en particulier lorsque vous devez synchroniser le datastore de votre application avec les données de Santé Connect, vous pouvez les mettre à jour. Il existe deux façons de mettre à jour des données existantes en fonction de l'identifiant utilisé pour rechercher les enregistrements.

Métadonnées

Il est utile d'examiner d'abord la classe Metadata, car cela est nécessaire pour mettre à jour les données. Lors de la création, chaque Record dans Santé Connect comporte un champ metadata. Les propriétés suivantes sont pertinentes pour la synchronisation :

Propriétés	Description
`id`	Chaque `Record` dans Santé Connect a une valeur `id` unique. Santé Connect la renseigne automatiquement lorsque vous insérez un nouvel enregistrement.
`lastModifiedTime`	Chaque `Record` conserve la date de sa dernière modification. Santé Connect renseigne automatiquement cette information.
`clientRecordId`	Chaque `Record` peut être associé à un identifiant unique qui servira de référence dans le datastore de votre application. Votre application fournit cette valeur.
`clientRecordVersion`	Lorsqu'un enregistrement est associé à un `clientRecordId`, vous pouvez utiliser `clientRecordVersion` pour permettre aux données de rester synchronisées avec la version du datastore de votre application. Votre application fournit cette valeur.

Mettre à jour les données via un identifiant d'enregistrement

Pour mettre à jour les données, préparez d'abord les enregistrements nécessaires. Si nécessaire, modifiez les enregistrements. Appelez ensuite updateRecords pour effectuer les modifications.

L'exemple suivant montre comment mettre à jour des données. À cette fin, les valeurs de décalage de zone de chaque enregistrement sont définies sur PST.

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

Insérer les données mises à jour via l'identifiant de l'enregistrement client

Si vous utilisez les valeurs facultatives d'identifiant et de version de l'enregistrement client, nous vous recommandons d'utiliser insertRecords au lieu de updateRecords.

La fonction insertRecords peut insérer les données mises à jour. Si les données existent dans Santé Connect en fonction de l'ensemble donné d'identifiants d'enregistrements client, elles sont écrasées. Sinon, elles sont écrites en tant que nouvelles données. Ce scénario est utile lorsque vous devez synchroniser les données du datastore de votre application avec Santé Connect.

L'exemple suivant montre comment effectuer une opération d'insertion des données mises à jour à partir du datastore de l'application :

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

Vous pourrez ensuite appeler ces fonctions dans votre thread principal.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Vérification des valeurs dans la version de l'enregistrement client

Si votre processus d'insertion des données mises à jour inclut la version de l'enregistrement client, Santé Connect effectue des vérifications des valeurs clientRecordVersion. Si la version des données insérées est ultérieure à celle des données existantes, l'insertion des données se produit. Sinon, le processus ignore la modification, et la valeur reste la même.

Pour inclure la gestion des versions dans vos données, vous devez fournir à Metadata.clientRecordVersion une valeur Long basée sur votre logique de gestion des versions.

val sr = StepsRecord(
    count = count,
    startTime = startTime,
    startZoneOffset = startZoneOffset,
    endTime = endTime,
    endZoneOffset = endZoneOffset,
    metadata = Metadata(
        clientRecordId = cid,
        clientRecordVersion = version
    )
)

Les insertions n'incrémentent pas automatiquement la version à chaque modification, ce qui évite tout écrasement inattendu des données. Vous devez donc lui attribuer manuellement une valeur plus élevée.

Bonnes pratiques

Une fois la logique créée, pensez à suivre les bonnes pratiques lorsque vous écrivez ou mettez à jour des données.