大多數與 Health Connect 整合的應用程式都有其專屬的資料儲存庫,用來做為可靠資料來源。Health Connect 提供多種方式,可確保應用程式保持同步。
請確保應用程式執行以下操作:
- 將應用程式資料儲存庫中的全新/更新資料饋送至 Health Connect。
- 從 Health Connect 提取資料相關變更,這些變更會反映在應用程式的資料儲存庫中。
- 若在應用程式的資料儲存庫中刪除資料,也會一併從 Health Connect 刪除該資料。
無論是上述哪一種情況,都請您確保同步處理程序能使 Health Connect 和應用程式儲存庫的資料保持一致。
將資料饋送至 Health Connect
同步處理程序的第一階段,就是將應用程式儲存庫的資料饋送至 Health Connect 資料儲存庫。
準備資料
應用程式資料儲存庫中的記錄通常包含下列詳細資料:
- 專屬金鑰,例如
UUID
。 - 版本或時間戳記。
您可以設計應用程式資料儲存庫,以便追蹤已饋送至 Health Connect 的資料。為達成此目標,請應用以下邏輯:
- 提供變更清單和權杖,這可用於擷取自上次權杖核發以來的更新記錄。
- 追蹤上次修改匯出資料的時間。
請務必完成這些步驟,確保只將全新資料或更新資料饋送至 Health Connect。
將資料寫入 Health Connect
如要將資料饋送至 Health Connect,請執行下列步驟:
- 從應用程式的資料儲存庫取得全新項目或更新項目清單。
- 針對每個項目,建立適合該資料類型的
Record
物件。舉例來說,您可以為體重相關資料建立WeightRecord
物件。 使用應用程式資料儲存庫的專屬金鑰和版本詳細資料,為每個
Record
指定Metadata
物件。如果資料尚未建立版本,您可以使用目前時間戳記的Long
值做為替代項目。val record = WeightRecord( metadata = Metadata( clientRecordId = "<Your record's Client ID>", clientRecordVersion = <Your record's version> ), weight = weight, time = time, zoneOffset = zoneOffset )
使用
insertRecords
將資料更新/插入至 Health Connect。更新/插入資料的含意是,只要 Health Connect 資料儲存庫中有clientRecordId
值,且clientRecordVersion
高於現有的值,那麼 Health Connect 中的所有現有資料都會遭到覆寫。但如果不是的話,則會以新資料的形式寫入更新/插入的資料。healthConnectClient.insertRecords(arrayListOf(record))
如要瞭解饋送資料的具體注意事項,請參閱「寫入資料」的最佳做法。
儲存 Health Connect ID
將記錄更新/插入至 Health Connect 後,應用程式的資料儲存庫需要儲存每筆記錄的 Health Connect id
。這樣做可讓應用程式在您提取資料後,確認每項即將發生的變更是否需要建立新的記錄,或更新現有記錄。
insertRecords
函式會傳回包含 id
值清單的 InsertRecordsResponse
。請使用回應取得並儲存記錄 ID。
val response = healthConnectClient.insertRecords(arrayListOf(record))
for (recordId in response.recordIdsList) {
// Store recordId to your app's datastore
}
從 Health Connect 提取資料
同步處理程序的第二階段,是將任何資料相關變更從 Health Connect 提取至應用程式的資料儲存庫。資料相關變更可能包括更新和刪除行為。
取得變更權杖
如果您想取得清單,瞭解要從 Health Connect 提取哪些變更,您的應用程式需要先追蹤「變更」權杖。您可以在要求「變更」時使用這些權杖,以便同時傳回資料變更清單,以及將於下次使用的全新「變更」權杖。
如要取得「變更」權杖,請呼叫 getChangesToken
,並提供必要的資料類型。
val changesToken = healthConnectClient.getChangesToken(
ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)
檢查資料變更
取得「變更」權杖後,請使用該權杖來取得所有「變更」。建議您建立可通過所有「變更」的迴圈,藉此檢查是否有可用的資料變更。操作步驟如下:
- 使用權杖呼叫
getChanges
,取得變更清單。 - 檢查各項變更的類型是
UpsertionChange
或DeletionChange
,並執行必要作業。- 如果是
UpsertionChange
,請只取用非來自呼叫應用程式的變更,確保不會重新匯入資料。
- 如果是
- 指派下一個「變更」權杖做為新權杖。
- 重複執行步驟 1 到 3,直到沒有剩餘的「變更」為止。
- 儲存下一個權杖以供日後匯入時使用。
suspend fun processChanges(token: String): String {
var nextChangesToken = token
do {
val response = healthConnectClient.getChanges(nextChangesToken)
response.changes.forEach { change ->
when (change) {
is UpsertionChange ->
if (change.record.metadata.dataOrigin.packageName != context.packageName) {
processUpsertionChange(change)
}
is DeletionChange -> processDeletionChange(change)
}
}
nextChangesToken = response.nextChangesToken
} while (response.hasMore)
// Return and store the changes token for use next time.
return nextChangesToken
}
如要瞭解提取資料的具體注意事項,請參閱「同步處理資料」的最佳做法。
處理資料變更
您可以讓應用程式的資料儲存庫反映相關變更。如果是 UpsertionChange
,請使用 id
和源自其 metadata
的 lastModifiedTime
更新/插入記錄。如果是 DeletionChange
,請使用提供的 id
來刪除記錄。
刪除 Health Connect 中的資料
當使用者從您的應用程式刪除自己的資料時,請確保這些資料也會從 Health Connect 中移除。您可以使用 deleteRecords
執行此操作。這會取得 id
和 clientRecordId
值的記錄類型和清單,方便您批次處理多筆要刪除的資料。也可以選擇納入 timeRangeFilter
的替代 deleteRecords
。