数据类型

Google 健身在 com.google 命名空间下提供了一组健康和保健数据类型。

数据类型定义了数据点内值的格式。数据点可以表示:

  • 瞬间阅读或观察
  • 一段时间内的汇总统计信息

Google 健身定义了即时观察的数据类型以及汇总数据的数据类型。数据点由数据类型的字段的值和时间戳信息组成。表示瞬时观察结果的点包括时间戳,汇总数据类型的点还包括间隔的开始时间。

Google 健身还允许您定义新的数据类型。

数据类型组

Google 健身提供以下数据类型:

公共数据类型
平台提供的标准数据类型带有“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"
},
...
}

授权范围

授权范围涵盖用户可以授权应用访问的数据类型组。有助于用户了解应用想要访问的数据类型。此外,借助这些 API,无需授予每种数据类型即可更轻松地向应用授予使用这些数据的权限。用户在下载您的应用后授予这些权限。

OAuth 范围意见征求屏幕示例
图 2. OAuth 范围意见征求屏幕。

在让少量用户测试您的应用后,在发布您的应用之前,您需要根据与这些数据类型相关的范围请求验证。仔细阅读上方链接的数据类型页面,了解哪些范围适用于每种数据类型。

例如,如果您的应用需要读取和写入血压,则需要声明它同时执行读取和写入请求,以及请求两个范围。如果它只将血压数据写入 Google 健身平台,则只需请求写入范围。

请以负责任的方式选择数据类型。请勿请求所有数据类型,因为您的应用可能需要这些数据。指定的类型决定了系统提示用户授予权限的范围。请只请求应用需要的数据类型,以便用户更有可能授予访问权限。用户更容易授予对有限清晰描述的范围的访问权限。

使用下表检查您的应用需要访问的范围是敏感范围还是受限范围(这决定了您需要遵循的验证步骤):

范围 说明 类别
https://www.googleapis.com/auth/fitness.activity.read 从 Google 健身平台读取活动数据。 受限
https://www.googleapis.com/auth/fitness.activity.write 将活动数据写入 Google 健身平台 受限
https://www.googleapis.com/auth/fitness.blood_glucose.read 从 Google 健身平台读取血糖数据。 受限
https://www.googleapis.com/auth/fitness.blood_glucose.write 将血糖数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.blood_pressure.read 从 Google 健身平台读取血压数据。 受限
https://www.googleapis.com/auth/fitness.blood_pressure.write 将血压数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.body.read 从 Google 健身平台读取身体测量数据(身高、体重、体脂百分比)。 受限
https://www.googleapis.com/auth/fitness.body.write 将身体测量数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.body_temperature.read 从 Google 健身平台读取体温数据。 受限
https://www.googleapis.com/auth/fitness.body_temperature.write 将体温数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.heart_rate.read 从 Google 健身平台读取心率数据。 受限
https://www.googleapis.com/auth/fitness.heart_rate.write 将心率数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.location.read 从 Google 健身平台读取位置数据。 受限
https://www.googleapis.com/auth/fitness.location.write 将位置数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.nutrition.read 从 Google 健身平台读取营养数据。 受限
https://www.googleapis.com/auth/fitness.nutrition.write 将营养数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.oxygen_saturation.read 从 Google 健身平台读取血氧饱和度数据。 受限
https://www.googleapis.com/auth/fitness.oxygen_saturation.write 将血氧饱和度数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.reproductive_health.read 从 Google 健身平台读取生殖健康数据。 受限
https://www.googleapis.com/auth/fitness.reproductive_health.write 将生殖健康数据写入 Google 健身平台。 受限
https://www.googleapis.com/auth/fitness.sleep.read 从 Google 健身平台读取睡眠数据。 受限
https://www.googleapis.com/auth/fitness.sleep.write 将睡眠数据写入 Google 健身平台。 受限

向现有应用添加新范围

当您更新应用以请求新范围时(例如,如果您添加新的睡眠或心率范围,或添加读取范围),系统会提示用户您的应用正在请求访问这些范围,他们可以选择授予或拒绝访问权限。

最佳做法是在您需要时向用户请求资源授权。请遵循请求增量授权的指南。

如果用户了解您的应用为何/如何使用这些数据,他们会更愿意授予访问权限:

  • 考虑添加一个警告/告知用户系统将询问他们需要这些范围的屏幕。
  • 明确说明应用请求访问这些范围/数据的原因,以便用户可以做出明智的决定。

详细了解有关 Android 应用权限的最佳做法