中繼資料相關規定

本指南適用於 Health Connect 1.1.0-alpha12 版

如果開發人員選擇升級至 1.1.0-alpha12 版本,Health Connect 中的中繼資料會有所變更。

程式庫資訊

Google Maven Android Gradle 外掛程式構件 ID 會標示您需要升級的 Health Connect 程式庫。將此 Health Connect SDK 依附元件新增至模組層級的 build.gradle 檔案:

dependencies {
  implementation "androidx.health.connect:connect-client:1.1.0-alpha12"
}

中繼資料變更

自 1.1.0-alpha12 版本起,Health Connect Jetpack SDK 已導入兩項中繼資料變更,以確保生態系統中存在其他實用的中繼資料。

每次例項化 Record() 類型物件時,都必須指定中繼資料詳細資料。

將資料寫入 Health Connect 時,您必須指定下列四種記錄方法之一:

錄製方法 說明
RECORDING_METHOD_UNKNOWN 無法驗證錄製方法。
RECORDING_METHOD_MANUAL_ENTRY 使用者輸入資料。
RECORDING_METHOD_AUTOMATICALLY_RECORDED 裝置或感應器記錄了資料。
RECORDING_METHOD_ACTIVELY_RECORDED 使用者在裝置上啟動或結束錄製工作階段。

例如:

StepsRecord(
    startTime \= Instant.ofEpochMilli(1234L),
    startZoneOffset \= null,
    endTime \= Instant.ofEpochMilli(1236L),
    endZoneOffset \= null,
    metadata \= Metadata.manualEntry(),
    Count \= 10,
)

您必須為所有自動和主動記錄的資料指定裝置類型。目前的裝置類型包括:

裝置類型 說明
TYPE_UNKNOWN 裝置類型不明。
TYPE_WATCH 裝置類型為手錶。
TYPE_PHONE 裝置類型為手機。
TYPE_SCALE 裝置類型為體重計。
TYPE_RING 裝置類型為戒指。
TYPE_HEAD_MOUNTED 裝置類型為頭戴式裝置。
TYPE_FITNESS_BAND 裝置類型為健身手環。
TYPE_CHEST_STRAP 裝置類型為胸帶。
TYPE_SMART_DISPLAY 裝置類型為智慧螢幕。

例如:

private val TEST_DEVICE = Device(type = Device.TYPE_PHONE)

已更新程式碼片段

我們已更新 Health Connect 指南,以便在需要新程式碼片段時遵守新的中繼資料規定。如需範例,請參閱「寫入資料」頁面。

新的中繼資料方法

中繼資料無法再直接例項化,因此請使用其中一個工廠方法,取得中繼資料的新例項。每個函式都有三種簽名變化版本:

  • activelyRecorded

    • fun activelyRecorded(device: Device): Metadata.
    • fun activelyRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
    • fun activelyRecordedWithId(id: String, device: Device): Metadata
  • autoRecorded

    • fun autoRecorded(device: Device): Metadata
    • fun autoRecorded(clientRecordId: String, clientRecordVersion: Long = 0, device: Device): Metadata
    • fun autoRecordedWithId(id: String, device: Device): Metadata
  • manualEntry

    • fun manualEntry(device: Device? = null): Metadata
    • fun manualEntry(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
    • fun manualEntryWithId(id: String, device: Device? = null): Metadata
  • unknownRecordingMethod

    • fun unknownRecordingMethod(device: Device? = null): Metadata
    • fun unknownRecordingMethod(clientRecordId: String, clientRecordVersion: Long = 0, device: Device? = null): Metadata
    • fun unknownRecordingMethodWithId(id: String, device: Device? = null): Metadata

詳情請參閱 Android 開放原始碼專案

測試資料

使用Testing Library模擬預期的結構描述值:

private val TEST_METADATA =
    Metadata.unknownRecordingMethod(
        clientRecordId = "clientId",
        clientRecordVersion = 1L,
        device = Device(type = Device.TYPE_UNKNOWN),
    ).populatedWithTestValues(id = "test")

這會模擬 Health Connect 實作行為,在插入記錄時自動填入這些值。

針對測試程式庫,您需要在模組層級的 build.gradle 檔案中新增此 Health Connect SDK 依附元件:

dependencies {
  testImplementation "androidx.health.connect:connect-testing:1.0.0-alpha02"
}

升級程式庫

您需要執行的主要步驟如下:

  1. 將程式庫升級至 1.1.0-alpha12。

  2. 建構程式庫時,如果需要新的中繼資料,系統就會擲回編譯錯誤,因此請務必在例項化 Record() 類型物件時,實作必要的中繼資料變更。這應該會完成遷移作業。