读取汇总数据

在 Health Connect 中汇总数据的操作包括基本汇总或将数据汇总到存储分区中。以下工作流将向您介绍如何执行这两个操作。

基本汇总

如需对数据使用基本汇总，请对 HealthConnectClient 对象使用 aggregate 函数。该函数接受 AggregateRequest 对象，您可以在其中添加指标类型和时间范围作为其参数。基本汇总的调用方式取决于所使用的指标类型。

累计汇总

累计汇总会计算总值。

以下示例展示了如何针对某个数据类型汇总数据：

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

统计汇总

统计汇总会使用样本计算相关记录的最小值、最大值或平均值。

以下示例展示了如何使用统计汇总：

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

存储分区

借助 Health Connect，您还可以将数据汇总到存储分区中。您可以使用两种类型的存储分区，包括时长和时间段。

调用后，它们会返回存储分区列表。请注意，该列表可能会采用稀疏格式，因此，如果存储分区中未包含任何数据，则不会将其包含在列表中。

时长

在此类型中，汇总数据会在固定的时长（例如一分钟或一小时）内拆分到多个存储分区中。如需将数据汇总到存储分区中，请使用 aggregateGroupByDuration。它接受 AggregateGroupByDurationRequest 对象，您可以在其中添加指标类型、时间范围和 Duration 作为参数。

以下示例展示了如何将步数汇总到时长为一分钟的存储分区中：

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

时间段

在此类型中，汇总数据会在基于日期的时间段（例如一周或一个月）内拆分到多个存储分区中。如需将数据汇总到存储分区中，请使用 aggregateGroupByPeriod。它接受 AggregateGroupByPeriodRequest 对象，您可以在其中添加指标类型、时间范围和 Period 作为参数。

以下示例展示了如何将步数汇总到每月存储分区中：

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

读取限制

默认情况下，您的应用可以读取在获得任何权限后最多 30 天的数据。借助 PERMISSION_READ_HEALTH_DATA_HISTORY 权限，您的应用可以读取 30 天之前的数据。

30 天限制

应用可以读取在首次授予任何权限前最多 30 天的 Health Connect 数据。

不过，如果用户删除您的应用，权限历史记录将会丢失。如果用户重新安装您的应用并再次授予权限，则您的应用可以读取从该新日期最多回推 30 天的 Health Connect 数据。

30 天示例

假设某用户在 2023 年 3 月 30 日首次向您的应用授予读取权限，则您的应用可读取的数据日期最早可回推到 2023 年 2 月 28 日。

之后，该用户在 2023 年 5 月 10 日删除了您的应用。用户决定在 2023 年 5 月 15 日重新安装该应用，并授予读取权限。现在，您的应用可读取的数据最早可追溯至 2023 年 4 月 15 日。

读取 30 天前的数据

如果您想读取 30 天之前的数据，则必须使用 PERMISSION_READ_HEALTH_DATA_HISTORY 权限。如果没有此权限，尝试读取 30 天以上的单个记录将导致错误。此外，您也无法使用时间范围请求之一读取 30 天之前的任何数据。