يقدّم قسم "مواصفات واجهة برمجة التطبيقات" نظرة عامة مفصّلة على المكوّنات الفنية الأساسية لعملية التكامل مع المنصة، بما في ذلك نطاقات التفويض وتعريفات أنواع البيانات وبُنى نقاط النهاية. تمثّل واجهة برمجة التطبيقات هذه تطورًا استراتيجيًا لواجهة Fitbit Web API القديمة، وقد تمت إعادة إنشائها على بنية أساسية حديثة لضمان تجربة أكثر استقرارًا واتساقًا للمطوّرين.
المستويات
يجب تعديل طلب التفويض لاستخدام نطاقات Google Health API. تحدّد النطاقات ما إذا كان تطبيقك يتيح عمليات القراءة أو الكتابة. اتّبِع تعليمات تنفيذ النطاق التي تحدّد طلب النطاقات المطلوبة فقط، وضبط إذن الكتابة فقط عند إرسال البيانات، والتعامل مع الموافقة الجزئية بشكل سلس.
نطاقات Google Health API هي عنوان URL يستخدم HTTP يبدأ بـ
https://www.googleapis.com/auth/googlehealth.{scope}. على سبيل المثال:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly.
عمليات ربط النطاق
في ما يلي كيفية ربط نطاقات Fitbit Web API بنطاقات Google Health API:
| نطاقات Fitbit Web API | نطاقات Google Health API |
|---|---|
| النشاط | .activity_and_fitness.readonly
.activity_and_fitness.writeonly |
| blood_glucose | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| cardio_fitness | .activity_and_fitness.readonly
.activity_and_fitness.writeonly |
| مخطَّط كهربية القلب | .ecg.readonly
|
| معدل نبضات القلب | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| irregular_rhythm_notifications | .irn.readonly
|
| الموقع | .location.readonly
|
| المعلومات الغذائية | .nutrition.readonly
.nutrition.writeonly |
| oxygen_saturation | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| الملف الشخصي | .profile.readonly
.profile.writeonly |
| respiratory_rate | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| الإعدادات | .settings.readonly
.settings.writeonly |
| النوم | .sleep.readonly
.sleep.writeonly |
| درجة الحرارة | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
| الوزن | .health_metrics_and_measurements.readonly
.health_metrics_and_measurements.writeonly |
أنواع البيانات
في ما يلي قائمة بأنواع بيانات Google Health API وكيفية ربطها بـ Fitbit Web API.
| نوع بيانات Fitbit Web API | نوع بيانات Google Health APIdataType |
الوصف |
|---|---|---|
| السعرات الحرارية المحروقة أثناء النشاط | سعرات حرارية محروقة بالنشاطactive-energy-burned
|
تمثّل هذه السمة السعرات الحرارية المحروقة خلال فترات النشاط، بما في ذلك معدّل الأيض الأساسي لتلك الفترات. في Google Health API، يمكن إعادة إنشاء هذه البيانات من خلال إضافة معدّل الأيض الأساسي إلى نوع البيانات active-energy-burned (الذي يتتبّع السعرات الحرارية المحروقة أثناء النشاط فقط، باستثناء معدّل الأيض الأساسي). |
| دقائق نطاق النشاط | دقائق نطاق النشاطactive-zone-minutes
|
|
| يحتوي على تغييرات في مستويات نشاط المستخدم | مستوى النشاطactivity-level
|
تسجّل مستوى نشاط المستخدم (مثل الخمول أو النشاط) خلال فترة زمنية محدّدة. |
| الارتفاع | Altitudealtitude
|
|
النشاط caloriesBMR |
معدّل الاستقلاب الأساسيbasal-energy-burned
|
السعرات الحرارية المحروقة بسبب معدّل الأيض الأساسي (BMR) خلال فترة زمنية محدّدة |
| الغلوكوز في الدم | الغلوكوز في الدمblood-glucose
|
|
| نسبة الدهون بالجسم | نسبة الدهون بالجسمbody-fat
|
|
caloriesOut في كل نطاق لمعدّل نبضات القلب |
السعرات الحرارية في نطاق معدّل نبضات القلبcalories-in-heart-rate-zone
|
|
| درجة الحرارة (الأساسية) | درجة حرارة الجسم الأساسيةcore-body-temperature
|
|
| ملخّص تغيُّر معدّل نبضات القلب | تغيُّر معدّل نبضات القلب اليوميdaily-heart-rate-variability
|
|
| ملخّص نسبة الأكسجين بالدم | نسبة الأكسجين اليومية في الدمdaily-oxygen-saturation
|
ملخّص يومي لإحصاءات نسبة الأكسجين في الدم (SpO2) يتم احتسابه من قياسات النوم التي تم التحقّق منها |
| معدّل النبض أثناء الراحة | معدّل النبض اليومي أثناء الراحةdaily-resting-heart-rate
|
|
| درجة حرارة الجلد | التغيّرات اليومية في درجة حرارة الجسم أثناء النومdaily-sleep-temperature-derivations
|
|
| المسافة | المسافةdistance
|
|
| مخطَّط كهربية القلب (ECG) | مخطَّط كهربية القلب (ECG)electrocardiogram
|
|
| النشاط المسجَّل | التمارين الرياضيةexercise
|
التمارين أو جلسات التمرين المسجَّلة، والتي تشمل أوقات البدء والانتهاء وأنواع الأنشطة ومقاييس الجلسات |
| الطوابق | الأرضياتfloors
|
|
| طعام | الطعامfood
|
|
| وحدة قياس الطعام | وحدة قياس الطعامfood-measurement-unit
|
|
| معدّل نبضات القلب | معدّل نبضات القلبheart-rate
|
|
| تغيُّر معدّل نبضات القلب خلال اليوم | تغيُّر معدّل نبضات القلبheart-rate-variability
|
|
| إشعارات اضطراب نظم القلب (IRN) | إشعار اضطراب نظم القلبirregular-rhythm-notification
|
|
| سجلّ الطعام | سجلّ التغذيةnutrition-log
|
|
| نسبة الأكسجين بالدم خلال اليوم | نسبة الأكسجين في الدمoxygen-saturation
|
تعرض هذه السمة قياسات نسبة الأكسجين بالدم التي تم التحقّق من صحتها على مستوى الدقيقة فقط، وتستبعد القراءات التي تم وضع علامة عليها على أنّها غير صالحة بسبب تشويش الحركة أو انخفاض مستوى موثوقية أداة الاستشعار. بما أنّ Fitbit Web API استبعدت فقط قيمة الحراسة البالغة %50، تعرض Google Health API نقاط بيانات أقل للنطاق الزمني نفسه. لمعرفة التفاصيل، يُرجى الاطّلاع على فلترة نسبة الأكسجين في الدم. |
| قيمة الحد الأقصى لاستهلاك الأكسجين عندما يركض المستخدم | الحد الأقصى لاستهلاك الأكسجين أثناء الجريrun-vo2-max
|
|
| دقائق الخمول في السلسلة الزمنية للنشاط | فترة الخمولsedentary-period
|
|
| النوم | درجات حرارة مناسبة للنومsleep
|
|
| الخطوات | الخطواتsteps
|
|
| عدد حركات السباحة في السلسلة الزمنية للنشاط | بيانات أطوال أحواض السباحةswim-lengths-data
|
|
النشاط caloriesOut |
إجمالي السعرات الحراريةtotal-calories
|
إجمالي عدد السعرات الحرارية المحروقة التي يحرقها المستخدم خلال فترة زمنية معيّنة، بما في ذلك معدل الأيض الأساسي (BMR) والطاقة النشطة المحروقة. |
| قيمة الحد الأقصى لاستهلاك الأكسجين | الحدّ الأقصى لاستهلاك الأكسجينvo2-max
|
|
| الوزن | الوزنweight
|
عمليات الاحتساب
تختلف عمليات الربط والقواعد في Google Health API عن Fitbit Web API.
فلترة نسبة الأكسجين في الدم
عند طلب بيانات نسبة الأكسجين في الدم (oxygen-saturation) على مستوى الدقيقة، تطبّق Google Health API فلترة أكثر صرامة على صلاحية البيانات مقارنةً بـ Fitbit Web API القديمة:
- استبعدت واجهة Fitbit Web API القديمة (الإصدار 1 والإصدار 3) عيّنات نسبة الأكسجين في الدم التي تحتوي على قيمة حارسة تبلغ %50 فقط.
- تستبعد واجهة برمجة التطبيقات Google Health API (الإصدار 4) جميع عينات نسبة الأكسجين بالدم التي تم وضع علامة عليها على أنّها غير صالحة من خلال خوارزمية التحقّق من الصحة. يتم وضع علامة "غير صالحة" على الدقيقة عندما تكون إشارة أداة الاستشعار الضوئية غير موثوقة بسبب حركة الذراع أو عدم إحكام ربط الساعة حول المعصم، أو عندما تنخفض درجة الثقة إلى أقل من %50، أو خلال الدقائق الثلاث التي تسبق القراءة غير الصالحة وتليها مباشرةً، أو عندما تستمر الفترة الصالحة لأقل من 4 دقائق متتالية.
بما أنّ Google Health API تزيل جميع القياسات غير الصالحة بدلاً من إزالة
قيمة الحراسة التي تبلغ %50 فقط، فإنّها تعرض نقاط بيانات oxygen-saturation أقل من
Fitbit Web API للنطاق الزمني نفسه، ومن المتوقّع حدوث فجوات في التغطية
دقيقة بدقيقة. تتوافق القراءات التي يتم عرضها على مستوى الدقيقة مع نقاط البيانات التي تم التحقّق منها والمستخدَمة لحساب daily-oxygen-saturation ملخّص جودة ومدة النوم للمستخدم. لمزيد من المعلومات، يُرجى الاطّلاع على فلترة نسبة الأكسجين بالدم على مستوى الدقيقة وصلاحية
البيانات.
مستوى النشاط ومكافئات الأيض وحدود الخطوات
في Google Health API، يتم استنتاج مستوى نشاط المستخدم دقيقة بدقيقة من المكافئ الأيضي (MET) وعدد الخطوات.
| مستوى النشاط | أجهزة قياس معدّل نبضات القلب | الأجهزة التي لا تقيس معدّل نبضات القلب |
|---|---|---|
| قليل الحركة | 1.5 مكافئ أيضي أو أقل | 1.5 مكافئ أيضي أو أقل |
| نشاط خفيف | > 1.5 مكافئ أيضي و≤ 4.2 مكافئ أيضي | > 1.5 مكافئ أيضي و≤ 3.5 مكافئ أيضي |
| نشاط معتدل | > 4.2 وحدة مكافئ أيضي و < 6.0 وحدة مكافئ أيضي (ما لم يتم استيفاء شروط نشط جدًا) |
> 3.5 وحدة مكافئ أيضي و < 6.0 وحدة مكافئ أيضي (ما لم يتم استيفاء شروط نشط جدًا) |
| نشط جدًا | 6.0 وحدة مكافئ أيضي أو أكثر، أو 5.0 وحدة مكافئ أيضي أو أكثر مع معدّل خطوات يبلغ 150 خطوة في الدقيقة أو أكثر | 6.0 وحدة مكافئ أيضي أو أكثر، أو 5.0 وحدة مكافئ أيضي أو أكثر مع معدّل خطوات يبلغ 150 خطوة في الدقيقة أو أكثر |
تتكوّن الدقائق النشطة من دقائق MODERATELY_ACTIVE وVERY_ACTIVE
مجتمعة. ومع ذلك، لا يتم احتساب الدقيقة النشطة للغاية إلا إذا حدثت خلال فترة متواصلة لا تقل عن 10 دقائق، مع السماح بفواصل زمنية لا تزيد عن دقيقتين من النشاط الأقل.
دقائق الخمول والنوم
لا تشمل دقائق الخمول وقت النوم. في الملخّصات اليومية، يتم احتساب دقائق عدم النشاط من خلال طرح دقائق النوم والدقائق النشطة (النشاط الخفيف والنشاط المعتدل والنشاط العالي) من إجمالي عدد الدقائق في اليوم (1,440 دقيقة):
Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes -
Moderately Active Minutes - Very Active Minutes
مؤشر كتلة الجسم (BMI)
بما أنّ Google Health API لا تعرض نوع بيانات مدمجًا لمؤشر كتلة الجسم، يجب أن تحسب التطبيقات مؤشر كتلة الجسم من جهة العميل باستخدام سجلّات الطول والوزن:
- يمكنك استرداد وزن المستخدم بالجرام من حقل
weightGramsفي نوع بيانات الوزن. حوِّل هذه القيمة إلى كيلوغرام (بالقسمة على 1,000) أو إلى رطل (بالقسمة على 453.59237). - يمكنك استرداد طول المستخدم بالمليمتر من حقل
heightMillimetersفي نوع بيانات الطول. حوِّل هذه القيمة إلى أمتار (بالقسمة على 1,000) أو بوصات (بالقسمة على 25.4). - استخدِم إحدى الصيغ التالية
لحساب قيمة مؤشر كتلة الجسم:
- صيغة المقياس:
BMI = weight (kg) / [height (m)]^2 - الصيغة الإمبراطورية:
BMI = (weight (lbs) / [height (in)]^2) * 703
- صيغة المقياس:
تتوافق قيم مؤشر كتلة الجسم الناتجة مع الفئات التالية:
| فئة الوزن | نطاق مؤشر كتلة الجسم |
|---|---|
| نقص الوزن | أقل من 18.5 |
| الوزن الصحي | من 18.5 إلى 24.9 |
| الوزن الزائد | من 25 إلى 29.9 |
| السمنة | 30 أو أكثر |
معدل الأيض الأساسي (BMR)
معدّل الأيض الأساسي (BMR) هو الحدّ الأدنى لعدد السعرات الحرارية اللازمة للوظائف الجسدية الأساسية أثناء الراحة. بما أنّ واجهة Google Health API لا تعرض نوع بيانات مدمجًا لمعدّل الأيض الأساسي، يجب أن تحتسبه التطبيقات من جهة العميل باستخدام معادلة "هاريس بينديكت". يمكنك الاطّلاع على مقالة معادلة هاريس بينديكت على ويكيبيديا لمزيد من المعلومات.
لإجراء هذه العملية الحسابية:
- استرِدّ وزن المستخدم بالجرام من الحقل
weightGramsفي نوع بيانات الوزن وحوِّله إلى كيلوجرام (بالقسمة على 1,000). لتحويل الأرطال إلى كيلوغرامات، اقسم على 2.2. - استرِدّ طول المستخدم بالمليمتر من حقل
heightMillimetersفي نوع بيانات الطول وحوِّله إلى سنتيمتر (بالقسمة على 10). لتحويل البوصات إلى سنتيمترات، اضرب في 2.54. - استرداد عمر المستخدم بالسنوات من الحقل
ageفي مورد الملف الشخصي - استرداد الجنس البيولوجي بشكل مستقل (على سبيل المثال، من خلال مطالبة المستخدم أو الاحتفاظ به في قاعدة البيانات الخاصة بك)، لأنّ Google Health API لا تعرض هذا الحقل.
- استخدِم إحدى الصيغ التالية استنادًا إلى الجنس البيولوجي للمستخدم:
- الرجال:
BMR = 66 + (13.7 x weight_kg) + (5 x height_cm) - (6.8 x age_years) - النساء:
BMR = 655 + (9.6 x weight_kg) + (1.8 x height_cm) - (4.7 x age_years)
- الرجال:
إجمالي استهلاك الطاقة اليومي (TDEE)
إجمالي استهلاك الطاقة اليومي (TDEE) هو تقدير لإجمالي عدد السعرات الحرارية التي يحرقها الشخص في اليوم، ويشمل كلاً من معدّل الأيض الأساسي والنشاط البدني. لتقدير إجمالي النفقات اليومية للطاقة (TDEE) للمستخدم، اضرب قيمة معدّل الأيض الأساسي (BMR) في عامل النشاط المتوافق مع أسلوب حياته:
| مستوى النشاط | الوصف | المُضاعِف |
|---|---|---|
| قليل الحركة | قليل من التمارين أو لا أمارسها أبدًا | BMR x 1.2 |
| نشاط خفيف | ممارسة التمارين الرياضية من يوم إلى 3 أيام في الأسبوع | BMR x 1.375 |
| نشاط معتدل | ممارسة التمارين الرياضية من 3 إلى 5 أيام في الأسبوع | BMR x 1.55 |
| نشط جدًا | ممارسة التمارين الرياضية من 6 إلى 7 أيام في الأسبوع | BMR x 1.725 |
| نشاط إضافي | تمارين رياضية شاقة جدًا أو عمل بدني شاق | BMR x 1.9 |
نقاط النهاية
تعتمد نقاط نهاية REST بنية متسقة لجميع أنواع البيانات.
- نقطة نهاية الخدمة: يتغيّر عنوان URL الأساسي الذي يستخدم HTTP إلى https://health.googleapis.com.
- بنية نقطة النهاية: تتيح واجهة Google Health API عددًا محدودًا من نقاط النهاية التي يمكن استخدامها مع معظم أنواع البيانات المتوافقة. يوفّر ذلك صيغة متّسقة لجميع أنواع البيانات ويجعل نقاط النهاية أسهل في الاستخدام.
- معرّف المستخدم: يجب تحديد رقم تعريف المستخدم أو me في بنية نقطة النهاية. عند استخدام me، يتم استنتاج رقم تعريف المستخدم من رمز الدخول.
مثال: في ما يلي مثال على نقطة نهاية GET Profile التي يتم طلبها باستخدام Google Health API
GET https://health.googleapis.com/v4/users/me/profile
عمليات ربط نقاط النهاية
يُرجى الاطّلاع على جدول أنواع بيانات Google Health API للحصول على قائمة بأنواع البيانات المتاحة وطُرق واجهة برمجة التطبيقات التي تتيحها.
| نوع نقطة نهاية Fitbit Web API | Google Health API |
|---|---|
| GET (Log | Summary | Daily Summary) حيث تطلب بيانات يوم واحد | طريقة "dailyRollUp" (POST .../dataPoints:dailyRollUp) مع "windowSizeDays: 1" |
| GET (Intraday) حيث تطلب بيانات دقيقة | طريقة واحدة (list) |
| GET (السلسلة الزمنية) حسب التاريخ أو الفاصل الزمني | طريقة rollUp أو dailyRollUp تتضمّن نطاقًا زمنيًا |
| GET (قائمة السجلّات) | طريقة واحدة (list) |
| سجلّات الإنشاء والتعديل | طريقة واحدة (patch) |
| سجلّات DELETE | طريقة واحدة (batchDelete) |
| GET Profile | users.getProfile تعرض معلومات محدّدة عن المستخدمusers.getSettings تعرض الوحدات والمناطق الزمنية للمستخدم |
| تعديل الملف الشخصي | users.updateProfile لتعديل معلومات المستخدم المحدّدةusers.updateSettings لتعديل وحدات المستخدم ومناطقه الزمنية |
| الحصول على رقم تعريف المستخدم | تعرض السمة users.getIdentity رقم تعريف المستخدم القديم في Fitbit ورقم تعريف المستخدم في Google. |
| الحصول على الأجهزة | users.pairedDevices تعرض قائمة الأجهزة المقترنة |
| إنشاء اشتراكات | إنشاء اشتراك يدويًا من قِبل "projects.subscribers.subscriptions.create" |
| حذف الاشتراكات | projects.subscribers.subscriptions.delete حذف اشتراك |
| الحصول على قائمة الاشتراكات | projects.subscribers.subscriptions.list يعرض كل الاشتراكات |