使用 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阶段间隔（用于划分不重叠的连续睡眠阶段进展）不同，短暂清醒是可与周围睡眠阶段重叠的独特片段。它们可提供有关不安和微觉醒的精细数据，而不会干扰主要睡眠阶段结构。

示例

{
  "name": "sleeps/12345",
  "startTime": "2026-04-20T22:30:00Z",
  "endTime": "2026-04-21T06:30:00Z",
  "sleepType": "STAGES",
  "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 支持采样呼吸频率 (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 数据类型。
  • 生理监测：如需进行高级健康监测，请将睡眠时段数据与生理和恢复指标（例如 respiratory-rate-sleep-summary、daily-sleep-temperature-derivations、daily-heart-rate-variability 和 daily-oxygen-saturation）相结合。
  • 协调：使用 reconcile 操作可确保将来自不同设备（例如穿戴式设备和床垫传感器）的重叠睡眠日志合并为一条“主要”睡眠记录。

计算深度睡眠总时长

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

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

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

上一页
步骤