رابط برنامهنویسی کاربردی گوگل هلث (Google Health API) یک رابط برنامهنویسی کاربردی جدید است که از پایه ساخته شده و به توسعهدهندگان اجازه میدهد تا دادههای کاربران فیتبیت (Fitbit) را جستجو کنند. این فقط یک بهروزرسانی نیست، بلکه یک حرکت استراتژیک برای اطمینان از ایمن، قابل اعتماد بودن و آماده بودن برنامههای شما برای پیشرفتهای آینده در فناوری سلامت است. این رابط برنامهنویسی کاربردی از یک کنسول جدید برای ثبت برنامههای شما، پشتیبانی از Google OAuth 2.0، انواع دادههای جدید، طرحواره نقطه پایانی جدید و قالب پاسخ جدید پشتیبانی میکند.
این راهنما به گونهای طراحی شده است که به توسعهدهندگان کمک کند تا برنامههای Fitbit Web API موجود خود را به Google Health API جدید منتقل کنند.
چرا باید مهاجرت کرد؟
مزایای استفاده از API گوگل هلث عبارتند از:
- امنیت پیشرفته : انطباق با بهترین شیوههای امنیتی گوگل، همسو با استانداردهای امنیتی، حریم خصوصی و هویت گوگل.
- سازگاری : ناسازگاریهای قدیمی در قالبهای دادهها، مناطق زمانی، واحدهای اندازهگیری و مدیریت خطا را برای یک تجربه توسعهدهنده شهودیتر از بین میبرد.
- مقیاسپذیری و آیندهنگر : طراحی شده برای مقیاسپذیری جهت پاسخگویی به نیازهای آینده و پشتیبانی از پروتکلهای مدرن مانند gRPC.
ثبت نام برنامه
همه برنامههای Google Health API باید با استفاده از کنسول Google Cloud ثبت شوند، که به عنوان یک مرکز اصلی برای مدیریت همه برنامههای Google شما عمل میکند.
برای دستورالعمل نحوه ثبت برنامه خود، مراحل موجود در بخش «شروع به کار» را دنبال کنید. در اینجا تفاوتهایی که هنگام ثبت برنامههای خود متوجه خواهید شد، آورده شده است.
| رابط برنامهنویسی کاربردی وب فیتبیت | رابط برنامهنویسی کاربردی گوگل هلث | |
| لینک(های) عمومی | https://dev.fitbit.com/apps | https://console.cloud.google.com |
| اضافه شدن یک برنامه جدید | ثبت یک برنامه جدید را فشار دهید |
|
| اطلاعات پایه | فیلدهایی که باید تکمیل شوند:
| فیلدهایی که باید تکمیل شوند:
|
| انواع برنامه | یک توسعهدهنده موظف است موارد زیر را انتخاب کند:
|
|
| شناسه مشتری | هنگام ذخیره تنظیمات برنامه ثبت میشود | جداگانه ثبت شده |
| نوع دسترسی | دسترسی خواندن و نوشتن در سطح برنامه کنترل میشود | دسترسی خواندن و نوشتن در سطح دامنه کنترل میشود. |
| آدرسهای اینترنتی اضافی |
|
|
پیادهسازی OAuth
برنامههای Google Health API فقط از کتابخانههای کلاینت Google OAuth2 پشتیبانی میکنند. کتابخانههای کلاینت برای چارچوبهای محبوب در دسترس هستند که پیادهسازی OAuth 2.0 را سادهتر میکند. تفاوتهای بین کتابخانههای Google OAuth2 و کتابخانههای متنباز OAuth2 به شرح زیر است:
| رابط برنامهنویسی کاربردی وب فیتبیت | رابط برنامهنویسی کاربردی گوگل هلث | |
| پشتیبانی از کتابخانه OAuth2 | متنباز | کتابخانههای کلاینت Google OAuth2 |
| عملکرد | ناهماهنگی در پلتفرمهای مختلف | سازگار در پلتفرمهای مختلف |
| آدرس اینترنتی مجوز | https://www.fitbit.com/oauth2/authorize | https://accounts.google.com/o/oauth2/v2/auth |
| آدرس اینترنتی توکن | https://api.fitbit.com/oauth2/token | https://oauth2.googleapis.com/token |
| طول عمر توکن دسترسی | ۸ ساعت | ۱ ساعت |
| اندازه توکن دسترسی | ۱۰۲۴ بایت | ۲۰۴۸ بایت |
| توکن تازهسازی | توکنهای بهروزرسانی هنگام استفاده از جریان اعطای کد مجوز ایجاد میشوند. فقط ۱ توکن بهروزرسانی میتواند برای یک کاربر ایجاد شود. توکنها هرگز منقضی نمیشوند و فقط یک بار میتوان از آنها استفاده کرد. | برای تولید یک توکن بهروزرسانی، رشته مجوز باید شامل پارامتر پرسوجوی "access_type=offline" باشد. میتوان چندین توکن بهروزرسانی برای یک کاربر ایجاد کرد. توکنهای بهروزرسانی میتوانند مبتنی بر زمان باشند. اگر در عرض ۶ ماه استفاده نشوند، به کاربر دسترسی مبتنی بر زمان داده شود یا برنامه در حالت "آزمایش" باشد، منقضی میشوند. برای جزئیات بیشتر به انقضای توکن بهروزرسانی مراجعه کنید. |
| پاسخ توکن | پاسخ JSON شامل موارد زیر است:
| پاسخ JSON شامل موارد زیر است:
برای دریافت شناسه کاربر، از نقطه پایانی users.getIdentity استفاده کنید. |
احراز هویت مجدد کاربر (رضایت مجدد اجباری)
کاربران Fitbit باید دوباره با ادغام جدید شما موافقت کنند، زیرا برنامه شما از کتابخانه OAuth متفاوتی استفاده میکند. انتقال توکنهای دسترسی و توکنهای بهروزرسانی به API گوگل هلث و کار کردن آنها امکانپذیر نیست.
محدودهها
برای استفاده از محدودههای API گوگل هلث، باید درخواست مجوز خود را بهروزرسانی کنید. محدودهها مشخص میکنند که آیا برنامه شما از عملیات خواندن یا نوشتن پشتیبانی میکند یا خیر. از محدودههایی که برای برنامه شما ضروری نیستند استفاده نکنید. در صورت تغییر طراحی برنامه، همیشه میتوانید بعداً محدودههای بیشتری اضافه کنید.
محدودههای API گوگل هلث یک URL HTTP هستند که با https://www.googleapis.com/auth/googlehealth.{scope} شروع میشوند. برای مثال، https://www.googleapis.com/auth/googlehealth.activity_and_fitness.
نگاشتهای محدوده
در اینجا نحوهی نگاشت محدودههای Fitbit Web API به محدودههای Google Health API نشان داده شده است:
| دامنههای API وب Fitbit | محدودههای API سلامت گوگل |
|---|---|
| فعالیت | فعالیت_و_تناسب_اندام .فعالیت_و_تناسب_اندام.فقط_خواندنی |
| تناسب اندام_قلبی | فعالیت_و_تناسب_اندام .فعالیت_و_تناسب_اندام.فقط_خواندنی |
| ضربان قلب | .معیارها_و_اندازهگیریهای_سلامت .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی |
| مکان | .مکان.فقط خواندنی |
| تغذیه | .تغذیه .تغذیه.فقط خواندنی |
| اشباع اکسیژن | .معیارها_و_اندازهگیریهای_سلامت .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی |
| پروفایل | پروفایل .profile.فقط خواندنی |
| میزان_تنفس | .معیارها_و_اندازهگیریهای_سلامت .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی |
| تنظیمات | تنظیمات تنظیمات.فقط خواندنی |
| خواب | خواب .sleep.only (فقط خواندنی) |
| دما | .معیارها_و_اندازهگیریهای_سلامت .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی |
| وزن | .معیارها_و_اندازهگیریهای_سلامت .معیارها_و_اندازهگیریهای_سلامت.فقط_خواندنی |
انواع داده
در اینجا لیستی از انواع دادههای API گوگل هلث و نحوهی نگاشت آنها به API وب فیتبیت ارائه شده است.
| نوع دادهی Web API فیتبیت | نوع داده API سلامت گوگل شناسه نقطه پایانی |
|---|---|
| صورتجلسات منطقه فعال | صورتجلسات منطقه فعالactive-zone-minutes |
| شامل تغییراتی در سطوح فعالیت کاربر است | سطح فعالیتactivity-level |
| ارتفاع | ارتفاعaltitude |
| چربی بدن | چربی بدنbody-fat |
caloriesOut در هر منطقه ضربان قلب | کالری در منطقه ضربان قلبcalories-in-heart-rate-zone |
| خلاصه HRV | تغییرپذیری روزانه ضربان قلبdaily-heart-rate-variability |
| خلاصه SpO2 | اشباع اکسیژن روزانهdaily-oxygen-saturation |
| ضربان قلب در حالت استراحت | ضربان قلب در حالت استراحت روزانهdaily-resting-heart-rate |
| دمای پوست | مشتقات دمای خواب روزانهdaily-sleep-temperature-derivations |
| فاصله | فاصلهdistance |
| فعالیت ثبت شده | ورزشexercise |
| طبقات | طبقاتfloors |
| ضربان قلب | ضربان قلبheart-rate |
| HRV روزانه | تغییرپذیری ضربان قلبheart-rate-variability |
| SpO2 روزانه | اشباع اکسیژنoxygen-saturation |
| مقدار VO2 Max هنگام دویدن کاربر | حداکثر اکسیژن مصرفی (VO2 Max) را بدویدrun-vo2-max |
| سری زمانی فعالیت، دقیقههای بیتحرک | دوره کم تحرکیsedentary-period |
| خواب | خوابsleep |
| مراحل | مراحلsteps |
caloriesOut مصرفی فعالیت | کل کالریtotal-calories |
| مقدار حداکثر اکسیژن مصرفی (VO2 Max) | حداکثر اکسیژن مصرفی (VO2 Max)vo2-max |
| وزن | وزنweight |
نقاط پایانی
نقاط پایانی REST برای همه انواع داده، یک سینتکس (نحو) ثابت را اتخاذ میکنند.
- نقطه پایانی سرویس : آدرس اینترنتی HTTP پایه به https://health.googleapis.com تغییر میکند.
- سینتکس نقطه پایانی : رابط برنامهنویسی کاربردی گوگل هلث از تعداد محدودی نقطه پایانی پشتیبانی میکند که میتوانند توسط اکثر انواع دادههای پشتیبانیشده مورد استفاده قرار گیرند. این امر سینتکس ثابتی را برای همه انواع دادهها فراهم میکند و استفاده از نقاط پایانی را آسانتر میسازد.
- شناسه کاربر : یا شناسه کاربر یا me باید در سینتکس نقطه پایانی مشخص شوند. هنگام استفاده از me، شناسه کاربر از توکن دسترسی استنباط میشود.
مثال : در اینجا مثالی از نقطه پایانی GET Profile که با استفاده از API Google Health فراخوانی شده است، آورده شده است.
دریافت کنید https://health.googleapis.com/v4/users/me/profile
نگاشتهای نقطه پایانی
برای مشاهدهی فهرستی از انواع دادههای موجود و متدهای API که پشتیبانی میکنند، به جدول «دسترسی به انواع دادهها» مراجعه کنید.
| نوع نقطه پایانی Fitbit Web API | رابط برنامهنویسی کاربردی گوگل هلث |
| GET (گزارش | خلاصه | خلاصه روزانه) که در آن درخواست دادههای یک روز را دارید | متد dailyRollup با windowSize = 1 روز |
| دریافت (درونروزی) جایی که دادههای جزئی را درخواست میکنید | روش فهرست |
| دریافت (سری زمانی) بر اساس تاریخ یا بازه زمانی | متد rollUp یا dailyRollUp شامل یک محدوده تاریخ |
| دریافت (لیست گزارش) | روش فهرست |
| ایجاد و بهروزرسانی لاگها | روش وصله |
| حذف گزارشها | متد حذف دستهای |
| دریافت پروفایل | users.getProfile اطلاعات خاص کاربر را برمیگرداند. users.getSettings واحدها و مناطق زمانی کاربر را برمیگرداند. |
| بهروزرسانی پروفایل | users.updateProfile اطلاعات خاص کاربر را تغییر میدهد. users.updateSettings واحدها و مناطق زمانی کاربر را تغییر میدهد. |
| دریافت شناسه کاربری | users.getIdentity شناسه کاربری قدیمی Fitbit و شناسه کاربری گوگل کاربر را برمیگرداند. |
کاربران خود را منتقل کنید
مهاجرت از API وب Fitbit به API گوگل هلث چیزی بیش از یک بهروزرسانی فنی است. کاربران شما باید به دلیل تغییر کتابخانه OAuth، دوباره با ادغام جدید شما موافقت کنند. انتقال توکنهای دسترسی و توکنهای بهروزرسانی به API گوگل هلث و کار کردن آنها امکانپذیر نیست. برای کمک به حفظ کاربر در طول مهاجرت، در اینجا چند پیشنهاد فنی و استراتژیک برای یک مهاجرت موفق ارائه شده است.
استراتژی کتابخانه دوگانه
از آنجا که Fitbit Web API و Google Health API از کتابخانههای OAuth2 متفاوتی استفاده میکنند، شما باید یک دوره "پل زدن" را مدیریت کنید که در آن هر دو کتابخانه در پایگاه کد شما وجود داشته باشند.
مدیریت مجوز موازی
- کپسولهسازی کلاینتها : یک لایه انتزاعی یا رابط برای «سرویس سلامت» خود ایجاد کنید. این به بقیه برنامه شما اجازه میدهد بدون دانستن اینکه کدام کتابخانه (Fitbit OAuth در مقابل Google OAuth) برای آن کاربر خاص فعال است، دادهها را درخواست کند.
- بهروزرسانی طرحواره پایگاه داده : جدول کاربر خود را بهروزرسانی کنید تا شامل یک پرچم
oauth_typeباشد. برای مثال، برای Fitbit OAuth ازfitbitو برای Google OAuthgoogleاستفاده کنید.- کاربران جدید : پیشفرض روی API سلامت گوگل و کتابخانه OAuth گوگل.
oauth_typeرا رویgoogleتنظیم کنید. - کاربران فعلی : تا زمانی که جریان رضایت مجدد را تکمیل کنند، در Fitbit Web API باقی میمانند.
oauth_typeرا رویfitbitتنظیم کنید.
- کاربران جدید : پیشفرض روی API سلامت گوگل و کتابخانه OAuth گوگل.
جریان «افزایشی» رضایت مجدد
به جای اجبار به خروج از سیستم، از رویکرد افزایشی مجوز استفاده کنید:
- تشخیص توکن متنباز Fitbit : وقتی یک کاربر Fitbit Web API برنامه را باز میکند، یک اعلان «بهروزرسانی سرویس» نمایش داده میشود.
- راهاندازی جریان OAuth گوگل : وقتی کاربر روی «بهروزرسانی» کلیک میکند، جریان کتابخانه OAuth2 گوگل آغاز میشود.
- جایگزینی و ابطال : پس از دریافت موفقیتآمیز توکن OAuth گوگل، آن را در پروفایل کاربر ذخیره کنید،
oauth_typeازfitbitبهgoogleبهروزرسانی کنید و (در صورت امکان) توکن قدیمیfitbitرا به صورت برنامهنویسی ابطال کنید تا پروفایل امنیتی کاربر پاک بماند.
به حداکثر رساندن نرخ حفظ کاربر
رضایت مجدد، «منطقه خطر» برای ریزش کاربر است. برای جلوگیری از ترک اپلیکیشن توسط کاربران، این بهترین شیوههای تجربه کاربری را دنبال کنید:
ارتباط «ارزش-محور»
با عبارت «ما API خود را بهروزرسانی کردیم» شروع نکنید. با مزایای سیستم جدید تحت پشتیبانی گوگل شروع کنید:
- امنیت پیشرفته : به محافظت از حسابهای کاربری و احراز هویت دو مرحلهای پیشرو در صنعت گوگل اشاره کنید.
- قابلیت اطمینان : زمان همگامسازی سریعتر و اتصالات داده پایدارتر.
- بهروزرسانی ویژگیها : به آرامی به کاربران اطلاع دهید که ویژگیها و انواع دادههای جدید نیاز به بهروزرسانی دارند.
زمانبندی هوشمند
- وظایف با ارزش بالا را قطع نکنید : هرگز صفحه رضایت مجدد را در حالی که کاربر در حال تمرین یا ثبت اطلاعات غذایی است، فعال نکنید.
- مرحله «هل دادن» : برای 30 روز اول، از یک بنر قابل رد کردن استفاده کنید.
- مرحله «قطع کامل دسترسی» : فقط پس از چند هفته هشدار، رضایت مجدد را اجباری کنید، که مصادف با مهلتهای رسمی منسوخ شدن Fitbit Web API است.
مقایسه جریان مهاجرت
یک تمایز بصری واضح بین جریانهای قدیمی و جدید به توسعهدهندگان کمک میکند تا بفهمند منطق از کجا منشعب میشود.
| ویژگی | رابط برنامهنویسی کاربردی وب فیتبیت (قدیمی) | رابط برنامهنویسی کاربردی گوگل هلث (گوگل-هویت) |
| کتابخانه Auth | استاندارد متنباز | سرویسهای هویت گوگل (GIS) / گوگل آث |
| حسابهای کاربری | اعتبارنامههای قدیمی فیتبیت | حساب گوگل |
| نوع توکن | دسترسی/رفرش مخصوص فیتبیت | توکنهای دسترسی/بهروزرسانی صادر شده توسط گوگل |
| مدیریت محدوده | مجوزهای گسترده | مجوزهای جزئی/افزایشی |
مدیریت جزئیات انتقال حساب کاربری
طبق مستندات Fitbit، کاربرانی که حساب خود را به گوگل منتقل میکنند، معمولاً بلافاصله اتصالات شخص ثالث خود را از دست نمیدهند، اما تغییر نسخه API یک الزام از طرف توسعهدهنده است.
- بررسی اعتبار توکن : از یک ابزار پسزمینه برای بررسی اینکه آیا توکنهای Fitbit با خطای «غیرمجاز» از کار میافتند یا خیر، استفاده کنید. این ممکن است نشان دهد که کاربر حساب خود را منتقل کرده است اما برنامه شما هنوز به آن متصل نشده است.
- شکستهای دلپذیر : اگر فراخوانی Fitbit OAuth با شکست مواجه شود، کاربر را به صفحه سفارشی "Reconnect Fitbit" که به طور خاص از جریان جدید Google OAuth استفاده میکند، هدایت میکند.
مثال کد
برای مهاجرت از API وب قدیمی Fitbit به API سلامت گوگل، شما از کتابخانههای عمومی OAuth2 به کتابخانه احراز هویت گوگل منتقل خواهید شد. در ادامه یک پیشنهاد معماری و یک پیادهسازی شبهکد نوشته شده در جاوا اسکریپت برای مدیریت این حالت "کتابخانه دوگانه" ارائه شده است.
۱. «سوئیچ میانافزار»
از آنجایی که نمیتوانید همه کاربران را به طور همزمان منتقل کنید، backend شما باید بر اساس apiVersion فعلی کاربر که در پایگاه داده شما ذخیره شده است، تعیین کند که از کدام کتابخانه استفاده کند.
پیادهسازی
const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;
// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
process.env.GOOGLE_CLIENT_ID,
process.env.GOOGLE_CLIENT_SECRET,
process.env.REDIRECT_URI
);
// 2. Create a Unified Fetcher
async function fetchSteps(user) {
if (user.apiVersion === 4) {
// ---- GOOGLE OAUTH LIBRARY LOGIC ----
GHAClient.setCredentials({ refresh_token: user.refreshToken });
const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
const res = await GHAClient.request({ url });
return res.data;
} else {
// ---- FITBIT WEB API LEGACY LOGIC ----
// Use your existing Fitbit open-source library logic here
return callLegacyV1Api(user.accessToken);
}
}
۲. جریان تجربه کاربری (UX) را منتقل کنید
برای به حداکثر رساندن ماندگاری، از الگوی «وقفه و ارتقا» استفاده کنید. این تضمین میکند که کاربر تا زمانی که با برنامه درگیر نشده است، مجبور به ورود مجدد نباشد.
منطق تغییر مسیر
وقتی کاربر Fitbit Web API به یک ویژگی خاص برخورد میکند، مهاجرت را آغاز کن:
app.get('/dashboard', async (req, res) => {
const user = await db.users.find(req.user.id);
if (user.apiVersion === 1) {
// Render a "soft" migration page explaining the Google transition
return res.render('migrate-to-google', {
title: "Keep your data syncing",
message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
});
}
const data = await fetchSteps(user);
res.render('dashboard', { data });
});
۳. گذارهای فنی کلیدی
هنگام نوشتن اسکریپتهای مهاجرت جاوا اسکریپت، این تفاوتها را در نظر داشته باشید:
| ویژگی | رابط برنامهنویسی کاربردی وب فیتبیت (قدیمی) | رابط برنامهنویسی کاربردی گوگل هلث (گوگل-هویت) |
| نقطه پایانی توکن | https://api.fitbit.com/oauth2/token | https://oauth2.googleapis.com/token |
| کتابخانه Auth | استاندارد متنباز | گوگل ادوردز |
| دامنه | فعالیت | https://www.googleapis.com/auth/googlehealth.activity_and_fitness |
| شناسه کاربری | شناسه رمزگذاری شده Fitbit در پاسخ /oauth2/token بازگردانده شد | شناسه کاربری از نقطه پایانی users.getIdentity بازگردانده میشود |
۴. چک لیست حفظ مشتری
- ماندگاری جلسه : تا زمانی که access_token مربوط به Google Health API با موفقیت تأیید و در پایگاه داده شما ذخیره نشده است، جلسه قدیمی Fitbit Web API کاربر را پاک نکنید.
- لغو خودکار : پس از تکمیل مهاجرت API گوگل هلث، از یک درخواست POST به نقطه پایانی لغو قدیمی Fitbit استفاده کنید: https://api.fitbit.com/oauth2/revoke. این تضمین میکند که کاربر مجوزهای برنامه "تکراری" را در تنظیمات Fitbit خود مشاهده نمیکند.
- مدیریت خطا : اگر یک تماس Fitbit خطای ۴۰۱ Unauthorized را برگرداند، به جای نمایش پیام خطا، به طور خودکار به جریان Google OAuth هدایت میشود.