원시 데이터 읽기

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

데이터 읽기

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

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

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

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

기록을 읽으려면 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
}

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

이전에 작성된 데이터 읽기

앱이 이전에 헬스 커넥트에 기록을 쓴 경우 앱에서 과거 데이터를 읽을 수 있습니다. 이는 사용자가 재설치한 후 앱을 헬스 커넥트와 다시 동기화해야 하는 시나리오에 적용됩니다.

다음과 같은 읽기 제한사항이 적용됩니다.

  • Android 14 이상

    • 앱이 자체 데이터를 읽는 데는 이전 제한이 없습니다.
    • 앱이 다른 데이터를 읽는 데 적용되는 30일 제한
  • Android 13 이하

    • 앱에서 데이터를 읽는 데 30일 제한이 적용됩니다.

읽기 권한을 요청하면 제한사항을 삭제할 수 있습니다.

이전 데이터를 읽으려면 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일이 지난 데이터 읽기

기본적으로 모든 애플리케이션은 권한이 처음 부여되기 최대 30일 전부터 헬스 커넥트에서 데이터를 읽을 수 있습니다.

읽기 권한을 기본 제한사항을 넘어 확장해야 하는 경우 PERMISSION_READ_HEALTH_DATA_HISTORY를 요청하세요. 이 권한이 없으면 30일 이전의 레코드를 읽으려고 하면 오류가 발생합니다.

삭제된 앱의 권한 기록

사용자가 앱을 삭제하면 기록 권한을 비롯한 모든 권한이 취소됩니다. 사용자가 앱을 재설치하고 권한을 다시 부여하면 동일한 기본 제한사항이 적용되며 앱은 새로운 날짜로부터 최대 30일 전부터의 헬스 커넥트 데이터를 읽을 수 있습니다.

예를 들어 사용자가 2023년 5월 10일에 앱을 삭제한 다음 2023년 5월 15일에 앱을 재설치하고 읽기 권한을 부여한다고 가정해 보겠습니다. 이제 앱에서 기본적으로 데이터를 읽을 수 있는 가장 빠른 날짜는 2023년 4월 15일입니다.