讀取匯總資料

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

Bucket

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 天限制

應用程式從 Health Connect 讀取資料時，日期最遠可以溯及首次授予任何權限前的 30 天。

不過，如果使用者刪除您的應用程式，權限記錄就會遺失。當使用者重新安裝您的應用程式並再次授予權限後，應用程式最多便可讀取從這個新日期回推 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 天前以外的任何資料。