使用 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
记录类型： 示例

兼容的设备
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阶段间隔（用于划分不重叠的连续睡眠阶段进展）不同，短暂清醒是可与周围睡眠阶段重叠的独特片段。它们可提供有关不安和微觉醒的精细数据，而不会干扰主要睡眠阶段结构。
  • 夜间醒来：设备端传感器融合（加速度计、陀螺仪和步数）功能可识别半夜醒来（例如起床喝水）的情况。在 Web API 中，应用可以通过过滤标记为级别 "wake"（经典睡眠）或 "awake"（阶段睡眠）的时间段来检测夜间醒来。

示例

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "minutesToFallAsleep": 15,
  "minutesAfterWakeup": 10,
  "sleepStages": [
    {
      "startTime": "2026-04-20T22:30:00Z",
      "endTime": "2026-04-20T23:45:00Z",
      "type": "LIGHT"
    },
    {
      "startTime": "2026-04-20T23:45:00Z",
      "endTime": "2026-04-21T01:15:00Z",
      "type": "DEEP"
    }
  ],
  "shortAwakenings": [
    {
      "startTime": "2026-04-20T23:10:00Z",
      "endTime": "2026-04-20T23:11:30Z",
      "type": "AWAKE"
    }
  ]
}

创建睡眠时段

如需创建睡眠时段条目，请向 sleep 数据点端点发送 POST 请求。响应中包含 name 字段，其中包含 data-point-id，该字段可用于 Update (Patch) 或 Delete 请求。

请求

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 会根据在新的就寝时间和起床时间范围内记录的传感器数据重新计算睡眠效率得分并调整睡眠阶段分区。

入睡潜伏期

入睡潜伏期是指从用户打算入睡时（“就寝”或“熄灯”时间的开始）到入睡的时间。

对于使用自动检测 (auto_detect) 自动生成的日志，minutesToFallAsleep 默认值为 0，因为未记录显式 intent 以入睡。当手动记录或修改就寝开始时间（将日志转换为 manual）时，API 会计算并填充 minutesToFallAsleep 以及 minutesAfterWakeup。

研究和手动日志记录指南

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

  1. 更新就寝边界会更改 timeInBed 时间间隔。
  2. 睡眠程度和阶段划分会自动调整，以评估新时间窗口内的传感器数据。
  3. 睡眠效率得分（minutesToFallAsleep 和 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 表示血液中氧饱和血红蛋白相对于总血红蛋白的百分比。在睡眠期间监测 SpO2 对于检测潜在的呼吸障碍至关重要，可确保用户在整个夜晚保持充足的氧气水平。该 API 支持抽样 SpO2 (oxygen-saturation) 和每日总结 (daily-oxygen-saturation)。

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

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

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

指南

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

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

计算深度睡眠总时长

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

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

所得总和即为相应时段的深度睡眠总时长。

上一页
步骤