يقدّم قسم "مواصفات واجهة برمجة التطبيقات" نظرة عامة مفصّلة على المكوّنات الفنية الأساسية لعملية الدمج مع المنصة، بما في ذلك نطاقات التفويض وتعريفات أنواع البيانات وبُنى نقاط النهاية. تمثّل واجهة برمجة التطبيقات هذه تطورًا استراتيجيًا لواجهة 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
|
|
| ملخّص تغيُّر معدّل نبضات القلب (HRV) | تغيُّر معدّل نبضات القلب يوميًاdaily-heart-rate-variability
|
|
| ملخّص نسبة الأكسجين بالدم | نسبة الأكسجين في الدم يوميًاdaily-oxygen-saturation
|
ملخّص يومي لإحصاءات نسبة الأكسجين في الدم (SpO2) يتم احتسابه من قياسات النوم التي تم التحقّق منها |
| معدّل النبض أثناء الراحة | معدّل النبض اليومي أثناء الراحةdaily-resting-heart-rate
|
|
| درجة حرارة الجلد | Daily Sleep Temperature Derivationsdaily-sleep-temperature-derivations
|
|
| المسافة | المسافةdistance
|
|
| مخطَّط كهربية القلب (ECG) | مخطَّط كهربية القلب (ECG)electrocardiogram
|
|
| النشاط المسجَّل | التمارين الرياضيةexercise
|
التمارين أو جلسات التمارين المسجّلة، والتي تتضمّن أوقات البدء والانتهاء وأنواع الأنشطة ومقاييس الجلسات |
| الطوابق | الطوابقfloors
|
|
| طعام | الطعامfood
|
|
| وحدة قياس الطعام | Food Measurement Unitfood-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
|
إجمالي عدد السعرات الحرارية التي يحرقها المستخدم خلال فترة زمنية معيّنة، بما في ذلك معدّل الأيض الأساسي والطاقة النشطة المحروقة. |
| قيمة الحد الأقصى لاستهلاك الأكسجين | الحد الأقصى لاستهلاك الأكسجين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. لمزيد من المعلومات، يُرجى الاطّلاع على فلترة نسبة الأكسجين بالدم على مستوى الدقيقة وصلاحية البيانات.
مستوى النشاط والمكافئات الأيضية للمَهمة (MET) والحدود القصوى للخطوات
في 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) هو تقدير لإجمالي عدد السعرات الحرارية التي يحرقها الشخص في اليوم، ويشمل كلاً من معدل الأيض الأساسي والنشاط البدني. لتقدير إجمالي النفقات اليومية للطاقة لدى المستخدم، اضرب قيمة معدّل الأيض الأساسي في عامل النشاط المتوافق مع أسلوب حياته:
| مستوى النشاط | الوصف | المُضاعِف |
|---|---|---|
| قليل الحركة | تمارين رياضية قليلة أو معدومة | 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) مع windowSize = يوم واحد |
| GET (Intraday) حيث تطلب بيانات دقيقة | طريقة واحدة (list) |
| GET (Time Series) by Date or Interval | طريقة 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 يعرض كل الاشتراكات |