数据类型

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"
},
...
}

授权范围

授权范围涵盖用户可以授权应用访问的数据类型组。有助于用户了解应用需要访问的数据类型。还可以更轻松地授予应用使用相应数据的权限,因为无需逐一批准每种数据类型。用户在下载您的应用后授予这些权限。

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 应用权限最佳做法