規劃及查看 Health Connect 資料類型

健康資料同步會儲存及建構健康與健身資料，也會控管不同資料類型的測量方式。這些資料類型包括立即測量的心率、經過一段時間的步數計算，以及在睡眠時段取得的睡眠資料。

請務必先瞭解 Health Connect 提供的資料類型和權限，再規劃應用程式的需求。因此，您必須先檢查資料類型，才能完成需求。

資料類型類別

Health Connect 支援多數健康與健身應用程式使用的資料類型，盡可能提供多樣化的資料。健康資料同步致力於提供全方位健康與健身資料的總覽與儲存。這些資料類型可分為以下幾類：

  • 活動：擷取使用者進行的任何活動，可以包括各種健康與健身活動，例如跑步和游泳。
  • 身體測量：擷取與身體相關的常見資料，例如使用者的體重和基礎代謝率。
  • 週期追蹤：擷取月經週期及相關資料點，例如排卵測試的二元結果。
  • 營養：擷取水份和營養資料類型，前者代表使用者一次飲用的水量，後者則有卡路里、糖和鎂等選用欄位。
  • 睡眠：擷取與使用者睡眠長度和睡眠類型相關的區間資料。
  • 生命徵象：擷取使用者重要的總體健康資訊，包括體溫、血糖、血壓和血氧濃度等資料。

資料類型格式

Health Connect 中的資料類型會儲存在 Record 的子類別物件中。

每種資料類型都有相關聯的欄位，可能是 time 和 zoneOffset 等一般欄位，也可能是 title、count 和 percentage 等特定欄位。部分欄位使用簡單型別 (例如 long、double 或 string)，其他欄位則使用複雜型別，例如列舉和類別 (如 Instant 和 ZoneOffset)。這些欄位的屬性可以是必填或選填。部分屬性為唯讀，部分屬性則會限制在特定值範圍內。

如需可用資料類型及其欄位的完整清單，請參閱 Jetpack 中的類別。

其他資料屬性

Health Connect API 中的資料也會提供以下清單中描述的中繼資料屬性：

  • Health Connect ID：系統會在建立每個資料點時指派一組專屬 ID (UID)。這適用於標準讀取和寫入作業。詳情請參閱「健康資料同步 ID」。
  • 上次修改時間：標示最後一次更新記錄的時間戳記，這會在首次建立記錄或每次更新時自動產生。
  • 資料來源：Health Connect 會儲存應用程式的資料來源相關資訊。這項屬性會顯示系統在建立來源時自動加入的來源套件名稱。
  • 裝置：Health Connect 會儲存裝置的資料來源相關資訊。這項屬性會顯示您手動提供的裝置製造商和型號。
  • 用戶端 ID：Health Connect 會提供用戶端 ID，方便用戶端應用程式使用自己的 ID 參照資料，協助解決衝突問題並簡化同步處理程序。這項資訊須手動提供給記錄。
  • 用戶端記錄版本：除了用戶端 ID 外，健康資料同步也提供版本管理功能，可協助您追蹤資料同步處理期間的變更。這項資訊須手動提供給記錄。
  • 記錄方式：透過「健康資料同步」，你可以瞭解資料的記錄方式。 這些方法包括應用程式被動 (自動) 記錄資料，以及使用者主動或手動記錄資料。

健康資料同步 ID

Health Connect 會為新插入的資料物件指派專屬 ID (UID)，用來識別資料物件並與其他物件區分。在讀取或寫入要求中，Health Connect ID 很有用。健康資料同步 ID 與用戶端 ID 不同。用戶端應用程式會指派用戶端 ID，而 Health Connect 則會指派專屬的 Health Connect ID。

使用健康資料同步 ID 時，請注意以下幾點：

  • 工作階段有單一健康資料同步 ID，但工作階段內的資料各有專屬的健康資料同步 ID。
  • 「健康資料同步」ID 與時間戳記之間沒有關聯，也不相關。
  • 某些用途可能需要在工作流程中儲存特定的「健康資料同步」ID。舉例來說，如要擷取並向使用者顯示剛記錄的資料項目，就必須使用特定 ID。

Health Connect 中的時間

所有寫入健康資料同步的資料都必須指定時區偏移資訊。指定時區偏移，可讓應用程式讀取資料並以民用時間表示資料。「民用時間」是指與使用者相關的當地時間，不一定是世界標準時間 (UTC)。

在極少數情況下，您可能無法使用時區偏移。在 Android 14 (API 級別 34) 中發生這種情況時，健康資料同步會根據裝置的系統預設時區設定時區偏移量。在 Android 13 以下版本 (API 級別 33 以下) 中，即使沒有指定任何時區偏移資訊，也可以寫入健康資料同步，但請盡量避免這種做法。

設定時間和時區

在寫入資料時指定時區偏移資訊，就能在讀取 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_EXERCISE
android.permission.health.WRITE_EXERCISE
距離 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
HeartRateVariabilityRmssd android.permission.health.READ_HEART_RATE_VARIABILITY
android.permission.health.WRITE_HEART_RATE_VARIABILITY
高度 android.permission.health.READ_HEIGHT
android.permission.health.WRITE_HEIGHT
補水 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
營養 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
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
速度 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
android.permission.health.WRITE_STEPS
TotalCaloriesBurned android.permission.health.READ_TOTAL_CALORIES_BURNED
android.permission.health.WRITE_TOTAL_CALORIES_BURNED
最大攝氧量 android.permission.health.READ_VO2_MAX
android.permission.health.WRITE_VO2_MAX
重量 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.Exercise.READ
androidx.health.permission.Exercise.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
HeartRateVariabilityRmssd androidx.health.permission.HeartRateVariability.READ
androidx.health.permission.HeartRateVariability.WRITE
高度 androidx.health.permission.Height.READ
androidx.health.permission.Height.WRITE
補水 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
營養 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
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
速度 androidx.health.permission.Speed.READ
androidx.health.permission.Speed.WRITE
步驟 androidx.health.permission.Steps.READ
androidx.health.permission.Steps.WRITE
StepsCadence androidx.health.permission.Steps.READ
androidx.health.permission.Steps.WRITE
TotalCaloriesBurned androidx.health.permission.TotalCaloriesBurned.READ
androidx.health.permission.TotalCaloriesBurned.WRITE
最大攝氧量 androidx.health.permission.VO2Max.READ
androidx.health.permission.VO2Max.WRITE
重量 androidx.health.permission.Weight.READ
androidx.health.permission.Weight.WRITE
WheelchairPushes androidx.health.permission.WheelchairPushes.READ
androidx.health.permission.WheelchairPushes.WRITE

查看資料類型和權限

規劃好資料類型和權限後，您可以在開發期間實作這些項目。

將應用程式上傳至 Play 商店前，請先仔細檢查應用程式所需的資料類型和權限清單。這樣您就能準確聲明應用程式的資料使用方式。

準備將應用程式發布至 Play 商店時，請聲明應用程式存取「健康資料同步」資料類型。否則，系統可能會向使用者顯示錯誤訊息，指出應用程式無法存取需要特別核准的「健康資料同步」資料類型。