L'agrégation des données dans Santé Connect inclut des agrégations de base ou l'agrégation de données dans des buckets. Les workflows suivants vous expliquent comment obtenir chaque type d'agrégation.
Agrégation de base
Pour utiliser l'agrégation de base sur vos données, utilisez la fonction aggregate sur l'objet HealthConnectClient. Celle-ci accepte un objet AggregateRequest dans lequel vous ajoutez les types de métriques et la période en tant que paramètres. La manière dont les agrégations de base sont appelées dépend des types de métriques utilisés.
Agrégation cumulative
L'agrégation cumulative calcule la valeur totale.
L'exemple suivant vous montre comment agréger les données correspondant à un type en particulier :
suspend fun aggregateDistance(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response = healthConnectClient.aggregate(
AggregateRequest(
metrics = setOf(DistanceRecord.DISTANCE_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
// The result may be null if no data is available in the time range
val distanceTotalInMeters = response[DistanceRecord.DISTANCE_TOTAL]?.inMeters ?: 0L
} catch (e: Exception) {
// Run error handling here
}
}
Agrégation statistique
L'agrégation statistique calcule les valeurs minimales, maximales ou moyennes des enregistrements avec des échantillons.
L'exemple suivant montre comment utiliser l'agrégation statistique :
suspend fun aggregateHeartRate(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response =
healthConnectClient.aggregate(
AggregateRequest(
setOf(HeartRateRecord.BPM_MAX, HeartRateRecord.BPM_MIN),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
// The result may be null if no data is available in the time range
val minimumHeartRate = response[HeartRateRecord.BPM_MIN]
val maximumHeartRate = response[HeartRateRecord.BPM_MAX]
} catch (e: Exception) {
// Run error handling here
}
}
Buckets
Santé Connect vous permet également de regrouper des données dans des buckets. Les deux types de buckets que vous pouvez utiliser sont duration (durée) et period (période).
Une fois appelés, ils renvoient une liste de buckets. Notez que cette liste n'est pas forcément exhaustive. Les buckets qui ne contiennent aucune donnée ne s'y trouvent pas.
Durée
Dans ce cas, les données agrégées sont divisées en buckets d'une durée fixe (une minute ou une heure, par exemple). Pour agréger les données dans des buckets, utilisez aggregateGroupByDuration. Cette fonction accepte un objet AggregateGroupByDurationRequest dans lequel vous ajoutez les types de métriques, la période et Duration en tant que paramètres.
Voici un exemple des étapes d'agrégation dans des buckets d'une minute :
suspend fun aggregateStepsIntoMinutes(
healthConnectClient: HealthConnectClient,
startTime: LocalDateTime,
endTime: LocalDateTime
) {
try {
val response =
healthConnectClient.aggregateGroupByDuration(
AggregateGroupByDurationRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
timeRangeSlicer = Duration.ofMinutes(1L)
)
)
for (durationResult in response) {
// The result may be null if no data is available in the time range
val totalSteps = durationResult.result[StepsRecord.COUNT_TOTAL]
}
} catch (e: Exception) {
// Run error handling here
}
}
Période
Dans ce cas, les données agrégées sont divisées en buckets sur une période de temps basée sur des dates, par exemple une semaine ou un mois. Pour agréger les données dans des buckets, utilisez aggregateGroupByPeriod. Cette fonction accepte un objet AggregateGroupByPeriodRequest dans lequel vous ajoutez les types de métriques, la période et Period en tant que paramètres.
Voici un exemple d'étapes agrégation dans des buckets mensuels :
suspend fun aggregateStepsIntoMonths(
healthConnectClient: HealthConnectClient,
startTime: LocalDateTime,
endTime: LocalDateTime
) {
try {
val response =
healthConnectClient.aggregateGroupByPeriod(
AggregateGroupByPeriodRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
timeRangeSlicer = Period.ofMonths(1)
)
)
for (monthlyResult in response) {
// The result may be null if no data is available in the time range
val totalSteps = monthlyResult.result[StepsRecord.COUNT_TOTAL]
}
} catch (e: Exception) {
// Run error handling here
}
}
Restrictions de lecture
Par défaut, votre application peut lire les données remontant jusqu'à 30 jours avec toutes les autorisations accordées.
Avec l'autorisation PERMISSION_READ_HEALTH_DATA_HISTORY, votre application peut lire les données datant de plus de 30 jours.
Restriction de 30 jours
Les applications peuvent lire les données de Santé Connect remontant jusqu'à 30 jours avant la date d'octroi de la première autorisation.
Toutefois, si un utilisateur supprime votre application, l'historique des autorisations sera perdu. Si l'utilisateur réinstalle votre application et accorde de nouveau l'autorisation, elle pourra lire les données de Santé Connect remontant jusqu'à 30 jours avant cette nouvelle date.
Exemple sur 30 jours
Si un utilisateur a d'abord accordé une autorisation de lecture à votre application le 30 mars 2023, les premières données que votre application pourra lire remonteront au 28 février 2023.
Ce même utilisateur supprime ensuite votre application le 10 mai 2023. L'utilisateur décide de la réinstaller le 15 mai 2023 et d'accorder une autorisation de lecture. Votre application pourra donc lire les données remontant au 15 avril 2023.
Lire les données de plus de 30 jours
Si vous souhaitez lire des données datant de plus de 30 jours, vous devez utiliser l'autorisation PERMISSION_READ_HEALTH_DATA_HISTORY. Sans cette autorisation, une tentative de lecture d'un seul enregistrement datant de plus de 30 jours génère une erreur.
Vous ne pouvez pas non plus lire de données datant de plus de 30 jours à l'aide de l'une des requêtes de plage de dates.
Données agrégées affectées par les priorités d'application sélectionnées par l'utilisateur
Les utilisateurs finaux peuvent définir la priorité des applications de sommeil et d'activité qu'ils ont intégrées à Santé Connect. Seuls les utilisateurs finaux peuvent modifier ces listes de priorité. Lorsque vous effectuez une lecture globale, l'API Aggregate tient compte de toutes les données en double et ne conserve que les données de l'application ayant la priorité la plus élevée. Des données en double peuvent exister si plusieurs applications écrivent le même type de données (par exemple, le nombre de pas effectués ou la distance parcourue) en même temps.
Pour savoir comment les utilisateurs finaux peuvent hiérarchiser leurs applications, consultez la section Gérer les données Santé Connect.
L'utilisateur peut ajouter ou supprimer des applications, ainsi que modifier leurs priorités. Un utilisateur peut souhaiter supprimer une application qui écrit des données en double afin que les totaux de données sur l'écran Santé Connect soient identiques à ceux de l'application à laquelle il a attribué la priorité la plus élevée. Les totaux des données sont mis à jour en temps réel.
Même si l'API Aggregate calcule les données des applications Activity et Sleep en les dédupliquant en fonction de la façon dont l'utilisateur a défini ses priorités, vous pouvez toujours créer votre propre logique pour calculer les données séparément pour chaque application qui les écrit.
Seuls les types de données "Activité" et "Sommeil" sont dédupliqués par Santé Connect. Les totaux de données affichés correspondent aux valeurs après la déduplication effectuée par l'API Aggregate. Ces totaux indiquent le jour complet le plus récent pour lequel des données sont disponibles pour les pas et la distance. Pour les autres types d'applications, le nombre total de toutes ces applications combinées est indiqué dans les totaux de données de Santé Connect.
Lectures en arrière-plan
Vous pouvez demander à votre application de s'exécuter en arrière-plan et de lire les données de Santé Connect. Si vous demandez l'autorisation Lecture en arrière-plan, votre utilisateur peut autoriser votre application à lire les données en arrière-plan.