规划和查看 Health Connect 数据类型

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

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

数据类型类别

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

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

数据类型格式

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

对于每种数据类型，都有相关联的字段，这些字段既可以是通用字段（例如 time 和 zoneOffset），也可以是特定字段（例如 title、count 和 percentage）。有些字段使用简单类型（例如 long、double 或字符串），而有些字段使用复杂类型，例如枚举和类（例如 Instant 和 ZoneOffset）。这些字段的属性可以是必需属性，也可以是可选属性。某些属性是只读属性，某些属性会被限制在特定的值范围内。

如需查看可用数据类型及其字段的完整列表，请参阅 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 及更高版本

权限参考 读取权限声明
后台读取 android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND
历史记录读取 android.permission.health.READ_HEALTH_DATA_HISTORY

记录类类型 读取和写入权限声明
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_CYCLING_PEDALING_CADENCE
android.permission.health.WRITE_CYCLING_PEDALING_CADENCE
距离 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.READ_EXERCISE_ROUTE
android.permission.health.WRITE_EXERCISE
android.permission.health.WRITE_EXERCISE_ROUTE

锻炼类型

EXERCISE_TYPE_BIKING
EXERCISE_TYPE_BIKING_HAND
EXERCISE_TYPE_BIKING_MOUNTAIN
EXERCISE_TYPE_BIKING_ROAD
EXERCISE_TYPE_BIKING_SPINNING
EXERCISE_TYPE_BIKING_STATIONARY
EXERCISE_TYPE_BIKING_UTURN
EXERCISE_TYPE_CANOEING
EXERCISE_TYPE_CROSSFIT
EXERCISE_TYPE_DANCING
EXERCISE_TYPE_ELLIPTICAL
EXERCISE_TYPE_GOLF
EXERCISE_TYPE_HORSEBACK_RIDING
EXERCISE_TYPE_KAYAKING
EXERCISE_TYPE_KICKBOXING
EXERCISE_TYPE_MARTIAL_ARTS
EXERCISE_TYPE_PILATES
EXERCISE_TYPE_ROLLERBLADING
EXERCISE_TYPE_RUNNING
EXERCISE_TYPE_RUNNING_JOGGING
EXERCISE_TYPE_RUNNING_SAND
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
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
MindfulnessSession android.permission.health.READ_MINDFULNESS
android.permission.health.WRITE_MINDFULNESS
Nutrition android.permission.health.READ_NUTRITION
android.permission.health.WRITE_NUTRITION
OvulationTest android.permission.health.READ_OVULATION_TEST
android.permission.health.WRITE_OVULATION_TEST
PlannedExerciseSession android.permission.health.READ_PLANNED_EXERCISE
android.permission.health.WRITE_PLANNED_EXERCISE
电源 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 android.permission.health.READ_SKIN_TEMPERATURE
android.permission.health.WRITE_SKIN_TEMPERATURE
SleepSession android.permission.health.READ_SLEEP
android.permission.health.WRITE_SLEEP
Speed android.permission.health.READ_SPEED
android.permission.health.WRITE_SPEED
步骤 android.permission.health.READ_STEPS
android.permission.health.WRITE_STEPS
StepsCadence android.permission.health.READ_STEPS_CADENCE
android.permission.health.WRITE_STEPS_CADENCE
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
距离 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

锻炼类型

EXERCISE_TYPE_BIKING
EXERCISE_TYPE_BIKING_HAND
EXERCISE_TYPE_BIKING_MOUNTAIN
EXERCISE_TYPE_BIKING_ROAD
EXERCISE_TYPE_BIKING_SPINNING
EXERCISE_TYPE_BIKING_STATIONARY
EXERCISE_TYPE_BIKING_UTURN
EXERCISE_TYPE_CANOEING
EXERCISE_TYPE_CROSSFIT
EXERCISE_TYPE_DANCING
EXERCISE_TYPE_ELLIPTICAL
EXERCISE_TYPE_GOLF
EXERCISE_TYPE_HORSEBACK_RIDING
EXERCISE_TYPE_KAYAKING
EXERCISE_TYPE_KICKBOXING
EXERCISE_TYPE_MARTIAL_ARTS
EXERCISE_TYPE_PILATES
EXERCISE_TYPE_ROLLERBLADING
EXERCISE_TYPE_RUNNING
EXERCISE_TYPE_RUNNING_JOGGING
EXERCISE_TYPE_RUNNING_SAND
FloorsClimbed androidx.health.permission.FloorsClimbed.READ
androidx.health.permission.FloorsClimbed.WRITE
HeartRate androidx.health.permission.HeartRate.READ
androidx.health.permission.HeartRate.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.Menstruation.READ
androidx.health.permission.Menstruation.WRITE
Nutrition androidx.health.permission.Nutrition.READ
androidx.health.permission.Nutrition.WRITE
OvulationTest androidx.health.permission.OvulationTest.READ
androidx.health.permission.OvulationTest.WRITE
PlannedExerciseSession androidx.health.permission.PlannedExerciseSession.READ
androidx.health.permission.PlannedExerciseSession.WRITE
电源 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
步骤 androidx.health.permission.Steps.READ
androidx.health.permission.Steps.WRITE
StepsCadence androidx.health.permission.StepsCadence.READ
androidx.health.permission.StepsCadence.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 数据类型，因为这些数据类型需要获得特殊批准。