本頁面由 Cloud Translation API 翻譯而成。

同步處理資料

大多數與 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 值的清單，方便您批次處理多筆要刪除的資料。