تطوير تجارب النوم باستخدام 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 مراحل النوم القياسية (التي تقسم مراحل النوم المتجاورة غير المتداخلة)، فإنّ فترات الاستيقاظ القصيرة هي مقاطع مميزة يمكن أن تتداخل مع مراحل النوم المحيطة. وتوفّر هذه المقاييس إمكانية الاطّلاع على تفاصيل حالات الأرق والاستيقاظات القصيرة بدون التأثير في بنية مراحل النوم الأساسية.

مثال

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

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

لإنشاء إدخال لجلسة نوم، أرسِل طلب 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"
        }
      ]
    }
  }
}

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

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

معدّل التنفس

يقيس معدّل التنفس عدد الأنفاس التي يتنفسها المستخدم في الدقيقة. أثناء النوم، يشكّل معدّل ضربات القلب مقياسًا أساسيًا لتتبُّع جودة النوم والاضطرابات المحتملة. تتيح واجهة برمجة التطبيقات عينات معدّل التنفس (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.
  • مراقبة المؤشرات الفيزيولوجية: لمراقبة الصحة بشكل متقدّم، يمكنك الجمع بين بيانات جلسة النوم ومقاييس التعافي والمؤشرات الفيزيولوجية، مثل respiratory-rate-sleep-summary وdaily-sleep-temperature-derivations وdaily-heart-rate-variability وdaily-oxygen-saturation.
  • التوفيق: استخدِم العملية reconcile لضمان دمج سجلّات النوم المتداخلة من أجهزة مختلفة (مثل جهاز يمكن ارتداؤه وجهاز استشعار في الفراش) في سجلّ نوم "رئيسي" واحد.

حساب إجمالي الوقت الذي قضيته في النوم العميق

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

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

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

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