다음 예는 원시 데이터를 일반적인 워크플로의 일부로 읽는 방법을 보여줍니다.
데이터 읽기
헬스 커넥트를 사용하면 앱이 포그라운드 및 백그라운드에 있을 때 앱이 데이터 스토어에서 데이터를 읽을 수 있습니다.
포그라운드 읽기: 앱이 포그라운드에 있는 경우 일반적으로 헬스 커넥트에서 데이터를 읽을 수 있습니다. 이러한 경우 읽기 작업 중에 사용자나 시스템이 앱을 백그라운드에 배치할 경우를 대비하여 포그라운드 서비스를 사용하여 이 작업을 실행하는 것이 좋습니다.
백그라운드 읽기: 사용자에게 추가 권한을 요청하면 사용자가 앱을 백그라운드에 배치하거나 시스템이 앱을 백그라운드에 배치한 후 데이터를 읽을 수 있습니다. 전체 백그라운드 읽기 예시를 참고하세요.
헬스 커넥트의 걸음 수 데이터 유형은 측정 시점과 시점 사이에 사용자가 걸은 걸음 수를 포착합니다. 걸음 수는 건강, 피트니스, 웰빙 플랫폼에서 공통으로 측정되는 수치를 나타냅니다. 헬스 커넥트를 사용하면 걸음 수 데이터를 쉽게 읽고 쓸 수 있습니다.
기록을 읽으려면 ReadRecordsRequest를 만들고 readRecords를 호출할 때 제공합니다.
다음 예는 특정 시간 동안 사용자의 걸음 수 데이터를 읽는 방법을 보여줍니다. SensorManager를 사용한 확장된 예는 걸음 수 데이터 가이드를 참고하세요.
suspend fun readStepsByTimeRange(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response = healthConnectClient.readRecords(
ReadRecordsRequest(
StepsRecord::class,
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
for (record in response.records) {
// Process each record
}
} catch (e: Exception) {
// Run error handling here
}
}
aggregate를 사용하여 집계된 방식으로 데이터를 읽을 수도 있습니다.
suspend fun readStepsByTimeRange(
healthConnectClient: HealthConnectClient,
startTime: Instant,
endTime: Instant
) {
try {
val response = healthConnectClient.aggregate(
AggregateRequest(
metrics = setOf(StepsRecord.COUNT_TOTAL),
timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
)
)
// The result may be null if no data is available in the time range
val stepCount = response[StepsRecord.COUNT_TOTAL]
} catch (e: Exception) {
// Run error handling here
}
}
백그라운드 읽기 예
백그라운드에서 데이터를 읽으려면 매니페스트 파일에서 다음 권한을 선언하세요.
<application>
<uses-permission android:name="android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND" />
...
</application>
다음 예는 WorkManager를 사용하여 특정 시간 동안 사용자의 걸음 수 데이터를 백그라운드에서 읽는 방법을 보여줍니다.
class ScheduleWorker(private val appContext: Context, workerParams: WorkerParameters):
CoroutineWorker(appContext, workerParams) {
override suspend fun doWork(): Result {
// Read data and process it.
...
// Return success indicating successful data retrieval
return Result.success()
}
}
if (healthConnectClient
.features
.getFeatureStatus(
HealthConnectFeatures.FEATURE_READ_HEALTH_DATA_IN_BACKGROUND
) == HealthConnectFeatures.FEATURE_STATUS_AVAILABLE) {
// Check if necessary permission is granted
val grantedPermissions = healthConnectClient.permissionController.getGrantedPermissions()
if (PERMISSION_READ_HEALTH_DATA_IN_BACKGROUND !in grantedPermissions) {
// Perform read in foreground
...
} else {
// Schedule the periodic work request in background
val periodicWorkRequest = PeriodicWorkRequestBuilder<ScheduleWorker>(1, TimeUnit.HOURS)
.build()
WorkManager.getInstance(context).enqueueUniquePeriodicWork(
"read_health_connect",
ExistingPeriodicWorkPolicy.KEEP,
periodicWorkRequest
)
}
} else {
// Background reading is not available, perform read in foreground
...
}
ReadRecordsRequest 매개변수의 기본 pageSize 값은 1000입니다.
단일 readResponse의 레코드 수가 요청의 pageSize을 초과하는 경우 pageToken를 사용하여 모든 레코드를 가져오려면 응답의 모든 페이지를 반복해야 합니다.
하지만 비율 제한 문제가 발생하지 않도록 주의해야 합니다.
pageToken 읽기 예
요청된 기간의 모든 사용 가능한 데이터를 가져오기 위해 레코드를 읽는 데 pageToken를 사용하는 것이 좋습니다.
다음 예시에서는 모든 페이지 토큰이 소진될 때까지 모든 레코드를 읽는 방법을 보여줍니다.
val type = HeartRateRecord::class
val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofDays(7))
try {
var pageToken: String? = null
do {
val readResponse =
healthConnectClient.readRecords(
ReadRecordsRequest(
recordType = type,
timeRangeFilter = TimeRangeFilter.between(
startTime,
endTime
),
pageToken = pageToken
)
)
val records = readResponse.records
// Do something with records
pageToken = readResponse.pageToken
} while (pageToken != null)
} catch (quotaError: IllegalStateException) {
// Backoff
}
대규모 데이터 세트를 읽을 때의 권장사항에 대한 자세한 내용은 속도 제한 방지 계획을 참고하세요.
이전에 작성된 데이터 읽기
앱이 이전에 헬스 커넥트에 기록을 쓴 경우 해당 앱에서 과거 데이터를 읽을 수 있습니다. 이는 사용자가 재설치한 후 앱을 헬스 커넥트와 다시 동기화해야 하는 시나리오에 적용됩니다.
다음과 같은 읽기 제한사항이 적용됩니다.
Android 14 이상
- 앱이 자체 데이터를 읽는 데는 이전 제한이 없습니다.
- 앱이 다른 데이터를 읽는 데 적용되는 30일 제한
Android 13 이하
- 앱의 데이터 읽기에 대한 30일 제한
읽기 권한을 요청하면 제한사항을 삭제할 수 있습니다.
이전 데이터를 읽으려면 ReadRecordsRequest의 dataOriginFilter 매개변수에서 DataOrigin 객체로 패키지 이름을 표시해야 합니다.
다음 예는 심박수 기록을 읽을 때 패키지 이름을 표시하는 방법을 보여줍니다.
try {
val response = healthConnectClient.readRecords(
ReadRecordsRequest(
recordType = HeartRateRecord::class,
timeRangeFilter = TimeRangeFilter.between(startTime, endTime),
dataOriginFilter = setOf(DataOrigin("com.my.package.name"))
)
)
for (record in response.records) {
// Process each record
}
} catch (e: Exception) {
// Run error handling here
}
30일이 지난 데이터 읽기
기본적으로 모든 애플리케이션은 권한이 처음 부여되기 최대 30일 전부터의 헬스 커넥트 데이터를 읽을 수 있습니다.
기본 제한사항을 초과하여 읽기 권한을 확장해야 하는 경우 PERMISSION_READ_HEALTH_DATA_HISTORY를 요청하세요.
이 권한이 없으면 30일이 지난 레코드를 읽으려고 할 때 오류가 발생합니다.
삭제된 앱의 권한 기록
사용자가 앱을 삭제하면 기록 권한을 비롯한 모든 권한이 취소됩니다. 사용자가 앱을 재설치하고 권한을 다시 부여하면 동일한 기본 제한사항이 적용되며 앱은 새로운 날짜로부터 최대 30일 전부터의 헬스 커넥트의 데이터를 읽을 수 있습니다.
예를 들어 사용자가 2023년 5월 10일에 앱을 삭제한 다음 2023년 5월 15일에 앱을 다시 설치하고 읽기 권한을 부여한다고 가정해 보겠습니다. 이제 앱에서 기본적으로 데이터를 읽을 수 있는 가장 빠른 날짜는 2023년 4월 15일입니다.
예외 처리
헬스 커넥트는 문제가 발생하면 CRUD 작업에 관한 표준 예외를 발생시킵니다. 앱은 이러한 예외를 적절하게 포착하고 처리해야 합니다.
HealthConnectClient의 각 메서드는 발생할 수 있는 예외를 나열합니다.
앱에서는 일반적으로 다음을 처리해야 합니다.
| 예외 | 설명 | 권장사항 |
|---|---|---|
IllegalStateException
| 다음 시나리오 중 하나가 발생했습니다.
| 요청을 진행하기 전에 먼저 입력과 관련하여 발생할 수 있는 문제를 해결합니다. 오류 처리 전략을 적용할 수 있도록, 요청에서 값을 직접 사용하는 대신 값을 변수에 할당하거나 사용자설정 함수 내에서 매개변수로 사용합니다. |
IOException
| 디스크에서 데이터를 읽고 쓸 때 문제가 발생합니다. | 이 문제를 방지하기 위한 권장사항은 다음과 같습니다.
|
RemoteException
| SDK가 연결되는 기본 서비스에서 또는 서비스와 통신하면서 오류가 발생했습니다. 예를 들어, 앱이 주어진 uid를 사용하여 레코드를 삭제하려고 하지만 앱이 기본 서비스에서 레코드가 존재하지 않는다는 사실을 확인한 후에 예외가 발생합니다.
| 이 문제를 방지하기 위한 권장사항은 다음과 같습니다.
|
SecurityException
| 요청에 부여되지 않은 권한이 필요한 경우 문제가 발생합니다. | 이를 방지하려면 게시된 앱의 헬스 커넥트 데이터 유형 사용을 선언해야 합니다. 또한 헬스 커넥트 권한을 매니페스트 파일과 활동에서 선언해야 합니다. |