資料類型

Google Fit 會在 com.google 命名空間下方提供一組健康與保健資料類型。

資料類型定義了資料點內值的格式。資料點可以代表：

  • 即時閱讀或觀察
  • 一段時間內的統計資料匯總

Google Fit 會定義即時觀察的資料類型，以及匯總資料的資料類型。資料點是由資料類型欄位和時間戳記資訊的值所組成。代表即時觀察的點包括時間戳記；匯總資料類型的點也包含間隔的開始時間。

Google Fit 還可讓您定義新的資料類型。

資料類型群組

Google Fit 提供下列資料類型：

公開資料類型
平台提供的標準資料類型含有「com.google」這個前置字元。例如 com.google.step_count.delta。這些資料類型會擷取即時健康讀數，包括健身活動、睡眠和營養資料。任何應用程式都可以要求相關權限，以讀取和寫入這些資料類型，只有部分位置資料類型，只有可將其寫入的應用程式才能讀取。

詳情請參閱：

健康狀態資料類型
平台提供的資料類型，可能因機密資料而受到限制。詳情請參閱健康狀態資料類型。
匯總資料類型
用於讀取根據時間和活動類型匯總的健康與保健資訊的資料類型。詳情請參閱匯總資料類型一文。
私人自訂資料類型
特定應用程式定義的自訂資料類型。只有定義該資料類型的應用程式才能讀取及寫入這個類型的資料。詳情請參閱自訂資料類型。

使用資料類型

Android

在 Android 中，資料類型定義為 DataType 類別的公開欄位。如何使用所需項目叫用 Fitness API 的方式：

  • 如要記錄資料，請使用 Recording API 為您要記錄的每個資料類型建立訂閱項目。
  • 如要讀取資料，請使用 History API，針對各個資料類型提交讀取要求。
  • 如要插入過去的歷來資料，請使用 History API 為每個資料類型提交插入要求。
  • 如要建立工作階段，請使用 Sessions API 來插入或記錄具有工作階段中繼資料的資料。

如要為即時 DataType 物件建立資料點，請使用正確的格式指派值。以下範例說明如何將食品指派為字串、來自 Field 類別的餐飲類型為常數，以及將營養內容視為對應的浮點值。

val nutritionSource = DataSource.Builder()
    .setDataType(DataType.TYPE_NUTRITION)
    ...
    .build()

val nutrients = mapOf(
    Field.NUTRIENT_TOTAL_FAT to 0.4f,
    Field.NUTRIENT_SODIUM to 1f,
    Field.NUTRIENT_POTASSIUM to 422f
)
val banana = DataPoint.builder(nutritionSource)
    .setTimestamp(now, TimeUnit.MILLISECONDS)
    .setField(Field.FIELD_FOOD_ITEM, "banana")
    .setField(Field.FIELD_MEAL_TYPE, Field.MEAL_TYPE_SNACK)
    .setField(Field.FIELD_NUTRIENTS, nutrients)
    .build()

在應用程式中設定資料點後，您可以使用 History API 插入、讀取或刪除歷史資料。

REST

dataSources 資源包含每個資料來源的資料類型 (及其欄位清單)。建立資料來源時，您可以指定其中一個資料類型；從健身儲存庫擷取資料來源時，您可以取得資料類型的名稱和欄位清單。

舉例來說，資料來源表示法可以指定資料類型：

{
"dataStreamId": "exampleDataSourceId",
...
"dataType": {
  "name": "com.google.step_count.delta"
},
...
}

授權範圍

授權範圍涵蓋可供使用者授權應用程式存取的資料類型群組。協助使用者瞭解應用程式要存取什麼類型的資料。也能讓應用程式更容易使用這些資料，而無需核准個別資料類型。使用者會在下載應用程式後授予這些權限。

OAuth 範圍同意畫面範例
圖 2. OAuth 範圍同意畫面。

對少數使用者測試完應用程式之後，您必須根據這些資料類型的範圍要求驗證。請詳閱以上連結的資料類型頁面，瞭解各個資料類型適用的範圍。

例如，如果您的應用程式需要讀取和寫入寫入血壓，則必須宣告應用程式必須同時讀取和寫入及要求這兩個範圍。如果只是將血壓資料寫入 Google Fit 平台，只需要要求寫入範圍即可。

請以負責任的態度選擇資料類型。請勿要求各種資料類型，以防應用程式可能需要。指定的類型會決定系統提示使用者授予哪些範圍的權限。只要求應用程式需要的資料類型，讓使用者更有可能授予存取權。使用者更容易授予有限且清楚描述的範圍。

使用下表檢查應用程式需要存取的範圍是否敏感或受限 (這會決定您需要使用的驗證步驟)：

範圍 說明 類別
https://www.googleapis.com/auth/fitness.activity.read 讀取來自 Google Fit 平台的活動資料。 有限使用
https://www.googleapis.com/auth/fitness.activity.write 將活動資料寫入 Google Fit 平台 有限使用
https://www.googleapis.com/auth/fitness.blood_glucose.read 讀取來自 Google Fit 平台的血糖資料。 有限使用
https://www.googleapis.com/auth/fitness.blood_glucose.write 將血糖資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.blood_pressure.read 讀取來自 Google Fit 平台的血壓資料。 有限使用
https://www.googleapis.com/auth/fitness.blood_pressure.write 將血壓資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.body.read 讀取來自 Google Fit 平台的身體測量資料 (身高、體重、體脂肪百分比)。 有限使用
https://www.googleapis.com/auth/fitness.body.write 將身體測量資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.body_temperature.read 讀取來自 Google Fit 平台的體溫資料。 有限使用
https://www.googleapis.com/auth/fitness.body_temperature.write 將體溫資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.heart_rate.read 讀取來自 Google Fit 平台的心率資料。 有限使用
https://www.googleapis.com/auth/fitness.heart_rate.write 將心率資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.location.read 讀取來自 Google Fit 平台的位置資料。 有限使用
https://www.googleapis.com/auth/fitness.location.write 將位置資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.nutrition.read 讀取來自 Google Fit 平台的營養資料。 有限使用
https://www.googleapis.com/auth/fitness.nutrition.write 將營養資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.oxygen_saturation.read 讀取來自 Google Fit 平台的氧飽和度資料。 有限使用
https://www.googleapis.com/auth/fitness.oxygen_saturation.write 將血氧飽和度資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.reproductive_health.read 讀取來自 Google Fit 平台的生殖健康資料。 有限使用
https://www.googleapis.com/auth/fitness.reproductive_health.write 將生殖健康資料寫入 Google Fit 平台。 有限使用
https://www.googleapis.com/auth/fitness.sleep.read 讀取來自 Google Fit 平台的睡眠資料。 有限使用
https://www.googleapis.com/auth/fitness.sleep.write 將睡眠資料寫入 Google Fit 平台。 有限使用

為現有應用程式新增範圍

當您更新應用程式以要求新範圍時 (例如，新增新的睡眠或心率範圍或新增讀取範圍)，系統會提示使用者提示應用程式要求存取這些範圍，並可選擇授予或拒絕存取權。

因此，建議您只在需要時向使用者要求授權。請按照要求漸進式授權的相關規範操作。

如果能瞭解應用程式使用這些資料的原因/方式，使用者就更有可能授予權限：

  • 建議您新增畫面，警告使用者/要求他們提供這些範圍。
  • 清楚說明應用程式要求存取這些範圍/資料的原因，讓使用者在充分掌握資訊的情況下做出決定。

進一步瞭解 Android 應用程式權限的最佳做法。