원시 데이터 읽기

다음 예는 원시 데이터를 일반적인 워크플로의 일부로 읽는 방법을 보여줍니다.

데이터 읽기

헬스 커넥트를 사용하면 앱이 포그라운드와 백그라운드에 있을 때 앱이 데이터 스토어에서 데이터를 읽을 수 있습니다.

  • 포그라운드 읽기: 앱이 포그라운드에 있을 때는 일반적으로 헬스 커넥트에서 데이터를 읽을 수 있습니다. 이 경우 사용자 또는 시스템이 읽기 작업 중에 앱을 백그라운드에 배치하는 경우 포그라운드 서비스를 사용하여 이 작업을 실행하는 것이 좋습니다.

  • 백그라운드 읽기: 사용자에게 추가 권한을 요청하면 사용자 또는 시스템에서 앱을 백그라운드로 전환한 후 데이터를 읽을 수 있습니다. 전체 백그라운드 읽기 예를 참고하세요.

헬스 커넥트의 걸음 수 데이터 유형은 측정 시점과 시점 사이에 사용자가 걸은 걸음 수를 포착합니다. 걸음 수는 건강, 피트니스, 웰빙 플랫폼에서 공통으로 측정되는 수치를 나타냅니다. 헬스 커넥트를 사용하면 걸음 수 데이터를 쉽게 읽고 쓸 수 있습니다.

기록을 읽으려면 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 (stepRecord in response.records) {
            // Process each step record
        }
    } 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 값은 1,000입니다. 단일 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
}

대규모 데이터 세트를 읽을 때의 권장사항에 관한 자세한 내용은 비율 제한을 피하기 위한 계획을 참고하세요.

이전에 작성된 데이터 읽기

앱이 이전에 헬스 커넥트에 기록을 쓴 경우 이러한 특정 기록에 대한 읽기 권한이 없어도 앱에서 기록을 다시 읽을 수 있습니다. 이는 사용자가 재설치한 후 앱을 헬스 커넥트와 다시 동기화해야 하는 시나리오에 적용됩니다.

이 시나리오에서 데이터를 읽으려면 ReadRecordsRequestdataOriginFilter 매개변수에서 DataOrigin 객체로 패키지 이름을 표시해야 합니다.

다음 예는 걸음 수 기록을 읽을 때 패키지 이름을 표시하는 방법을 보여줍니다.

try {
    val response =  healthConnectClient.readRecords(
        ReadRecordsRequest(
            recordType = StepsRecord::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일 동안 데이터를 읽을 수 있습니다. 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일 이전의 데이터를 읽을 수 없습니다.