规划和查看 Health Connect 数据类型

Health Connect 会存储健康与健身数据,并对其进行结构化处理。此外,它还会考虑不同数据类型的测量方式。这些数据类型包括立即测量的心率、一段时间内的步数以及时段中的睡眠数据。

请务必先了解 Health Connect 提供的数据类型和权限,以便规划应用的要求。因此,您需要先检查数据类型,然后才能最终确定要求。

数据类型类别

Health Connect 支持大多数健康与健身应用中使用的各种数据类型,以尽可能提供多样化的数据。Health Connect 旨在全面展示和存储健康与健身数据。这些数据类型分为以下类别:

  • 活动:用于捕获用户的所有活动数据,其中可能包括跑步、游泳和睡眠等健康与健身活动的数据。
  • 身体测量:用于捕获与身体相关的常见数据,例如用户的体重及其基础代谢率。
  • 经期记录:用于捕获月经周期和相关数据点,例如排卵检测的二元结果。
  • 营养:用于捕获饮水量和营养方面的数据。饮水量代表用户单次摄入的水量。营养包含卡路里、糖和镁等可选字段。
  • 睡眠:用于捕获与用户的睡眠时长和类型相关的区间数据。
  • 生命体征:用于捕获与用户的整体健康状况相关的重要信息,其中包括体温、血糖、血压和血氧饱和度等数据。

数据类型格式

Health Connect 中的数据类型存储在 Record 的子类对象中。

每种数据类型都有相应的关联字段,即泛型(如 timezoneOffset)或具体(如 titlecountpercentage)。有些字段使用简单类型(例如 long、double 或字符串),而有些字段使用复杂类型,例如枚举和类(例如 InstantZoneOffset)。这些字段的属性可以是必填字段,也可以是选填字段。某些属性是只读属性,某些属性会被限制在特定的值范围内。

如需查看可用数据类型及其字段的完整列表,请参阅 Jetpack 中的类。

其他数据属性

Health Connect API 中的数据还包含下表中所述的元数据属性:

  • Health Connect ID:每个数据点在创建时都分配有一个唯一标识符 (UID)。这对于标准读写操作非常有用。如需了解详情,请参阅 Health Connect ID
  • 上次修改时间:用于标记记录最后一次更新的时间戳。系统会在首次创建记录或每次更新记录时自动生成此属性。
  • 数据来源:Health Connect 会存储数据的来源应用的相关信息。它包含该来源的软件包名称,该名称会在创建时自动添加。
  • 设备:Health Connect 会存储数据的来源设备的相关信息。其中包含相应设备的制造商和型号(您将手动提供相应值)。
  • 客户端 ID:Health Connect 提供客户端 ID,让客户端应用能够使用自己的 ID 来引用数据,这有助于解决冲突和便于同步。您需要将这些信息手动提供给记录。
  • 客户端记录版本:除了客户端 ID,Health Connect 同时还会提供版本控制,以帮助在数据同步期间跟踪更改。您需要将这些信息手动提供给记录。
  • 记录方法:借助 Health Connect,您可以了解数据的记录方式。 这些方法包括应用被动(自动)记录数据,以及用户主动或手动记录数据。

Health Connect ID

Health Connect 会为新插入的数据对象分配唯一标识符 (UID),用于标识数据对象并将其与其他对象区分开来。Health Connect ID 在读取或写入请求中非常有用。Health Connect ID 与客户端 ID 不完全相同。客户端 ID 由客户端应用分配,而 Health Connect ID 由 Health Connect 专门分配。

使用 Health Connect ID 时,请注意以下几点:

  • 时段具有单个 Health Connect ID,但时段中的数据具有自己的 Health Connect ID。
  • Health Connect ID 与时间戳没有绑定或关联。
  • 某些用例可能需要在工作流中存储特定 Health Connect ID。例如,需要使用特定 ID 才能检索用户刚刚记录的数据条目并将其显示给用户。

Health Connect 中的时间

写入 Health Connect 的所有数据都必须指定时区偏移量信息。指定时区偏移量后,读取数据的应用即可以民用时间来展示相关数据。民用时间是指与用户相关的本地时间,但不一定是世界协调时间 (UTC)。

在极少数情况下,时区偏移量可能不可用。当 Android 14(API 级别 34)中发生这种情况时,Health Connect 会根据设备的系统默认时区设置时区偏移量。在 Android 13 及更低版本(API 级别 33 及更低版本)中,可以在未指定任何时区偏移量信息的情况下向 Health Connect 写入数据,但应尽可能避免这种情况。

时间和时区设置

通过在写入数据时指定时区偏移量信息,可以在读取 Health Connect 中的数据时提供时区信息。不过,该操作在某些情况下可能会失败,例如当未提供时区偏移量时。您的应用需要做好准备,从而以适合您具体情况的方式来处理这两种数据。

权限

在请求任何权限之前,您的应用必须先在清单中声明这些权限。如需了解数据类型及其权限的完整对应关系,请参阅下表。

对于 1.0.0-alpha10 及更高版本

记录类类型 读取和写入权限声明
ActiveCaloriesBurned android.permission.health.READ_ACTIVE_CALORIES_BURNED
android.permission.health.WRITE_ACTIVE_CALORIES_BURNED
BasalBodyTemperature android.permission.health.READ_BASAL_BODY_TEMPERATURE
android.permission.health.WRITE_BASAL_BODY_TEMPERATURE
BasalMetabolicRate android.permission.health.READ_BASAL_METABOLIC_RATE
android.permission.health.WRITE_BASAL_METABOLIC_RATE
BloodGlucose android.permission.health.READ_BLOOD_GLUCOSE
android.permission.health.WRITE_BLOOD_GLUCOSE
BloodPressure android.permission.health.READ_BLOOD_PRESSURE
android.permission.health.WRITE_BLOOD_PRESSURE
BodyFat android.permission.health.READ_BODY_FAT
android.permission.health.WRITE_BODY_FAT
BodyTemperature android.permission.health.READ_BODY_TEMPERATURE
android.permission.health.WRITE_BODY_TEMPERATURE
BodyWaterMass android.permission.health.READ_BODY_WATER_MASS
android.permission.health.WRITE_BODY_WATER_MASS
BoneMass android.permission.health.READ_BONE_MASS
android.permission.health.WRITE_BONE_MASS
CervicalMucus android.permission.health.READ_CERVICAL_MUCUS
android.permission.health.WRITE_CERVICAL_MUCUS
CyclingPedalingCadence android.permission.health.READ_EXERCISE
android.permission.health.WRITE_EXERCISE
Distance android.permission.health.READ_DISTANCE
android.permission.health.WRITE_DISTANCE
ElevationGained android.permission.health.READ_ELEVATION_GAINED
android.permission.health.WRITE_ELEVATION_GAINED
ExerciseSession android.permission.health.READ_EXERCISE
android.permission.health.WRITE_EXERCISE
FloorsClimbed android.permission.health.READ_FLOORS_CLIMBED
android.permission.health.WRITE_FLOORS_CLIMBED
HeartRate android.permission.health.READ_HEART_RATE
android.permission.health.WRITE_HEART_RATE
HeartRateVariabilityRmssd android.permission.health.READ_HEART_RATE_VARIABILITY
android.permission.health.WRITE_HEART_RATE_VARIABILITY
Height android.permission.health.READ_HEIGHT
android.permission.health.WRITE_HEIGHT
Hydration android.permission.health.READ_HYDRATION
android.permission.health.WRITE_HYDRATION
IntermenstrualBleeding android.permission.health.READ_INTERMENSTRUAL_BLEEDING
android.permission.health.WRITE_INTERMENSTRUAL_BLEEDING
LeanBodyMass android.permission.health.READ_LEAN_BODY_MASS
android.permission.health.WRITE_LEAN_BODY_MASS
MenstruationFlow android.permission.health.READ_MENSTRUATION
android.permission.health.WRITE_MENSTRUATION
MenstruationPeriod android.permission.health.READ_MENSTRUATION
android.permission.health.WRITE_MENSTRUATION
Nutrition android.permission.health.READ_NUTRITION
android.permission.health.WRITE_NUTRITION
OvulationTest android.permission.health.READ_OVULATION_TEST
android.permission.health.WRITE_OVULATION_TEST
OxygenSaturation android.permission.health.READ_OXYGEN_SATURATION
android.permission.health.WRITE_OXYGEN_SATURATION
PlannedExercise android.permission.health.READ_PLANNED_EXERCISE
android.permission.health.WRITE_PLANNED_EXERCISE
Power android.permission.health.READ_POWER
android.permission.health.WRITE_POWER
RespiratoryRate android.permission.health.READ_RESPIRATORY_RATE
android.permission.health.WRITE_RESPIRATORY_RATE
RestingHeartRate android.permission.health.READ_RESTING_HEART_RATE
android.permission.health.WRITE_RESTING_HEART_RATE
SexualActivity android.permission.health.READ_SEXUAL_ACTIVITY
android.permission.health.WRITE_SEXUAL_ACTIVITY
SkinTemperature androidx.health.permission.SkinTemperature.READ
androidx.health.permission.SkinTemperature.WRITE
SleepSession android.permission.health.READ_SLEEP
android.permission.health.WRITE_SLEEP
Speed android.permission.health.READ_SPEED
android.permission.health.WRITE_SPEED
StepsCadence android.permission.health.READ_STEPS
android.permission.health.WRITE_STEPS
Steps android.permission.health.READ_STEPS
android.permission.health.WRITE_STEPS
TotalCaloriesBurned android.permission.health.READ_TOTAL_CALORIES_BURNED
android.permission.health.WRITE_TOTAL_CALORIES_BURNED
Vo2Max android.permission.health.READ_VO2_MAX
android.permission.health.WRITE_VO2_MAX
Weight android.permission.health.READ_WEIGHT
android.permission.health.WRITE_WEIGHT
WheelchairPushes android.permission.health.READ_WHEELCHAIR_PUSHES
android.permission.health.WRITE_WHEELCHAIR_PUSHES

对于 1.0.0-alpha09 及更低版本

记录类类型 读取和写入权限声明
ActiveCaloriesBurned androidx.health.permission.ActiveCaloriesBurned.READ
androidx.health.permission.ActiveCaloriesBurned.WRITE
BasalBodyTemperature androidx.health.permission.BasalBodyTemperature.READ
androidx.health.permission.BasalBodyTemperature.WRITE
BasalMetabolicRate androidx.health.permission.BasalMetabolicRate.READ
androidx.health.permission.BasalMetabolicRate.WRITE
BloodGlucose androidx.health.permission.BloodGlucose.READ
androidx.health.permission.BloodGlucose.WRITE
BloodPressure androidx.health.permission.BloodPressure.READ
androidx.health.permission.BloodPressure.WRITE
BodyFat androidx.health.permission.BodyFat.READ
androidx.health.permission.BodyFat.WRITE
BodyTemperature androidx.health.permission.BodyTemperature.READ
androidx.health.permission.BodyTemperature.WRITE
BodyWaterMass androidx.health.permission.BodyWaterMass.READ
androidx.health.permission.BodyWaterMass.WRITE
BoneMass androidx.health.permission.BoneMass.READ
androidx.health.permission.BoneMass.WRITE
CervicalMucus androidx.health.permission.CervicalMucus.READ
androidx.health.permission.CervicalMucus.WRITE
CyclingPedalingCadence androidx.health.permission.CyclingPedalingCadence.READ
androidx.health.permission.CyclingPedalingCadence.WRITE
Distance androidx.health.permission.Distance.READ
androidx.health.permission.Distance.WRITE
ElevationGained androidx.health.permission.ElevationGained.READ
androidx.health.permission.ElevationGained.WRITE
ExerciseSession androidx.health.permission.ExerciseSession.READ
androidx.health.permission.ExerciseSession.WRITE
FloorsClimbed androidx.health.permission.FloorsClimbed.READ
androidx.health.permission.FloorsClimbed.WRITE
HeartRate androidx.health.permission.HeartRate.READ
androidx.health.permission.HeartRate.WRITE
HeartRateVariabilityRmssd androidx.health.permission.HeartRateVariabilityRmssd.READ
androidx.health.permission.HeartRateVariabilityRmssd.WRITE
Height androidx.health.permission.Height.READ
androidx.health.permission.Height.WRITE
Hydration androidx.health.permission.Hydration.READ
androidx.health.permission.Hydration.WRITE
IntermenstrualBleeding androidx.health.permission.IntermenstrualBleeding.READ
androidx.health.permission.IntermenstrualBleeding.WRITE
LeanBodyMass androidx.health.permission.LeanBodyMass.READ
androidx.health.permission.LeanBodyMass.WRITE
MenstruationFlow androidx.health.permission.MenstruationFlow.READ
androidx.health.permission.MenstruationFlow.WRITE
Nutrition androidx.health.permission.Nutrition.READ
androidx.health.permission.Nutrition.WRITE
OvulationTest androidx.health.permission.OvulationTest.READ
androidx.health.permission.OvulationTest.WRITE
OxygenSaturation androidx.health.permission.OxygenSaturation.READ
androidx.health.permission.OxygenSaturation.WRITE
Power androidx.health.permission.Power.READ
androidx.health.permission.Power.WRITE
RespiratoryRate androidx.health.permission.RespiratoryRate.READ
androidx.health.permission.RespiratoryRate.WRITE
RestingHeartRate androidx.health.permission.RestingHeartRate.READ
androidx.health.permission.RestingHeartRate.WRITE
SexualActivity androidx.health.permission.SexualActivity.READ
androidx.health.permission.SexualActivity.WRITE
SleepSession androidx.health.permission.SleepSession.READ
androidx.health.permission.SleepSession.WRITE
Speed androidx.health.permission.Speed.READ
androidx.health.permission.Speed.WRITE
StepsCadence androidx.health.permission.StepsCadence.READ
androidx.health.permission.StepsCadence.WRITE
Steps androidx.health.permission.Steps.READ
androidx.health.permission.Steps.WRITE
TotalCaloriesBurned androidx.health.permission.TotalCaloriesBurned.READ
androidx.health.permission.TotalCaloriesBurned.WRITE
Vo2Max androidx.health.permission.Vo2Max.READ
androidx.health.permission.Vo2Max.WRITE
Weight androidx.health.permission.Weight.READ
androidx.health.permission.Weight.WRITE
WheelchairPushes androidx.health.permission.WheelchairPushes.READ
androidx.health.permission.WheelchairPushes.WRITE

查看您的数据类型和权限

现在,您已规划好数据类型和权限,接下来可以在开发期间实现它们。

在将应用上传到 Play 商店之前,请仔细检查应用所需的数据类型和权限列表。这样,您就可以准确声明应用的数据使用方式

当您准备将应用发布到 Play 商店时,请声明对应用使用的 Health Connect 数据类型的访问权限。否则,系统可能会向用户显示错误消息,指出您的应用无法访问 Health Connect 数据类型,因为它们需要获得特殊批准。