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

同步處理資料

大多數與 Health Connect 整合的應用程式都有其專屬的資料儲存庫做為可靠資料來源Health Connect 提供多種方式同步。

請確保應用程式執行以下操作：

將應用程式資料儲存庫中的全新資料或更新資料饋送至 Health Connect。
從 Health Connect 提取資料相關變更，這些變更會反映在在應用程式的資料儲存庫中。
若在應用程式的資料儲存庫中刪除資料，亦會從 Health Connect 刪除該資料。

無論是上述哪一種情況，都請您確保同步處理程序能同時保留 Health Connect 和應用程式的資料儲存庫對齊方式

將資料動態饋給至 Health Connect

同步處理程序的第一階段，就是從應用程式資料儲存庫提供資料至 Health Connect 資料儲存庫

準備資料

應用程式資料儲存庫中的記錄通常包含下列詳細資料：

專屬金鑰，例如 UUID。
版本或時間戳記。

設計應用程式資料儲存庫，以追蹤已動態饋給的資料健康資料同步。為達成此目標，請應用以下邏輯：

提供變更清單和權杖，以便用於擷取記錄更新應用程式。
追蹤上次修改匯出資料的時間。

請務必完成這些步驟，確保只將全新資料或更新資料動態饋給健康資料同步。

將資料寫入 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
)

使用以下程式碼將資料更新/插入資料至 Health Connect insertRecords。更新/安裝資料是指只要 clientRecordId，系統就會覆寫 Health Connect 中的資料 Health Connect 資料儲存庫中存在的值，而 clientRecordVersion 大於現有值但如果不是的話，則會寫入更新/插入的資料視為新資料。
```
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，請只取用非來自呼叫 app，確定您沒有重新匯入資料。
指派下一個「變更」權杖做為新權杖。
重複執行步驟 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 和 lastModifiedTime 的 metadata 對記錄進行更新。如果是 DeletionChange，請使用提供的 id 來刪除記錄。

刪除 Health Connect 中的資料

當使用者從您的應用程式刪除自己的資料時，請確認資料也已從 Health Connect 移除。使用 deleteRecords 執行這個步驟這會擷取 id 和 clientRecordId 的記錄類型和清單值，方便您批次處理多筆要刪除的資料。一個替代 deleteRecords，接收 timeRangeFilter 您也可以使用

同步處理資料的最佳做法

以下因素會影響同步處理程序。

權杖到期

未使用的「變更」權杖會在 30 天內到期，因此您必須使用同步處理避免在這類情況下遺失資訊的策略您的策略包括：

搜尋應用程式資料儲存庫，找出最近取用的記錄擁有 Health Connect 的id。
要求 Health Connect 提供特定時間戳記之後的記錄，並在應用程式資料儲存庫中插入或更新該記錄。
要求提供變更權杖，並保留至下次需要時使用。

建議的變更管理策略

如果應用程式收到無效或過期的「變更」權杖，我們會根據 Google Cloud 的應用情境，建議採用下列管理策略您的邏輯：

讀取及簡化所有資料。這是最理想的策略。
- 儲存上次從 Health Connect 讀取資料時的時間戳記。
- 在權杖過期時，從最近的時間戳記或過去 30 天的資料接著使用識別碼
- 在理想情況下，請實作用戶端 ID，因為必須使用用戶端 ID 才能更新資料。
僅讀取自上次讀取時間戳記以來的資料。這會導致不過，時間範圍會伴隨變更權杖到期則可能需時數小時至數天
- 儲存上次從 Health Connect 讀取資料時的時間戳記。
- 在權杖到期時，讀取這個時間戳記後的所有資料。
刪除再讀取過去 30 天的資料。這與初次整合時的情況
- 刪除應用程式在過去 30 天內從 Health Connect 讀取的所有資料天。
- 刪除完成後，再次讀取所有資料。
讀取過去 30 天的資料，且不刪除重複的資料。不理想以免使用者看到重複的資料。
- 刪除應用程式從 Health Connect 讀取的所有資料：過去 30 天的資料
- 允許重複的項目。

資料類型變更權杖

如果應用程式可獨立取用多種資料類型，請使用獨立的變更每種資料類型的權杖。請只搭配使用多種資料類型和變更同步 API (如果同時取用或完全不取用這些資料類型)。

前景讀取

應用程式只有在前景運作時，才能從 Health Connect 讀取資料。從 Health Connect 同步處理資料時，「健康資料同步」的存取作業可能會隨時中斷舉例來說，您的應用程式必須處理中斷讀取 Health Connect 中的大量資料時並在下次開啟應用程式時繼續

匯入時間

如果應用程式無法在資料新增時收到通知，則應在以下兩個時間點檢查新資料：

每當應用程式開始在前景運作時。請在這種情況下使用生命週期事件。
應用程式持續在前景運作的期間。請定期檢查新資料。通知使用者：新的資料可用時，他們可以更新畫面來反映並輸入變更內容