以下範例說明如何在常見工作流程中讀取原始資料。
讀取資料
Health Connect 允許應用程式在前景和背景運作時,從資料儲存庫讀取資料:
前景讀取:應用程式在前景運作時,通常可以從 Health Connect 讀取資料。在這種情況下,建議您使用前景服務來執行這項作業,以免使用者或系統在讀取作業期間將應用程式排入背景。
背景讀取:向使用者要求額外權限,即可在使用者或系統將應用程式置於背景後讀取資料。請參閱完整的背景讀取範例。
Health Connect 中的「步數」資料類型會擷取多次讀取的使用者步數。步數代表各健康與健身平台上的常見測量值。Health Connect 提供方便讀取及寫入步數資料的功能。
如要讀取記錄,請建立 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
...
}
讀取先前寫入的資料
如果應用程式之前曾將記錄寫入 Health Connect,則應用程式不必要求這些特定記錄的「讀取」權限,就能重新讀取這些記錄。這適用於使用者重新安裝應用程式後,應用程式需要與 Health Connect 重新同步的情況。
如要在此情況下讀取資料,您需要在 ReadRecordsRequest
的 dataOriginFilter
參數中,將套件名稱指定為 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 天限制
Health Connect 讀取資料時,日期最遠可以溯及首次授予任何權限前的 30 天。
不過,如果使用者刪除您的應用程式,權限記錄就會遺失。當使用者重新安裝應用程式並再次授予權限後,應用程式最多便可讀取從這個新日期回推 30 天的 Health Connect 資料。
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 天前以外的任何資料。