تطوير تجارب النوم باستخدام Google Health API

توفّر Google Health API أنواع بيانات تتتبّع أنماط نوم المستخدم، بما في ذلك المدة والجودة والمقاييس الفيزيولوجية أثناء الراحة. تساعد هذه المقاييس التطبيقات في تقديم إحصاءات حول التعافي ونظافة النوم والمؤشرات الصحية الطويلة الأمد.

يتم تسجيل المقاييس الفيزيولوجية، مثل تغيُّر معدّل نبضات القلب (HRV) وتشبع الأكسجين (SpO2) ومعدّل التنفس، أثناء النوم تحديدًا لأنّ الجسم يكون في حالة راحة مستقرة. يتيح ذلك لواجهة برمجة التطبيقات تسجيل بيانات أساسية عن صحة الجهاز العصبي اللاإرادي والجهاز التنفسي للمستخدم بدون تداخل عوامل الإجهاد أثناء النهار أو النشاط البدني أو الظروف البيئية المختلفة.

ننصحك بالتعرّف على الاختلافات بين أنواع البيانات هذه لتحديد المقاييس المناسبة لتطبيقك.

أنواع البيانات المتوافقة

تتيح واجهة برمجة التطبيقات أنواع البيانات التالية لقياس النوم:

الجدول: أنواع بيانات النوم في Google Health API
نوع البيانات
العمليات المتاحة		 النطاق
تغيُّر معدّل نبضات القلب اليومي
نوع البيانات: daily-heart-rate-variability
مَعلمة الفلتر: daily_heart_rate_variability
نوع السجلّ: يومي

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
تشبّع الدم بالأكسجين يوميًا
نوع البيانات: daily-oxygen-saturation
مَعلمة الفلتر: daily_oxygen_saturation
نوع السجلّ: يومي

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
معدّل التنفس اليومي
نوع البيانات: daily-respiratory-rate
مَعلمة الفلتر: daily_respiratory_rate
نوع السجلّ: يومي

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
البيانات المشتقة اليومية لدرجة حرارة الجسم أثناء النوم
نوع البيانات: daily-sleep-temperature-derivations
مَعلمة الفلتر: daily_sleep_temperature_derivations
نوع السجلّ: يومي

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
تغيُّر معدّل نبضات القلب
نوع البيانات: heart-rate-variability
مَعلمة الفلتر: heart_rate_variability
نوع السجلّ: عينة

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
تشبّع الأكسجين
نوع البيانات: oxygen-saturation
مَعلمة الفلتر: oxygen_saturation
نوع السجلّ: عينة

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
ملخّص جودة ومدة النوم ومعدّل التنفس
نوع البيانات: respiratory-rate-sleep-summary
مَعلمة الفلتر: respiratory_rate_sleep_summary
نوع السجلّ: عينة

الأجهزة المتوافقة
قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
النوم
نوع البيانات: 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"
    }
  ]
}

إنشاء جلسة نوم

لإنشاء إدخال لجلسة نوم، أرسِل طلب POST إلى نقطة نهاية sleep لبيانات النوم. تتضمّن الاستجابة الحقل 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"
        }
      ]
    }
  }
}

مقاييس فعالية النوم ووقت الاستجابة

بالإضافة إلى مراحل النوم والمقاييس الفسيولوجية، توفّر واجهة برمجة التطبيقات مقاييس أساسية تحدّد جودة النوم وبدايته. فعالية النوم ومدة الاستغراق في النوم هما مقياسان سريريان معياران يوضّحان مدى فعالية استراحة المستخدم مقارنةً بإجمالي الوقت الذي يقضيه في السرير، ما يقدّم إحصاءات حول صحة النوم ومدى الاسترخاء.

نتيجة فعالية النوم

فعالية النوم هي مقياس معياري يُعرَّف بأنّه نسبة الوقت الذي تقضيه نائمًا إلى إجمالي الوقت الذي تقضيه في السرير. تحسب واجهة برمجة التطبيقات كفاءة النوم باستخدام الصيغة التالية:

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

يتم احتساب نتيجة الفعالية قبل تقسيم مستويات النوم (المراحل). تعكس إجمالي عدد دقائق النوم التي تم عرضها في الردّ من واجهة برمجة التطبيقات (في الحقل summary.minutesAsleep) النتيجة النهائية بعد احتساب مستويات النوم.

إذا عدّل مستخدم أو باحث يدويًا وقت بدء جلسة نوم أو وقت الانتهاء منها، ستعيد واجهة برمجة التطبيقات احتساب النتيجة فعالية النوم وتعدّل أقسام المراحل وفقًا لبيانات جهاز الاستشعار المسجّلة ضمن حدود وقت النوم والاستيقاظ الجديدة.

مدة الاستغراق في النوم

تقيس مدة الاستعداد للنوم الوقت المنقضي منذ أن يقرّر المستخدم النوم (بداية وقت "الاستعداد للنوم" أو "إطفاء الأنوار") إلى أن يبدأ النوم.

بالنسبة إلى السجلات التي يتم إنشاؤها تلقائيًا باستخدام ميزة "الرصد التلقائي" (auto_detect)، يتم ضبط minutesToFallAsleep تلقائيًا على 0 لأنّه لم يتم تسجيل أي نية واضحة للنوم. عند تسجيل أوقات بدء النوم أو تعديلها يدويًا (تحويل السجلّ إلى manual)، تحسب واجهة برمجة التطبيقات minutesToFallAsleep وتملأها مع minutesAfterWakeup.

إرشادات حول البحث والتسجيل اليدوي

عندما يسجّل المشاركون يدويًا أوقات البدء والانتهاء في السرير أو يضبطونها:

  1. يؤدي تعديل حدود النوم إلى تغيير الفاصل الزمني timeInBed.
  2. يتم تعديل مستويات النوم وتقسيمات المراحل تلقائيًا لتقييم بيانات المستشعر ضمن النافذة الجديدة.
  3. يتم إعادة احتساب نتائج فعالية النوم، minutesToFallAsleep، وminutesAfterWakeup استنادًا إلى الفترة الزمنية المعدَّلة.

القيم المشتقة اليومية لدرجة حرارة الجسم أثناء النوم

تقيس مشتقات درجة حرارة النوم اليومية التغيّر في درجة حرارة جلد المستخدم أثناء النوم مقارنةً بدرجة حرارة جسمه الطبيعية. ويتم عادةً تسجيل هذه البيانات مرة واحدة في اليوم بعد جلسة نوم رئيسية.

معدّل التنفس

يقيس معدّل التنفس عدد الأنفاس التي يتنفسها المستخدم في الدقيقة. أثناء النوم، يشكّل معدّل ضربات القلب مقياسًا أساسيًا لتتبُّع جودة النوم والاضطرابات المحتملة. تتيح واجهة برمجة التطبيقات عينات معدّل التنفس (respiratory-rate) والملخّصات اليومية (daily-respiratory-rate) وملخّصات النوم على مستوى الجلسة (respiratory-rate-sleep-summary).

تغيُّر معدّل نبضات القلب (HRV)

يقيس تغيُّر معدّل نبضات القلب (HRV) التغيّر في الوقت بين كل نبضتَين. وهو مؤشر رئيسي على حالة الجهاز العصبي اللاإرادي، إذ يشير معدل ضربات القلب المتغير المرتفع أثناء النوم بشكل عام إلى تحسّن التعافي والاستعداد، بينما يشير معدل ضربات القلب المتغير المنخفض إلى الإجهاد أو الإفراط في التدريب. تتيح واجهة برمجة التطبيقات الحصول على عيّنات من بيانات معدّل ضربات القلب (heart-rate-variability) وملخّصات يومية (daily-heart-rate-variability).

نسبة الأكسجين في الدم (SpO2)

تمثّل نسبة الأكسجين في الدم النسبة المئوية للهيموغلوبين المشبّع بالأكسجين مقارنةً بإجمالي الهيموغلوبين في الدم. تُعد مراقبة نسبة الأكسجين بالدم أثناء النوم أمرًا بالغ الأهمية لرصد أي اضطرابات محتملة في التنفس وضمان الحفاظ على مستويات الأكسجين الكافية طوال الليل. تتيح واجهة برمجة التطبيقات الحصول على عيّنات من مستوى تشبّع الدم بالأكسجين (SpO2) (oxygen-saturation) والملخّصات اليومية (daily-oxygen-saturation).

نظرة شاملة على جودة النوم والتعافي

على الرغم من أنّ كل مقياس يقدّم إحصاءات محدّدة، فإنّها مرتبطة ببعضها بشكل كبير وتوفّر معًا نظرة شاملة على عملية استرداد المستخدم. توفّر مراحل النوم (الخفيف والعميق ونوم حركة العين السريعة) الأساس البنيوي للراحة، بينما تشير المؤشرات الفيزيولوجية، مثل معدل ضربات القلب المتغير ومستوى تشبّع الدم بالأكسجين، إلى كيفية استجابة الجسم للراحة. على سبيل المثال، يرتبط النوم الجيد الذي يتضمّن فترة نوم عميق مثالية غالبًا بمعدّل ضربات القلب المتغيّر الأعلى، ما يشير إلى التعافي الفعّال للجهاز العصبي اللاإرادي.

ويتيح الجمع بين هذه البيانات واشتقاقات معدّل التنفس ودرجة حرارة الجسم أثناء النوم للتطبيقات تحديد الاضطرابات المحتملة. يمكن أن يوضّح الارتفاع المفاجئ في معدّل التنفس أو الانحراف في درجة حرارة الجسم أثناء النوم سبب قضاء المستخدم وقتًا أقل في مراحل النوم المجدِّدة للنشاط. ومن خلال تحليل هذه الأنواع من البيانات معًا، يمكن للمطوّرين تقديم تقييم شامل لعادات النوم الصحية والمؤشرات الصحية على المدى الطويل.

الإرشادات

عند دمج مقاييس النوم في تطبيقك، اتّبِع الإرشادات التالية:

  • تفاصيل الجلسة: لعرض مراحل نوم المستخدم (النوم الخفيف والعميق وحركة العين السريعة والاستيقاظ) والاستيقاظات القصيرة، استخدِم طلب البحث لنوع البيانات 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. احتساب المدة (وقت النهاية - وقت البدء) لكل فاصل زمني للنوم العميق وجمعها

ويوفّر المجموع الناتج إجمالي المدة الفعلية للنوم العميق خلال تلك الجلسة.

السابق
الخطوات