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

Lần ngủ và lần 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.
  • Thức giấc vào ban đêm: Tính năng này xác định thời điểm thức giấc vào ban đêm (chẳng hạn như thức dậy để uống nước) bằng cách kết hợp dữ liệu từ các cảm biến trên thiết bị (gia tốc kế, con quay hồi chuyển và số bước). Trong Web API, các ứng dụng có thể phát hiện tình trạng thức giấc vào ban đêm bằng cách lọc các khoảng thời gian được đánh dấu bằng cấp độ "wake" (giấc ngủ thông thường) hoặc "awake" (giấc ngủ theo giai đoạn).

Ví dụ

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

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

Chỉ số về hiệu quả và độ trễ của giấc ngủ

Ngoài các giai đoạn ngủ và chỉ số sinh lý, API này còn cung cấp các chỉ số chính để định lượng chất lượng giấc ngủ và thời gian bắt đầu ngủ. Hiệu quả giấc ngủ và độ trễ khi bắt đầu ngủ là các chỉ số lâm sàng tiêu chuẩn mô tả mức độ hiệu quả của giấc ngủ so với tổng thời gian trên giường của người dùng, cung cấp thông tin chi tiết về vệ sinh giấc ngủ và mức độ nghỉ ngơi.

Điểm hiệu quả giấc ngủ

Hiệu quả giấc ngủ là một chỉ số tiêu chuẩn được xác định là tỷ lệ thời gian ngủ so với tổng thời gian nằm trên giường. API này tính toán hiệu quả giấc ngủ bằng công thức sau:

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

Điểm hiệu suất được tính ngay trước khi phân vùng cấp độ (giai đoạn) giấc ngủ. Tổng số phút ngủ được trả về trong phản hồi API (trong trường summary.minutesAsleep) phản ánh kết quả cuối cùng sau khi các cấp độ ngủ được tính toán.

Nếu người dùng hoặc nhà nghiên cứu sửa đổi thời gian bắt đầu hoặc kết thúc của nhật ký giấc ngủ theo cách thủ công, API sẽ tính toán lại điểm hiệu quả giấc ngủ và điều chỉnh các phân vùng giai đoạn theo dữ liệu cảm biến được ghi lại trong ranh giới mới của thời gian đi ngủ và thức dậy.

Độ trễ khi bắt đầu ngủ

Độ trễ khi bắt đầu ngủ đo khoảng thời gian trôi qua từ khi người dùng dự định ngủ (bắt đầu từ thời gian "lên giường" hoặc "tắt đèn") cho đến khi bắt đầu ngủ.

Đối với nhật ký được tạo tự động bằng tính năng tự động phát hiện (auto_detect), minutesToFallAsleep sẽ mặc định là 0 vì không có ý định tường minh nào về việc đi ngủ được ghi lại. Khi thời gian bắt đầu ngủ được ghi lại hoặc chỉnh sửa theo cách thủ công (chuyển đổi nhật ký thành manual), API sẽ tính toán và điền sẵn minutesToFallAsleep cùng với minutesAfterWakeup.

Hướng dẫn về việc nghiên cứu và ghi nhật ký theo cách thủ công

Khi người tham gia ghi lại hoặc điều chỉnh thời gian bắt đầu và kết thúc giấc ngủ theo cách thủ công:

  1. Việc cập nhật ranh giới trên giường sẽ thay đổi khoảng thời gian timeInBed.
  2. Các phân vùng giai đoạn và mức độ ngủ sẽ tự động điều chỉnh để đánh giá dữ liệu cảm biến trong cửa sổ mới.
  3. Điểm hiệu quả giấc ngủ, minutesToFallAsleep và minutesAfterWakeup được tính toán lại dựa trên khung thời gian mới cập nhật.

Số liệu 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.
  • Thức giấc vào ban đêm: Để theo dõi các sự kiện thức giấc vào nửa đêm mà không có luồng dữ liệu cảm biến thô, hãy kiểm tra các khoảng thời gian của giai đoạn sleep và lọc các mục có loại giai đoạn AWAKE (hoặc wake đối với nhật ký giấc ngủ thông thường).
  • Độ trễ và hiệu quả: Sử dụng minutesToFallAsleep và công thức hiệu quả giấc ngủ để phân tích độ trễ giấc ngủ. Xin lưu ý rằng minutesToFallAsleep sẽ được điền sẵn khi nhật ký giấc ngủ được chỉnh sửa theo cách thủ công hoặc được ghi lại một cách rõ ràng.
  • 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à type 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