헬스 커넥트에서 데이터를 집계하는 작업에는 기본 집계 또는 버킷으로 데이터를 집계하는 작업이 포함됩니다. 다음 워크플로는 이 두 가지 작업을 실행하는 방법을 보여줍니다.
기본 집계
데이터에 기본 집계를 사용하려면 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
}
}
버킷
헬스 커넥트를 사용하면 데이터를 버킷으로 집계할 수도 있습니다. 사용할 수 있는 버킷에는 시간과 기간이라는 두 가지 유형이 있습니다.
호출하면 버킷 목록이 반환됩니다. 목록은 희소할 수 있으므로 버킷에 데이터가 포함되어 있지 않으면 목록에 포함되지 않습니다.
시간
이 경우 집계된 데이터는 고정된 시간(예: 1분 또는 1시간) 내에 버킷으로 분할됩니다. 데이터를 버킷으로 집계하려면 aggregateGroupByDuration
을 사용하세요. 이는 AggregateGroupByDurationRequest
객체를 허용하며 여기서 측정항목 유형, 기간, Duration
을 매개변수로 추가합니다.
다음은 걸음 수를 1분 길이의 버킷으로 집계하는 예를 보여줍니다.
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
}
}
기간
이 경우 집계된 데이터는 날짜 기반 기간(예: 1주 또는 1개월) 내에 버킷으로 분할됩니다. 데이터를 버킷으로 집계하려면 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일 전부터의 헬스 커넥트 데이터를 읽을 수 있습니다.
그러나 사용자가 앱을 삭제하면 권한 기록이 사라집니다. 사용자가 앱을 재설치하고 권한을 다시 부여하면 앱은 새로운 날짜로부터 최대 30일 전부터의 헬스 커넥트의 데이터를 읽을 수 있습니다.
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일 이전의 데이터를 읽을 수 없습니다.
사용자가 선택한 앱 우선순위에 영향을 받는 데이터 집계
최종 사용자는 헬스 커넥트와 통합한 수면 및 활동 앱의 우선순위를 설정할 수 있습니다. 최종 사용자만 이러한 우선순위 목록을 변경할 수 있습니다. 집계 읽기를 실행하면 Aggregate API는 중복 데이터를 고려하고 우선순위가 가장 높은 앱의 데이터만 유지합니다. 걸음 수나 이동 거리와 같은 동일한 종류의 데이터를 동시에 쓰는 앱이 여러 개 있는 경우 중복 데이터가 있을 수 있습니다.
최종 사용자가 앱의 우선순위를 지정하는 방법에 관한 자세한 내용은 헬스 커넥트 데이터 관리를 참고하세요.
사용자는 앱을 추가하거나 삭제하고 우선순위를 변경할 수 있습니다. 사용자는 헬스 커넥트 화면의 데이터 총계가 가장 높은 우선순위를 부여한 앱과 동일하도록 중복 데이터를 쓰는 앱을 삭제할 수 있습니다. 데이터 합계는 실시간으로 업데이트됩니다.
Aggregate API는 사용자가 우선순위를 설정한 방식에 따라 데이터를 중복 삭제하여 활동 및 수면 앱의 데이터를 계산하지만, 자체 로직을 빌드하여 해당 데이터를 쓰는 각 앱에 대해 데이터를 별도로 계산할 수도 있습니다.
헬스 커넥트에서 활동 및 수면 데이터 유형만 중복 삭제되며 표시되는 데이터 합계는 집계 API에서 중복 삭제 작업을 실행한 후의 값입니다. 이 총계는 걸음 수 및 거리에 데이터가 있는 가장 최근 하루 전체를 보여줍니다. 다른 유형의 앱의 경우 이러한 모든 앱의 총 개수가 헬스 커넥트의 데이터 총계에 표시됩니다.
백그라운드 읽기
애플리케이션이 백그라운드에서 실행되고 헬스 커넥트에서 데이터를 읽도록 요청할 수 있습니다. 백그라운드 읽기 권한을 요청하면 사용자는 앱에 백그라운드에서 데이터를 읽을 수 있는 액세스 권한을 부여할 수 있습니다.