بخش «مشخصات میانای برنامه‌سازی کاربردی» نمای کلی دقیقی از مؤلفه‌های فنی ضروری برای ادغام با پلاتفرم، ازجمله دامنه‌های مجوز، تعاریف نوع داده، و ساختارهای نقطه پایانی ارائه می‌دهد. این «میانای برنامه‌سازی کاربردی» نشان‌دهنده تکامل استراتژیک «میانای برنامه‌سازی کاربردی وب» قدیمی Fitbit است که روی زیرساخت مدرن بازسازی شده است تا تجربه توسعه‌دهنده پایدارتر و منسجم‌تری را تضمین کند.
دوربین تفنگ
برای استفاده از دامنه‌های Google Health API، باید درخواست مجوزتان را به‌روز کنید. این دامنه‌ها مشخص می‌کنند که آیا برنامه شما از عملیات خواندن یا نوشتن پشتیبانی می‌کند یا نه. دستورالعمل‌های پیاده‌سازی گستره را دنبال کنید که مشخص می‌کند فقط گستره‌های موردنیاز درخواست شود، دسترسی نوشتن فقط هنگام ارسال داده پیکربندی شود، و رضایت جزئی به‌درستی مدیریت شود.
دامنه‌های Google Health API نشانی وب 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 | گستره‌های 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، این مقدار را می‌توان با افزودن BMR به نوع داده active-energy-burned (که فقط کالری سوخته‌شده در فعالیت را بدون احتساب نرخ پایه ردیابی می‌کند) بازسازی کرد. |
| دقایق محدوده فعالیت | دقایق محدوده فعالیتactive-zone-minutes
|
|
| حاوی تغییراتی در سطح فعالیت کاربر است | سطح فعالیتactivity-level
|
سطح فعالیت کاربر (مانند بی‌تحرک یا فعال) را در یک دوره زمانی خاص ثبت می‌کند. |
| ارتفاع | ارتفاعaltitude
|
|
فعالیت caloriesBMR |
میزان سوخت‌وساز پایهbasal-energy-burned
|
کالری‌های سوزانده‌شده به‌دلیل «سرعت سوخت‌وساز پایه» (BMR) درطول دوره زمانی خاص. |
| قند خون | قند خونblood-glucose
|
|
| چربی بدن | چربی بدنbody-fat
|
|
caloriesOut در هر محدوده ضربان قلب |
کالری در محدوده ضربان قلبcalories-in-heart-rate-zone
|
|
| دما (مرکزی) | دمای مرکزی بدنcore-body-temperature
|
|
| خلاصه HRV | تغییرپذیری ضربان قلب روزانهdaily-heart-rate-variability
|
|
| خلاصه SpO2 | اشباع اکسیژن روزانه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
|
|
| SpO2 درون‌روز | اشباع اکسیژنoxygen-saturation
|
فقط اندازه‌گیری‌های SpO2 معتبرشده در سطح دقیقه را برمی‌گرداند و خوانش‌هایی را که به‌دلیل مصنوعات حرکتی یا اطمینان پایین حسگر به‌عنوان نامعتبر پرچم‌گذاری شده‌اند مستثنی می‌کند. چون Fitbit Web API فقط مقدار نگهبان ۵۰٪ را مستثنی می‌کرد، Google Health API نقاط داده کمتری را برای همان محدوده زمانی برمی‌گرداند. برای جزئیات، فیلتر کردن اشباع اکسیژن را ببینید. |
| مقدار حداکثر VO2 وقتی کاربر می‌دود | حداکثر اکسیژن مصرفی در دویدن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 (نسخه ۱ و ۳) فقط نمونه‌های SpO2 را با مقدار نگهبان ۵۰٪ مستثنی می‌کرد.
- Google Health API (v4) همه نمونه‌های SpO2 را که توسط الگوریتم اعتبارسنجی به‌عنوان نامعتبر پرچم‌گذاری شده‌اند مستثنی می‌کند. یک دقیقه زمانی نامعتبر علامت‌گذاری می‌شود که حرکت بازو یا شل بودن مچ‌بند باعث غیرقابل‌اعتماد شدن سیگنال حسگر نوری شود، زمانی که امتیاز اطمینان به زیر ۵۰٪ کاهش یابد، درطول ۳ دقیقه بلافاصله قبل و بعداز خوانش نامعتبر، یا زمانی که یک بازه معتبر کمتر از ۴ دقیقه متوالی طول بکشد.
چون Google Health API به‌جای فقط ۵۰٪ مقدار نگهبان، همه اندازه‌گیری‌های نامعتبر را برمی‌دارد،
برای همان محدوده زمانی، نقاط داده oxygen-saturation کمتری نسبت به Fitbit Web API برمی‌گرداند،
و انتظار می‌رود که در پوشش دقیقه به دقیقه وقفه‌هایی وجود داشته باشد. خوانش‌های دقیقه‌ای برگردانده‌شده با نقاط داده معتبرشده‌ای که برای محاسبه خلاصه اطلاعات خواب daily-oxygen-saturation کاربر استفاده شده است مطابقت دارد. برای اطلاعات بیشتر، فیلتر کردن SpO2 در سطح دقیقه و اعتبار داده را ببینید.
سطح فعالیت، شاخص سوخت‌وساز، و آستانه تعداد قدم‌ها
در Google Health API، سطح فعالیت دقیقه‌به‌دقیقه کاربر از «شاخص سوخت‌وساز» (MET) و تعداد قدم‌های او مشتق می‌شود.
| سطح فعالیت | دستگاه‌های ضربان قلب | دستگاه‌های بدون ضربان قلب |
|---|---|---|
| کم‌تحرک | ≤ ۱٫۵ شاخص سوخت‌وساز | ≤ ۱٫۵ شاخص سوخت‌وساز |
| فعالیت کم | > ۱٫۵ MET و ≤ ۴٫۲ MET | > ۱٫۵ MET و ≤ ۳٫۵ MET |
| نسبتاً فعال | > ۴.۲ MET و < ۶.۰ MET (مگر اینکه شرایط بسیار فعال برآورده شود) |
> ۳٫۵ MET و < ۶٫۰ MET (مگر اینکه شرایط بسیار فعال برآورده شود) |
| بسیار فعال | ≥ ۶٫۰ MET، یا ≥ ۵٫۰ MET با نرخ گام ۱۵۰ گام در دقیقه یا بیشتر | ≥ ۶٫۰ MET، یا ≥ ۵٫۰ MET با نرخ گام ۱۵۰ گام در دقیقه یا بیشتر |
دقایق فعال شامل مجموع دقایق MODERATELY_ACTIVE و VERY_ACTIVE است. بااین‌حال، دقیقه بسیار فعال فقط درصورتی لحاظ می‌شود که درطول یک دوره پیوسته حداقل ۱۰ دقیقه‌ای رخ دهد و حداکثر ۲ دقیقه وقفه با فعالیت کمتر مجاز است.
دقیقه‌های بی‌تحرکی و خواب
دقایق بی‌تحرکی شامل زمان خواب نمی‌شود. در خلاصه‌های روزانه، دقایق بی‌تحرکی با کسر کردن دقایق خواب و دقایق فعال (فعالیت سبک، فعالیت متوسط، و فعالیت شدید) از کل دقایق روز (۱۴۴۰ دقیقه) محاسبه می‌شود:
Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes -
Moderately Active Minutes - Very Active Minutes
شاخص توده بدنی (BMI)
ازآنجایی‌که Google Health API نوع داده BMI داخلی را نشان نمی‌دهد، برنامه‌ها باید «شاخص توده بدنی» را در سمت کارخواه بااستفاده از سوابق قد و وزن محاسبه کنند:
- وزن کاربر را به گرم از فیلد
weightGramsدر نوع داده وزن بازیابی کنید. این مقدار را به کیلوگرم (تقسیم بر ۱۰۰۰) یا پوند (تقسیم بر ۴۵۳٫۵۹۲۳۷) تبدیل کنید. - قد کاربر را برحسب میلی‌متر از فیلد
heightMillimetersدر نوع داده قد بازیابی کنید. این مقدار را به متر (تقسیم بر ۱۰۰۰) یا اینچ (تقسیم بر ۲۵٫۴) تبدیل کنید. - برای محاسبه مقدار BMI، از یکی از فرمول‌های زیر استفاده کنید:
- فرمول سنجه:
BMI = weight (kg) / [height (m)]^2 - فرمول معیار بریتانیایی:
BMI = (weight (lbs) / [height (in)]^2) * 703
- فرمول سنجه:
مقادیر شاخص توده بدنی به‌دست‌آمده با دسته‌های زیر مطابقت دارد:
| رده وزنی | محدوده شاخص توده بدنی |
|---|---|
| کم‌وزن | کمتر از ۱۸٫۵ |
| وزن سالم | ۱۸٫۵ تا ۲۴٫۹ |
| اضافه وزن | ۲۵ تا ۲۹٫۹ |
| چاق | ۳۰ یا بالاتر |
سرعت سوخت‌وساز پایه (BMR)
سرعت سوخت‌وساز پایه (BMR) حداقل تعداد کالری موردنیاز برای عملکردهای پایه بدن درحال استراحت است. چون Google Health API نوع داده BMR داخلی را نشان نمی‌دهد، برنامه‌ها باید آن را در سمت کارخواه بااستفاده از فرمول هریس-بندیکت محاسبه کنند. برای کسب اطلاعات بیشتر، مقاله معادله هریس-بندیکت را در ویکی‌پدیا ببینید.
برای انجام این محاسبه:
- وزن کاربر را به گرم از فیلد
weightGramsدر نوع داده وزن بازیابی کنید و به کیلوگرم تبدیل کنید (تقسیم بر ۱۰۰۰). برای تبدیل پوند به کیلوگرم، آن را بر ۲٫۲ تقسیم کنید. - قد کاربر را برحسب میلی‌متر از فیلد
heightMillimetersدر نوع داده قد بازیابی کنید و به سانتی‌متر تبدیل کنید (تقسیم بر ۱۰). برای تبدیل اینچ به سانتی‌متر، آن را در ۲٫۵۴ ضرب کنید. - سن کاربر را به سال از فیلد
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) و هم فعالیت بدنی را دربرمی‌گیرد. برای تخمین زدن TDEE کاربر، مقدار BMR را در ضریب فعالیت مربوط به سبک زندگی او ضرب کنید:
| سطح فعالیت | شرح | ضریب |
|---|---|---|
| کم‌تحرک | ورزش کم یا بدون ورزش. | BMR x 1.2 |
| فعالیت کم | ۱ تا ۳ روز ورزش در هفته. | BMR x 1.375 |
| نسبتاً فعال | ۳ تا ۵ روز ورزش در هفته. | BMR x 1.55 |
| بسیار فعال | ۶ تا ۷ روز تمرین در هفته. | BMR x 1.725 |
| بسیار فعال | ورزش یا کار فیزیکی بسیار سخت. | BMR x 1.9 |
نقاط پایانی
نقطه‌های پایانی REST از نحو ثابتی برای همه انواع داده استفاده می‌کنند.
- نقطه پایانی سرویس: نشانی وب HTTP پایه به https://health.googleapis.com تغییر می‌کند.
- نحو نقطه پایانی: Google Health API از تعداد محدودی از نقاط پایانی پشتیبانی می‌کند که اکثر انواع داده‌های پشتیبانی‌شده می‌توانند از آن‌ها استفاده کنند. این نحو ثابتی را برای همه انواع داده ارائه می‌دهد و استفاده از نقاط پایانی را آسان‌تر می‌کند.
- شناسه کاربر: شناسه کاربر یا me باید در نحو نقطه پایانی مشخص شود. هنگام استفاده از me، شناسه کاربر از کد دسترسی استنباط می‌شود.
مثال: در اینجا مثالی از نقطه پایانی GET Profile آورده شده است که بااستفاده از Google Health API فراخوانی شده است
GET https://health.googleapis.com/v4/users/me/profile
نگاشت‌های نقطه پایان
برای مشاهده فهرست انواع داده‌های دردسترس و روش‌های API که از آن‌ها پشتیبانی می‌کنند، به جدول انواع داده‌های Google Health API مراجعه کنید.
| نوع نقطه پایان میانای برنامه‌سازی کاربردی وب Fitbit | Google Health API |
|---|---|
| GET (Log | Summary | Daily Summary) که در آن داده‌های یک روز را درخواست می‌کنید | روش dailyRollup با windowSize = ۱ روز |
| GET (Intraday) که در آن داده‌های جزئی درخواست می‌کنید | روش list |
| دریافت (سری زمانی) براساس تاریخ یا فاصله زمانی | روش rollUp یا dailyRollUp شامل محدوده تاریخ |
| GET (Log List) | روش list |
| ایجاد و به‌روزرسانی گزارش‌ها | روش patch |
| حذف گزارش‌ها | روش batchDelete |
| GET Profile | users.getProfile اطلاعات خاص کاربر را برمی‌گرداندusers.getSettings واحدها و منطقه‌های زمانی کاربر را برمی‌گرداند |
| به‌روزرسانی نمایه | users.updateProfile اطلاعات خاص کاربر را اصلاح می‌کندusers.updateSettings واحدها و مناطق زمانی کاربر را اصلاح می‌کند |
| دریافت شناسه کاربر | users.getIdentity شناسه کاربر Google و Fitbit قدیمی کاربر را برمی‌گرداند. |
| دریافت دستگاه‌ها | users.pairedDevices فهرست دستگاه‌های جفت‌شده را برمی‌گرداند |
| ایجاد اشتراک‌ها | projects.subscribers.subscriptions.create اشتراکی را به‌صورت دستی ایجاد می‌کند |
| حذف اشتراک‌ها | projects.subscribers.subscriptions.delete حذف اشتراک |
| دریافت فهرست اشتراک‌ها | projects.subscribers.subscriptions.list همه اشتراک‌ها را فهرست می‌کند |