資料類型

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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 應用程式權限的最佳做法