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

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

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

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

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

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

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

الأجهزة المتوافقة

قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
نسبة الأكسجين في الدم يوميًا
dataType: daily-oxygen-saturation
filter parameter: daily_oxygen_saturation
نوع السجلّ: يومي

الأجهزة المتوافقة

قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
معدّل التنفس اليومي
dataType: daily-respiratory-rate
filter parameter: daily_respiratory_rate
نوع السجلّ: يومي

الأجهزة المتوافقة

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

الأجهزة المتوافقة

قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
تغيُّر معدّل نبضات القلب
dataType: heart-rate-variability
filter parameter: heart_rate_variability
نوع السجلّ: نموذج

الأجهزة المتوافقة

قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
نسبة الأكسجين في الدم
dataType: oxygen-saturation
filter parameter: oxygen_saturation
نوع السجلّ: نموذج
دقة التخزين: دقيقة واحدة

الأجهزة المتوافقة

قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
ملخّص جودة ومدة النوم استنادًا إلى معدّل التنفس
dataType: respiratory-rate-sleep-summary
filter parameter: respiratory_rate_sleep_summary
نوع السجلّ: نموذج

الأجهزة المتوافقة

قائمة، تسوية .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly
النوم
dataType: sleep
filter parameter: sleep
نوع التسجيل: جلسة

الأجهزة المتوافقة

list, get, reconcile, create, update, batchDelete .sleep.readonly
.sleep.writeonly

جلسات النوم وفترات الاستيقاظ القصيرة

تمثّل جلسة النوم (Sleep) حدث نوم منفصلاً، مثل النوم ليلاً أو قيلولة نهارية. وتتضمّن تفاصيل دقيقة عن مراحل النوم غير المتداخلة، بالإضافة إلى فترات انتقالية قصيرة للاستيقاظ تُعرف باسم "فترات الاستيقاظ القصيرة".

  • جلسة النوم (Sleep): تمثّل حدث نوم منفصلاً (فترات مراحل LIGHT وDEEP وREM وAWAKE) يقسّم المخطط الزمني المتجاور لفترة الراحة الأساسية.
  • الاستيقاظ لفترات قصيرة (shortAwakenings): يشير هذا المقياس إلى فترات الاستيقاظ القصيرة أو الاستيقاظ أثناء الراحة. على عكس الفواصل الزمنية العادية لمراحل AWAKE (التي تقسم تسلسل مراحل النوم المتجاورة غير المتداخلة)، فإنّ فترات الاستيقاظ القصيرة هي أجزاء مميزة يمكن أن تتداخل مع مراحل النوم المحيطة بها. وتوفّر هذه المقاييس رؤية دقيقة حول الأرق والاستيقاظ لفترات قصيرة بدون التأثير في بنية مراحل النوم الأساسية.
  • الاستيقاظ ليلاً: يتم تحديد حالات الاستيقاظ في منتصف الليل (مثل الاستيقاظ لشرب الماء) من خلال دمج بيانات أدوات الاستشعار على الجهاز فقط (مقياس التسارع والجيروسكوب وعدد الخطوات). يمكن للتطبيقات رصد حالات الاستيقاظ ليلاً من خلال فلترة stages للفترات التي تتضمّن type: "AWAKE" (المستخدَمة في سجلّات النوم لكل من CLASSIC وSTAGES) أو من خلال فحص outOfBedSegments.

مثال

{
  "name": "users/user-id/dataTypes/sleep/dataPoints/data-point-id",
  "sleep": {
    "interval": {
      "startTime": "2026-04-20T22:30:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-04-21T06:30:00Z",
      "endUtcOffset": "-14400s"
    },
    "type": "STAGES",
    "stages": [
      {
        "startTime": "2026-04-20T22:30:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:45:00Z",
        "endUtcOffset": "-14400s",
        "type": "LIGHT"
      },
      {
        "startTime": "2026-04-20T23:45:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-21T01:15:00Z",
        "endUtcOffset": "-14400s",
        "type": "DEEP"
      }
    ],
    "shortAwakenings": [
      {
        "startTime": "2026-04-20T23:10:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-04-20T23:11:30Z",
        "endUtcOffset": "-14400s",
        "type": "AWAKE"
      }
    ],
    "summary": {
      "minutesInSleepPeriod": "480",
      "minutesAsleep": "455",
      "minutesAwake": "25",
      "minutesToFallAsleep": "15",
      "minutesAfterWakeUp": "10"
    }
  }
}

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

لإنشاء إدخال جلسة نوم، أرسِل طلب 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) النتيجة النهائية بعد احتساب مستويات النوم.

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

وقت الاستجابة لبدء النوم

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

بالنسبة إلى السجلات التي يتم إنشاؤها تلقائيًا (metadata.manuallyEdited هي false)، يتم ضبط summary.minutesToFallAsleep تلقائيًا على "0" لأنّه لم يتم تسجيل أي نية صريحة للنوم. عند تسجيل أوقات بدء النوم في السرير أو تعديلها يدويًا (metadata.manuallyEdited هو true)، تحتسب واجهة برمجة التطبيقات summary.minutesToFallAsleep وتملأه مع summary.minutesAfterWakeUp.

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

عندما يسجّل المشاركون أوقات النوم والاستيقاظ يدويًا أو يعدّلونها:

  1. يؤدي تعديل حدود وقت النوم إلى تغيير interval (وsummary.minutesInSleepPeriod) النوم.
  2. يتم ضبط مستويات النوم وأقسام المراحل تلقائيًا لتقييم بيانات جهاز الاستشعار ضمن النافذة الجديدة.
  3. تتم إعادة احتساب نتيجة كفاءة النوم وsummary.minutesToFallAsleep وsummary.minutesAfterWakeUp استنادًا إلى الفترة الزمنية المعدَّلة.

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

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

معدّل التنفس

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

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

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

تشبّع الأكسجين في الدم

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

عند طلب بيانات oxygen-saturation على مستوى الدقيقة، تعرض Google Health API نقاط البيانات التي تم التحقّق منها فقط وتستبعد القياسات غير الصالحة الناتجة عن حركة الذراع أو عدم إحكام ربط الساعة بالمعصم أو انخفاض مستوى ثقة أداة الاستشعار (أقل من %50)، بالإضافة إلى القراءات المجاورة لضوضاء الحركة. بما أنّه يتم استبعاد الدقائق غير الصالحة، قد تكون التغطية على مستوى الدقيقة متفرقة، ومن المتوقّع حدوث فجوات في الطوابع الزمنية. يعتمد كل من oxygen-saturation وdaily-oxygen-saturation على القراءات التي تم التحقّق منها نفسها. للحصول على تفاصيل حول معايير التحقّق من الصحة، يُرجى الاطّلاع على فلترة نسبة الأكسجين بالدم على مستوى الدقيقة وصلاحية البيانات.

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

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

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

الإرشادات

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

  • تفاصيل الجلسة: لعرض مراحل نوم المستخدم (النوم الخفيف والعميق وحركة العين السريعة والاستيقاظ) وفترات الاستيقاظ القصيرة، يمكنك الاستعلام عن نوع البيانات sleep.
  • الاستيقاظ ليلاً: لتتبُّع أحداث الاستيقاظ في منتصف الليل بدون بيانات أولية من أجهزة الاستشعار، يمكنك فحص فترات مراحل sleep وفلترة العناصر التي تحتوي على type: "AWAKE" (لكل من سجلات النوم STAGES وCLASSIC) أو فحص outOfBedSegments.
  • وقت الاستجابة والكفاءة: يمكنك استخدام summary.minutesToFallAsleep ومعادلة كفاءة النوم لتحليل وقت الاستجابة للنوم. يُرجى العِلم أنّه تتم تعبئة الحقل summary.minutesToFallAsleep عند تعديل سجلّات النوم يدويًا (metadata.manuallyEdited هو true) أو تسجيلها بشكل صريح.
  • المراقبة الفسيولوجية: لمراقبة الحالة الصحية بشكل متقدّم، يمكنك دمج بيانات جلسة النوم مع المقاييس الفسيولوجية ومقاييس التعافي، مثل respiratory-rate-sleep-summary وdaily-sleep-temperature-derivations وdaily-heart-rate-variability وdaily-oxygen-saturation.
  • التسوية: استخدِم العملية reconcile لضمان دمج سجلّات النوم المتداخلة من أجهزة مختلفة (مثل جهاز قابل للارتداء وأداة استشعار في الفراش) في سجلّ نوم "رئيسي" واحد.

حساب إجمالي مدة النوم العميق

لاحتساب إجمالي الوقت الذي قضاه المستخدم في مرحلة النوم العميق المريح في ليلة معيّنة:

  1. يمكنك الاستعلام عن نوع البيانات sleep للنطاق الزمني المحدّد.
  2. يمكنك تكرار قائمة المراحل وتحديد الفترات التي يكون فيها type هو DEEP.
  3. احسب المدة (وقت الانتهاء - وقت البدء) لكل فترة نوم عميق واجمعها.

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