元データを読み取る

次の例は、一般的なワークフローの一環として元データを読み取る方法を示しています。

データを読み取る

ヘルスコネクトでは、アプリがフォアグラウンドとバックグラウンドにあるときに、アプリがデータストアからデータを読み取ることができます。

  • フォアグラウンドの読み取り: 通常、アプリがフォアグラウンドにあるときにヘルスコネクトからデータを読み取ることができます。このような場合は、読み取りオペレーション中にユーザーまたはシステムによってアプリがバックグラウンドに移動された場合に備えて、フォアグラウンド サービスを使用してこのオペレーションを実行することを検討してください。

  • バックグラウンドでの読み取り: ユーザーから追加の権限をリクエストすることで、ユーザーまたはシステムがアプリをバックグラウンドに配置した後にデータを読み取ることができます。バックグラウンド読み取りの例をご覧ください。

ヘルスコネクトのデータの種類「歩数」では、各読み取りの間にユーザーが歩いた歩数が記録されます。歩数は、健康、フィットネス、ウェルネスのプラットフォームで共通の測定値を表します。ヘルスコネクトでは、歩数データの読み取りと書き込みが簡単にできます。

レコードを読み取るには、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 です。1 つの 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 日です。