Phát triển các trải nghiệm về giấc ngủ bằng Google Health API

Google Health API cung cấp các loại dữ liệu theo dõi kiểu ngủ của người dùng, bao gồm cả thời lượng, chất lượng và các chỉ số sinh lý trong thời gian nghỉ ngơi. Những chỉ số này giúp các ứng dụng cung cấp thông tin chi tiết về quá trình hồi phục, thói quen ngủ và xu hướng sức khoẻ lâu dài.

Các chỉ số sinh lý như Sự thay đổi tần số tim (HRV), Độ bão hoà oxy (SpO2) và nhịp thở được ghi lại cụ thể trong khi ngủ vì cơ thể ở trạng thái nghỉ ngơi ổn định. Điều này cho phép API ghi lại thông tin cơ bản về sức khoẻ hô hấp và hệ thần kinh tự chủ của người dùng mà không bị ảnh hưởng bởi các yếu tố gây căng thẳng vào ban ngày, hoạt động thể chất hoặc các điều kiện môi trường khác nhau.

Tìm hiểu sự khác biệt giữa các loại dữ liệu này để xác định chỉ số phù hợp với ứng dụng của bạn.

Các loại dữ liệu được hỗ trợ

API này hỗ trợ các loại dữ liệu sau đây để đo lường giấc ngủ:

Bảng: Các loại dữ liệu giấc ngủ của Google Health API
Loại dữ liệu Các thao tác
có thể thực hiện		 Phạm vi
Sự thay đổi tần số tim hằng ngày
dataType: daily-heart-rate-variability
tham số bộ lọc: daily_heart_rate_variability
Loại bản ghi: Hằng ngày

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Độ bão hoà oxy hằng ngày
dataType: daily-oxygen-saturation
tham số bộ lọc: daily_oxygen_saturation
Loại bản ghi: Hằng ngày

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Nhịp thở hằng ngày
dataType: daily-respiratory-rate
tham số bộ lọc: daily_respiratory_rate
Loại bản ghi: Hằng ngày

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Thông tin về nhiệt độ cơ thể trong lúc ngủ mỗi ngày
dataType: daily-sleep-temperature-derivations
tham số bộ lọc: daily_sleep_temperature_derivations
Loại bản ghi: Hằng ngày

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Sự thay đổi tần số tim
dataType: heart-rate-variability
tham số bộ lọc: heart_rate_variability
Loại bản ghi: Mẫu

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Độ bão hoà oxy
dataType: oxygen-saturation
tham số bộ lọc: oxygen_saturation
Loại bản ghi: Mẫu

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Tóm tắt nhịp thở khi ngủ
dataType: respiratory-rate-sleep-summary
tham số bộ lọc: respiratory_rate_sleep_summary
Loại bản ghi: Mẫu

Thiết bị tương thích
list, reconcile .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
Ngủ
dataType: sleep
tham số bộ lọc: sleep
Loại bản ghi: Phiên

Thiết bị tương thích
list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

Giấc ngủ và khoảng thời gian thức giấc ngắn

Phiên giấc ngủ (Sleep) là một sự kiện giấc ngủ riêng biệt, chẳng hạn như một giấc ngủ đêm hoặc giấc ngủ trưa. Chỉ số này bao gồm thông tin chi tiết về các giai đoạn ngủ không trùng lặp cùng với các khoảng thời gian chuyển tiếp ngắn sang trạng thái thức được gọi là thời gian thức giấc ngắn.

  • Phiên ngủ (Sleep): Biểu thị một sự kiện ngủ riêng biệt (các khoảng thời gian của giai đoạn LIGHT, DEEP, REM, AWAKE) phân vùng dòng thời gian liên tục của giấc ngủ chính.
  • Thức giấc trong thời gian ngắn (shortAwakenings): Khoảng thời gian chuyển đổi hoặc thức giấc ngắn xảy ra trong thời gian nghỉ ngơi. Không giống như các khoảng thời gian giai đoạn AWAKE tiêu chuẩn (phân chia tiến trình giai đoạn ngủ liên tục không trùng lặp), các lần thức giấc ngắn là những phân đoạn riêng biệt có thể trùng lặp với các giai đoạn ngủ xung quanh. Các chỉ số này cung cấp thông tin chi tiết về tình trạng ngủ không yên và các lần thức giấc ngắn mà không làm gián đoạn cấu trúc giai đoạn ngủ chính.

Ví dụ

{
  "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"
    }
  ]
}

Tạo một phiên ngủ

Để tạo một mục nhập phiên ngủ, hãy gửi yêu cầu POST đến điểm cuối dữ liệu sleep. Phản hồi này bao gồm trường name chứa data-point-id. Bạn có thể dùng trường này trong yêu cầu Cập nhật (Bản vá) hoặc Xoá.

Yêu cầu

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"
      }
    ]
  }
}

Phản hồi

{
  "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"
        }
      ]
    }
  }
}

Số liệu thống kê nhiệt độ khi ngủ hằng ngày

Chỉ số Nhiệt độ cơ thể khi ngủ hằng ngày đo lường sự thay đổi nhiệt độ trên da của người dùng trong khi ngủ so với nhiệt độ cơ sở của họ. Dữ liệu này thường được báo cáo mỗi ngày một lần sau một phiên ngủ chính.

Nhịp thở

Nhịp thở đo số lần thở của người dùng trong một phút. Trong khi ngủ, đây là một chỉ số quan trọng để theo dõi chất lượng giấc ngủ và những yếu tố có thể gây gián đoạn. API này hỗ trợ nhịp thở (respiratory-rate), thông tin tóm tắt hằng ngày (daily-respiratory-rate) và thông tin tóm tắt về giấc ngủ ở cấp phiên (respiratory-rate-sleep-summary).

Sự thay đổi tần số tim (HRV)

HRV đo lường sự thay đổi về khoảng thời gian giữa mỗi nhịp tim. Đây là một chỉ số quan trọng về trạng thái của hệ thần kinh tự chủ; HRV cao trong khi ngủ thường cho thấy khả năng hồi phục và chỉ số sẵn sàng tốt hơn, trong khi HRV thấp có thể cho biết tình trạng căng thẳng hoặc tập luyện quá sức. API này hỗ trợ HRV mẫu (heart-rate-variability) và thông tin tóm tắt hằng ngày (daily-heart-rate-variability).

Độ bão hoà oxy (SpO2)

SpO2 biểu thị tỷ lệ phần trăm hemoglobin bão hoà oxy so với tổng lượng hemoglobin trong máu. Việc theo dõi SpO2 trong khi ngủ là rất quan trọng để phát hiện các vấn đề tiềm ẩn về hô hấp và đảm bảo người dùng duy trì đủ lượng oxy trong suốt đêm. API này hỗ trợ SpO2 mẫu (oxygen-saturation) và thông tin tóm tắt hằng ngày (daily-oxygen-saturation).

Thông tin tổng quan về sức khoẻ giấc ngủ và khả năng hồi phục

Mặc dù mỗi chỉ số đều cung cấp thông tin chi tiết cụ thể, nhưng chúng có mối quan hệ mật thiết với nhau và cùng nhau cung cấp một cái nhìn tổng thể về quá trình phục hồi của người dùng. Các giai đoạn ngủ (Ngủ nông, Ngủ sâu, Ngủ REM) cung cấp nền tảng cấu trúc cho giấc ngủ, trong khi các chỉ số sinh lý như HRV và SpO2 cho biết cơ thể đang phản ứng về mặt thể chất với giấc ngủ đó như thế nào. Ví dụ: một phiên ngủ chất lượng cao với giấc ngủ sâu tối ưu thường tương quan với HRV cao hơn, cho thấy hệ thống thần kinh tự chủ hồi phục hiệu quả.

Việc kết hợp những dữ liệu này với dữ liệu nhịp thở và nhiệt độ khi ngủ cho phép các ứng dụng xác định những yếu tố có thể gây rối loạn. Sự gia tăng đột ngột về nhịp hô hấp hoặc sự thay đổi về nhiệt độ khi ngủ có thể cho biết lý do khiến người dùng có thể đã dành ít thời gian hơn cho các giai đoạn phục hồi. Bằng cách phân tích đồng thời các loại dữ liệu này, nhà phát triển có thể đưa ra đánh giá toàn diện về thói quen ngủ lành mạnh và xu hướng sức khoẻ lâu dài.

Nguyên tắc

Khi tích hợp chỉ số giấc ngủ vào ứng dụng, hãy áp dụng các nguyên tắc sau:

  • Thông tin chi tiết về phiên: Để hiện các giai đoạn ngủ của người dùng (Ngủ nông, Ngủ sâu, Ngủ REM, Thức) và thời gian thức ngắn, hãy truy vấn kiểu dữ liệu sleep.
  • Theo dõi sinh lý: Để theo dõi sức khoẻ nâng cao, hãy kết hợp dữ liệu phiên ngủ với các chỉ số sinh lý và phục hồi, chẳng hạn như respiratory-rate-sleep-summary, daily-sleep-temperature-derivations, daily-heart-rate-variability và daily-oxygen-saturation.
  • Đối chiếu: Sử dụng thao tác reconcile để đảm bảo rằng các nhật ký giấc ngủ trùng lặp từ nhiều thiết bị (ví dụ: thiết bị đeo và cảm biến nệm) được hợp nhất thành một bản ghi giấc ngủ "chính".

Tính tổng thời gian ngủ sâu

Cách tính tổng thời gian người dùng dành cho giai đoạn ngủ sâu phục hồi trong một đêm cụ thể:

  1. Truy vấn loại dữ liệu sleep cho phạm vi thời gian đã chỉ định.
  2. Lặp lại danh sách giai đoạn và xác định các khoảng thời gian mà stageType là DEEP.
  3. Tính thời lượng (Thời gian kết thúc – Thời gian bắt đầu) cho từng khoảng thời gian ngủ sâu và cộng các khoảng thời gian đó lại.

Tổng số thu được là tổng thời lượng ngủ sâu thực tế của phiên đó.

Trước
Các bước