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:系統會在建立每個資料點時指派一組專屬 ID (UID)。這對標準讀取和寫入作業來說非常實用。詳情請參閱 Health Connect ID。
- 上次修改時間:標示最後一次更新記錄的時間戳記,這會在首次建立記錄或每次更新時自動產生。
- 資料來源:Health Connect 會儲存應用程式的資料來源相關資訊。其中包含該來源的套件名稱,系統會在建立時自動加入這個名稱。
- 裝置:Health Connect 會儲存裝置的資料來源相關資訊。當中包含裝置的製造商和型號,您必須手動提供這個值。
- 用戶端 ID:Health Connect 提供用戶端 ID,可讓用戶端應用程式使用自己的 ID 參照資料,有助於解決衝突問題,並簡化同步處理程序。這項資訊須手動提供給記錄。
- 用戶端記錄版本:除了用戶端 ID 外,Health Connect 也提供版本管理功能,可協助您追蹤資料同步處理期間的變更。這項資訊須手動提供給記錄。
- 記錄方法:Health Connect 可讓您瞭解資料的記錄方式。這些方法包括以被動方式記錄資料的應用程式,以及使用者主動或手動記錄資料。
Health Connect ID
Health Connect 會為新插入的資料物件指派專屬 ID (UID),這有助於識別資料物件,並與其他物件做出區別。Health Connect ID 適合用於讀取或寫入要求。Health Connect ID 與用戶端 ID 不同。用戶端應用程式會指派用戶端 ID,Health Connect 則只會指派 Health Connect ID。
使用 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 |
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 |
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.ElevationGeted.READ
androidx.health.permission.ElevationGeted.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 資料類型的存取權」。