使用 Google Health API 开发睡眠体验

Google Health API 提供的数据类型可跟踪用户的睡眠模式，包括睡眠时长、睡眠质量和休息期间的生理指标。这些指标有助于应用提供有关恢复、睡眠卫生和长期健康趋势的数据分析。

心率变异性 (HRV)、血氧饱和度 (SpO2) 和呼吸频率等生理指标是在睡眠期间专门记录的，因为此时身体处于稳定的静息状态。这样，API 就可以在不受白天压力、身体活动或各种环境条件干扰的情况下，捕获用户自主神经和呼吸系统健康的基准。

了解这些数据类型之间的差异，以确定哪些指标适合您的应用。

支持的数据类型

该 API 支持以下用于测量睡眠的数据类型：

表：Google Health API 睡眠数据类型
数据类型 可用的
操作		 范围
每日心率变异性
dataType： daily-heart-rate-variability
过滤条件参数： daily_heart_rate_variability
记录类型： 每日

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日血氧饱和度
dataType： daily-oxygen-saturation
过滤条件参数： daily_oxygen_saturation
记录类型： 每日

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日呼吸频率
dataType： daily-respiratory-rate
过滤条件参数： daily_respiratory_rate
记录类型： 每日

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
每日睡眠温度偏差
dataType： daily-sleep-temperature-derivations
过滤条件参数： daily_sleep_temperature_derivations
记录类型： 每日

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
心率变异性
dataType： heart-rate-variability
过滤条件参数： heart_rate_variability
记录类型： 示例

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
血氧饱和度
dataType： oxygen-saturation
过滤条件参数： oxygen_saturation
记录类型： 示例
存储分辨率 ：1 分钟

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
呼吸频率睡眠状况摘要
dataType： respiratory-rate-sleep-summary
过滤条件参数： respiratory_rate_sleep_summary
记录类型： 示例

兼容的设备
list、reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
睡眠
dataType： sleep
过滤条件参数： sleep
记录类型： 练习

兼容的设备
list、get、reconcile、create、update、batchDelete .sleep.readonly
.sleep.writeonly

睡眠时段和短暂清醒

睡眠时段 (Sleep) 表示离散的睡眠事件，例如单次夜间睡眠或日间小憩。它包含不重叠睡眠阶段的详细细分，以及称为短暂清醒的短暂清醒过渡间隔。

  • 睡眠时段 (Sleep)：表示一个离散的睡眠事件（LIGHT、DEEP、REM、AWAKE 阶段间隔），用于划分主要休息时间的连续时间轴。
  • 短暂清醒 (shortAwakenings)：休息期间发生的短暂清醒或醒来。与标准 AWAKE 阶段间隔（划分不重叠的连续睡眠阶段进展）不同，短暂清醒是独特的片段，可以与周围的睡眠阶段重叠。它们可以精细地显示不安和微觉醒，而不会破坏主要的睡眠阶段结构。
  • 夜间醒来：通过设备端传感器融合（加速度计、陀螺仪和步数）识别夜间醒来（例如起床喝水）。应用可以通过过滤 stages 来检测夜间醒来，以查找具有 type: "AWAKE" 的时间间隔（在 CLASSIC 和 STAGES 睡眠记录中均使用），也可以通过检查 outOfBedSegments 来检测夜间醒来。

示例

{
  "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
  "sleep": {
    "interval": {
      "startTime": "2026-04-20T22:30:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-04-21T06:30:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-04-20T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-04-20T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-21T01:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      }
    ],
    "shortAwakenings": [
      {
        "startTime": "2026-04-20T23:10:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:11:30Z",
        "endUtcOffset": "-14400s",
        "type": "AWAKE"
      }
    ],
    "summary": {
      "minutesInSleepPeriod": "480",
      "minutesAsleep": "455",
      "minutesAwake": "25",
      "minutesToFallAsleep": "15",
      "minutesAfterWakeUp": "10"
    }
  }
}

创建睡眠时段

如需创建睡眠时段条目，请向 sleep 数据点端点发送 POST 请求。响应包含 name 字段，其中包含 data-point-id，可在更新（修补）或删除请求中使用。

请求

POST https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "sleep": {
    "interval": {
      "startTime": "2026-06-07T22:00:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-06-08T06:00:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-06-07T22:00:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-07T22:30:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-07T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-07T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      },
      {
        "startTime": "2026-06-07T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T02:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-08T02:15:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T02:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "REM"
      },
      {
        "startTime": "2026-06-08T02:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T05:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-06-08T05:15:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T06:00:00Z",
        "endUtcOffset": "-14400s",
        "type": "REM"
      }
    ]
  }
}

响应

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
    "sleep": {
      "interval": {
        "startTime": "2026-06-07T22:00:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-06-08T06:00:00Z",
        "endUtcOffset": "-14400s"
      },
      "type": "STAGES",
      "stages": [
        {
          "startTime": "2026-06-07T22:00:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-07T22:30:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-07T22:30:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-07T23:45:00Z",
          "endUtcOffset": "-14400s",
          "type": "DEEP"
        },
        {
          "startTime": "2026-06-07T23:45:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T02:15:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-08T02:15:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T02:45:00Z",
          "endUtcOffset": "-14400s",
          "type": "REM"
        },
        {
          "startTime": "2026-06-08T02:45:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T05:15:00Z",
          "endUtcOffset": "-14400s",
          "type": "LIGHT"
        },
        {
          "startTime": "2026-06-08T05:15:00Z",
          "startUtcOffset": "-14400s",
          "endTime": "2026-06-08T06:00:00Z",
          "endUtcOffset": "-14400s",
          "type": "REM"
        }
      ]
    }
  }
}

睡眠效率和入睡用时指标

除了睡眠阶段和生理指标外，该 API 还提供量化睡眠质量和入睡情况的关键指标。睡眠效率和入睡延迟是标准的临床指标，用于描述用户相对于其在床上的总时间的休息效率，从而提供对睡眠卫生和休息质量的洞察。

睡眠效率得分

睡眠效率是一项标准指标，定义为睡眠时间占在床上总时间的比例。该 API 使用以下公式计算睡眠效率：

Sleep Efficiency Score = round( (Total Minutes Asleep / Total Minutes In Bed) * 100 )

效率得分是在睡眠水平（阶段）划分之前计算的。API 响应中返回的总睡眠分钟数（在 summary.minutesAsleep 字段中）反映了计算睡眠水平后的最终结果。

如果用户或研究人员手动修改睡眠记录的开始或结束时间，API 会根据在新的就寝时间和起床时间范围内记录的传感器数据，重新计算睡眠效率得分并调整睡眠阶段划分。

入睡延迟

入睡潜伏期衡量的是从用户打算入睡（“上床”或“熄灯”时间开始）到入睡所经过的时间。

对于自动生成的日志（metadata.manuallyEdited 为 false），summary.minutesToFallAsleep 默认为 "0"，因为系统未记录明确的入睡意图。手动记录或修改在床开始时间（metadata.manuallyEdited 为 true）时，API 会计算并填充 summary.minutesToFallAsleep 以及 summary.minutesAfterWakeUp。

研究和手动记录指南

当参与者手动记录或调整在床开始和结束时间时：

  1. 更新在床边界会更改睡眠 interval（和 summary.minutesInSleepPeriod）。
  2. 睡眠水平和阶段划分会自动调整，以评估新时间范围内的传感器数据。
  3. 系统会根据更新后的时间范围重新得出睡眠效率得分、summary.minutesToFallAsleep和summary.minutesAfterWakeUp。

每日睡眠温度偏差

每日睡眠温度偏差用于测量用户睡眠期间的体表温度与基准温度之间的变化。此数据通常在主要睡眠时段后每天报告一次。

呼吸频率

呼吸频率测量的是用户每分钟呼吸次数。在睡眠期间，它是监测睡眠质量和潜在干扰的关键指标。该 API 支持样本呼吸频率 (respiratory-rate)、每日摘要 (daily-respiratory-rate) 和会话级睡眠状况摘要 (respiratory-rate-sleep-summary)。

心率变异性 (HRV)

HRV 测量每次心跳之间的时间变化。它是自主神经系统状态的关键指标；睡眠期间 HRV 较高通常表示恢复和准备状态较好，而 HRV 较低则可能表示压力或过度训练。该 API 支持 HRV 样本 (heart-rate-variability) 和每日摘要 (daily-heart-rate-variability)。

血氧饱和度

血氧饱和度 (SpO2) 表示血液中氧饱和血红蛋白相对于总血红蛋白的百分比。在睡眠期间监测 SpO2 有助于检测潜在的呼吸紊乱，并确认用户在夜间是否保持了充足的血氧水平。该 API 支持血氧饱和度样本 (oxygen-saturation) 和每日摘要 (daily-oxygen-saturation)。

当您查询分钟级 oxygen-saturation 时，Google Health API 仅返回经过验证的数据点，并滤除因手臂移动、手腕佩戴松动或传感器置信度低（低于 50%）而导致的无效测量值，以及与运动噪声相邻的读数。由于无效分钟数会被排除，因此分钟级覆盖率可能较低，并且预计会出现时间戳间隔。oxygen-saturation 和 daily-oxygen-saturation 都依赖于相同的经验证读数。如需详细了解验证标准，请参阅分钟级血氧饱和度过滤和数据有效性。

全面了解睡眠健康和恢复情况

虽然每个指标都提供了特定的分析洞见，但它们之间存在着密切的关联，共同构成了用户恢复情况的整体视图。睡眠阶段（浅度睡眠、深度睡眠、快速眼动睡眠）是休息的结构基础，而 HRV 和 SpO2 等生理指标则反映了身体对休息的生理反应。 例如，深层睡眠时间充足的高质量睡眠时段通常与较高的 HRV 相关，这表明自主神经系统得到了有效恢复。

将这些数据与呼吸频率和睡眠温度推导结果相结合，应用便能识别潜在的干扰因素。呼吸频率突然飙升或睡眠温度出现偏差，可以解释用户在恢复性睡眠阶段的时间为何减少。通过同时分析这些数据类型，开发者可以全面评估睡眠卫生和长期健康趋势。

指南

在应用中集成睡眠指标时，请遵循以下准则：

  • 睡眠详情：如需显示用户的睡眠阶段（浅睡眠、深睡眠、REM 快速眼动睡眠、清醒）和短暂清醒，请查询 sleep 数据类型。
  • 夜间醒来：如需在没有原始传感器数据流的情况下跟踪午夜醒来事件，请检查 sleep 阶段间隔，并过滤出包含 type: "AWAKE" 的项（适用于 STAGES 和 CLASSIC 睡眠记录），或检查 outOfBedSegments。
  • 延迟时间和效率：使用 summary.minutesToFallAsleep 和睡眠效率公式进行睡眠延迟时间分析。请注意，手动修改睡眠记录（metadata.manuallyEdited 为 true）或明确记录睡眠时，系统会填充 summary.minutesToFallAsleep。
  • 生理监测：如需进行高级健康监测，请将睡眠时段数据与生理和恢复指标（例如 respiratory-rate-sleep-summary、daily-sleep-temperature-derivations、daily-heart-rate-variability 和 daily-oxygen-saturation）相结合。
  • 协调：使用 reconcile 操作，确保将来自不同设备（例如穿戴式设备和床垫传感器）的重叠睡眠记录合并为一条“主要”睡眠记录。

计算深度睡眠总时长

如需计算用户在特定夜晚处于恢复性深度睡眠阶段的总时间，请执行以下操作：

  1. 查询指定时间范围内的 sleep 数据类型。
  2. 遍历阶段列表，并找出 type 为 DEEP 的时间间隔。
  3. 计算每个深度睡眠时间间隔的时长（结束时间 - 开始时间），然后求和。

所得总和即为该时段内深度睡眠的总实际时长。

上一页
步骤
下一页
女性健康