بخش مشخصات API، مروری دقیق بر اجزای فنی ضروری برای ادغام با پلتفرم، از جمله حوزههای مجوز، تعاریف نوع داده و ساختارهای نقطه پایانی ارائه میدهد. این API نشاندهنده تکامل استراتژیک API وب Fitbit قدیمی است که بر روی زیرساختهای مدرن بازسازی شده است تا تجربه توسعهدهنده پایدارتر و سازگارتری را تضمین کند.
محدودهها
برای استفاده از محدودههای API گوگل هلث، باید درخواست مجوز خود را بهروزرسانی کنید. محدودهها مشخص میکنند که آیا برنامه شما از عملیات خواندن یا نوشتن پشتیبانی میکند یا خیر. دستورالعملهای پیادهسازی محدوده را دنبال کنید، که فقط درخواست محدودههای مورد نیاز، پیکربندی دسترسی نوشتن فقط هنگام ارسال دادهها و مدیریت رضایت جزئی را به طور مناسب مشخص میکند.
محدودههای 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 نشان داده شده است:
| دامنههای API وب Fitbit | محدودههای API سلامت گوگل |
|---|---|
| فعالیت | .فعالیت_و_تناسب_اندام.فقط_خواندنی .activity_and_fitness.فقط نوشتنی |
| قند خون | .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی .معیارها_و_اندازهگیریهای_سلامت.فقط_نوشتنی |
| تناسب اندام_قلبی | .فعالیت_و_تناسب_اندام.فقط_خواندنی .activity_and_fitness.فقط نوشتنی |
| الکتروکاردیوگرام | .ecg.فقط خواندنی |
| ضربان قلب | .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی .معیارها_و_اندازهگیریهای_سلامت.فقط_نوشتنی |
| اعلانهای ریتم نامنظم | .irn.فقط خواندنی |
| مکان | .مکان.فقط خواندنی |
| تغذیه | .تغذیه.فقط خواندنی .تغذیه.فقط بنویس |
| اشباع اکسیژن | .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی .معیارها_و_اندازهگیریهای_سلامت.فقط_نوشتنی |
| پروفایل | .profile.فقط خواندنی .profile.فقط نوشتنی |
| میزان_تنفس | .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی .معیارها_و_اندازهگیریهای_سلامت.فقط_نوشتنی |
| تنظیمات | تنظیمات.فقط خواندنی تنظیمات.فقط نوشتنی |
| خواب | .sleep.only (فقط خواندنی) .sleep.only |
| دما | .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی .معیارها_و_اندازهگیریهای_سلامت.فقط_نوشتنی |
| وزن | .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی .معیارها_و_اندازهگیریهای_سلامت.فقط_نوشتنی |
انواع داده
در اینجا لیستی از انواع دادههای API گوگل هلث و نحوهی نگاشت آنها به API وب فیتبیت ارائه شده است.
برای اطلاعات بیشتر در مورد نحوه گزارش دادهها برای این نوعها، به راهنمای حضور دادهها و صفرهای واقعی مراجعه کنید. این راهنما شامل جزئیاتی در مورد عدم فعالیت و فیلترینگ روی مچ دست است.
| نوع دادهی Web API فیتبیت | نوع داده API سلامت گوگلdataType | توضیحات |
|---|---|---|
| کالری فعالیت | انرژی فعال سوزانده شدهactive-energy-burned | کالری سوزانده شده در طول دورههای فعال، شامل BMR برای آن دورهها را نشان میدهد. در API گوگل هلث، این مقدار را میتوان با اضافه کردن BMR به نوع دادهی active-energy-burned (که فقط میزان سوخت و ساز بدن را در طول فعالیت، به استثنای میزان پایه، اندازهگیری میکند) بازسازی کرد. |
| صورتجلسات منطقه فعال | صورتجلسات منطقه فعالactive-zone-minutes | |
| شامل تغییراتی در سطوح فعالیت کاربر است | سطح فعالیتactivity-level | |
| ارتفاع | ارتفاعaltitude | |
caloriesBMR فعالیت BMR | انرژی پایه سوزانده شده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 | |
| ضربان قلب در حالت استراحت | ضربان قلب در حالت استراحت روزانهdaily-resting-heart-rate | |
| دمای پوست | مشتقات دمای خواب روزانهdaily-sleep-temperature-derivations | |
| فاصله | فاصلهdistance | |
| الکتروکاردیوگرام (ECG) | الکتروکاردیوگرام (ECG)electrocardiogram | |
| فعالیت ثبت شده | ورزشexercise | تمرینات یا جلسات ورزشی ضبطشده، که شامل زمان شروع/پایان، انواع فعالیت و معیارهای جلسه میشود. |
| طبقات | طبقاتfloors | |
| غذا | غذاfood | |
| واحد اندازهگیری غذا | واحد اندازهگیری غذاfood-measurement-unit | |
| ضربان قلب | ضربان قلبheart-rate | |
| HRV روزانه | تغییرپذیری ضربان قلبheart-rate-variability | |
| اعلانهای ریتم نامنظم (IRN) | اعلان ریتم نامنظمirregular-rhythm-notification | |
| گزارش غذا | گزارش تغذیهnutrition-log | |
| SpO2 روزانه | اشباع اکسیژنoxygen-saturation | |
| مقدار VO2 Max هنگام دویدن کاربر | حداکثر اکسیژن مصرفی (VO2 Max) را بدویدrun-vo2-max | |
| سری زمانی فعالیت، دقیقههای بیتحرک | دوره کم تحرکیsedentary-period | |
| خواب | خوابsleep | |
| مراحل | مراحلsteps | |
| سری زمانی فعالیت، حرکات شنا | دادههای طول شناswim-lengths-data | |
caloriesOut مصرفی فعالیت | کل کالریtotal-calories | تعداد کل کالریهای سوزانده شده توسط یک کاربر در یک دوره زمانی، شامل انرژی پایه سوزانده شده و انرژی فعال سوزانده شده. |
| مقدار حداکثر اکسیژن مصرفی (VO2 Max) | حداکثر اکسیژن مصرفی (VO2 Max)vo2-max | |
| وزن | وزنweight |
محاسبات
نگاشتها و قوانین در API گوگل هلث با API وب فیتبیت متفاوت است.
سطح فعالیت، METs و آستانههای گام
در رابط برنامهنویسی کاربردی گوگل هلث، سطح فعالیت دقیقه به دقیقه کاربر از معادل متابولیک وظیفه (MET) و تعداد گامهای او استخراج میشود.
| سطح فعالیت | دستگاههای ضربان قلب | دستگاههای غیر ضربان قلب |
|---|---|---|
| کمتحرک | ≤ ۱.۵ METs | ≤ ۱.۵ METs |
| کمی فعال | > 1.5 METs و ≤ 4.2 METs | > ۱.۵ METs و ≤ ۳.۵ METs |
| نسبتاً فعال | > ۴.۲ METs و < ۶.۰ METs (مگر اینکه شرایط مربوط به حالت بسیار فعال برقرار باشد) | > 3.5 METs و < 6.0 METs (مگر اینکه شرایط مربوط به حالت بسیار فعال برقرار باشد) |
| بسیار فعال | ≥ ۶.۰ METs، یا ≥ ۵.۰ METs با سرعت گام ۱۵۰ گام در دقیقه یا بیشتر | ≥ ۶.۰ METs، یا ≥ ۵.۰ METs با سرعت گام ۱۵۰ گام در دقیقه یا بیشتر |
دقایق فعال شامل دقایق ترکیبی MODERATELY_ACTIVE و VERY_ACTIVE است. با این حال، یک دقیقه بسیار فعال فقط در صورتی ثبت میشود که در یک دوره حداقل ۱۰ دقیقهای مداوم رخ دهد و حداکثر ۲ دقیقه وقفه با فعالیت کمتر مجاز باشد.
دقایق بیتحرکی و خواب
دقایق بیتحرکی شامل زمان خواب نمیشود. در محاسبهی روزانه، دقایق بیتحرکی با کم کردن دقایق خواب و دقایق فعال (کمفعال، نسبتاً فعال و بسیار فعال) از کل دقایق روز (۱۴۴۰ دقیقه) محاسبه میشود:
Sedentary Minutes = 1440 - Sleep Minutes - Lightly Active Minutes - Moderately Active Minutes - Very Active Minutes
شاخص توده بدنی (BMI)
از آنجا که رابط برنامهنویسی کاربردی گوگل هلث (Google Health API) نوع دادهی BMI داخلی را نمایش نمیدهد، برنامهها باید شاخص توده بدنی (BMI) را در سمت کلاینت با استفاده از رکوردهای قد و وزن محاسبه کنند:
- وزن کاربر را بر حسب گرم از فیلد
weightGramsدر نوع داده Weight بازیابی کنید. این مقدار را به کیلوگرم (تقسیم بر ۱۰۰۰) یا پوند (تقسیم بر ۴۵۳.۵۹۲۳۷) تبدیل کنید. - قد کاربر را بر حسب میلیمتر از فیلد
heightMillimetersدر نوع داده Height بازیابی کنید. این مقدار را به متر (تقسیم بر ۱۰۰۰) یا اینچ (تقسیم بر ۲۵.۴) تبدیل کنید. - برای محاسبه مقدار BMI از یکی از فرمولهای زیر استفاده کنید:
- فرمول متریک:
BMI = weight (kg) / [height (m)]^2 - فرمول امپریال:
BMI = (weight (lbs) / [height (in)]^2) * 703
- فرمول متریک:
مقادیر BMI حاصل با دستههای زیر مطابقت دارند:
| دسته وزنی | محدوده BMI |
|---|---|
| کمبود وزن | زیر ۱۸.۵ |
| وزن سالم | ۱۸.۵ تا ۲۴.۹ |
| اضافه وزن | ۲۵ تا ۲۹.۹ |
| چاق | ۳۰ یا بالاتر |
میزان متابولیسم پایه (BMR)
میزان متابولیسم پایه (BMR) حداقل تعداد کالری مورد نیاز برای عملکردهای اساسی بدن در حالت استراحت است. از آنجا که API گوگل هلث نوع داده BMR داخلی را ارائه نمیدهد، برنامهها باید آن را با استفاده از فرمول هریس-بندیکت در سمت کلاینت محاسبه کنند. برای کسب اطلاعات بیشتر به مقاله معادله هریس-بندیکت در ویکیپدیا مراجعه کنید.
برای انجام این محاسبه:
- وزن کاربر را بر حسب گرم از فیلد
weightGramsدر نوع داده Weight بازیابی کنید و به کیلوگرم تبدیل کنید (بر ۱۰۰۰ تقسیم کنید). برای تبدیل پوند به کیلوگرم، بر ۲.۲ تقسیم کنید. - قد کاربر را بر حسب میلیمتر از فیلد
heightMillimetersدر نوع داده Height بازیابی کنید و به سانتیمتر تبدیل کنید (بر ۱۰ تقسیم کنید). برای تبدیل اینچ به سانتیمتر، عدد را در ۲.۵۴ ضرب کنید. - سن کاربر را به سال از فیلد
ageدر منبع Profile بازیابی کنید. - جنسیت بیولوژیکی را به طور مستقل بازیابی کنید (برای مثال، با درخواست از کاربر یا نگهداری آن در پایگاه داده خودتان)، زیرا 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 تغییر میکند.
- سینتکس نقطه پایانی : رابط برنامهنویسی کاربردی گوگل هلث از تعداد محدودی نقطه پایانی پشتیبانی میکند که میتوانند توسط اکثر انواع دادههای پشتیبانیشده مورد استفاده قرار گیرند. این امر سینتکس ثابتی را برای همه انواع دادهها فراهم میکند و استفاده از نقاط پایانی را آسانتر میسازد.
- شناسه کاربر : یا شناسه کاربر یا me باید در سینتکس نقطه پایانی مشخص شوند. هنگام استفاده از me، شناسه کاربر از توکن دسترسی استنباط میشود.
مثال : در اینجا مثالی از نقطه پایانی GET Profile که با استفاده از API Google Health فراخوانی شده است، آورده شده است.
دریافت کنید https://health.googleapis.com/v4/users/me/profile
نگاشتهای نقطه پایانی
برای مشاهدهی فهرستی از انواع دادههای موجود و روشهای API که پشتیبانی میکنند، به جدول انواع دادههای API گوگل هلث مراجعه کنید.
| نوع نقطه پایانی Fitbit Web API | رابط برنامهنویسی کاربردی گوگل هلث |
|---|---|
| GET (گزارش | خلاصه | خلاصه روزانه) که در آن درخواست دادههای یک روز را دارید | متد dailyRollup با windowSize = 1 روز |
| دریافت (درونروزی) جایی که دادههای جزئی را درخواست میکنید | روش list |
| دریافت (سری زمانی) بر اساس تاریخ یا بازه زمانی | متد rollUp یا dailyRollUp شامل یک محدوده تاریخ |
| دریافت (لیست گزارش) | روش list |
| ایجاد و بهروزرسانی لاگها | روش patch |
| حذف گزارشها | batchDelete |
| دریافت پروفایل | users.getProfile اطلاعات خاص کاربر را برمیگرداند.users.getSettings واحدها و مناطق زمانی کاربر را برمیگرداند. |
| بهروزرسانی پروفایل | users.updateProfile اطلاعات خاص کاربر را تغییر میدهد.users.updateSettings واحدها و مناطق زمانی کاربر را تغییر میدهد. |
| دریافت شناسه کاربری | users.getIdentity شناسه کاربری قدیمی Fitbit و شناسه کاربری گوگل کاربر را برمیگرداند. |
| دستگاهها را دریافت کنید | users.pairedDevices لیست دستگاههای جفتشده را برمیگرداند. |
| ایجاد اشتراک | projects.subscribers.subscriptions.create به صورت دستی یک اشتراک ایجاد میکند. |
| اشتراکها را حذف کنید | projects.subscribers.subscriptions.delete حذف یک اشتراک |
| دریافت لیست اشتراکها | projects.subscribers.subscriptions.list همه اشتراکها را فهرست میکند. |