מדריך להעברת נתונים (מיגרציה)

‫Google Health API הוא API חדש שנבנה מאפס ומאפשר למפתחים לשלוח שאילתות לגבי נתוני משתמשים ב-Fitbit. זה לא רק עדכון, אלא מהלך אסטרטגי שמטרתו לוודא שהאפליקציות שלכם בטוחות, אמינות ומוכנות להתפתחויות עתידיות בטכנולוגיות בתחום הבריאות. ה-API תומך במסוף חדש לרישום האפליקציות, בתמיכה ב-Google OAuth 2.0, בסוגי נתונים חדשים, בסכימת נקודות קצה חדשה ובפורמט תגובה חדש.

המדריך הזה נועד לעזור למפתחים להעביר את האפליקציות הקיימות שלהם של Fitbit Web API אל Google Health API החדש.

למה כדאי לבצע את ההעברה

היתרונות של שימוש ב-Google Health API:

  • אבטחה משופרת: עמידה בשיטות המומלצות של Google לאבטחה, בהתאם לתקני האבטחה, הפרטיות והזהות של Google.
  • עקביות: הממשק החדש מבטל אי-עקביות מדור קודם בפורמטים של נתונים, באזורי זמן, ביחידות מידה ובטיפול בשגיאות, וכך משפר את חוויית המפתחים.
  • יכולת הרחבה והיערכות לעתיד: המערכת מתוכננת להתרחב כדי לעמוד בדרישות עתידיות, והיא תומכת בפרוטוקולים מודרניים כמו gRPC.

רישום אפליקציה

כל האפליקציות של Google Health API צריכות להיות רשומות באמצעות Google Cloud Console, שמשמש כמרכז לניהול כל האפליקציות של Google.

הוראות לרישום האפליקציה מופיעות במאמר תחילת העבודה. אלה ההבדלים שתבחינו בהם כשאתם רושמים את האפליקציות.

‫Fitbit Web API ‫Google Health API
קישורים שגלויים לכולם https://dev.fitbit.com/apps https://console.cloud.google.com
הוספת אפליקציה חדשה לוחצים על Register a new app (רישום אפליקציה חדשה).
  1. יצירת פרויקט ב-Google Cloud
  2. הפעלת Google Health API
פרטים בסיסיים השדות שצריך למלא:
  • שם האפליקציה
  • תיאור
  • כתובת ה-URL של אתר האפליקציה
  • ארגון
  • כתובת ה-URL של האתר של הארגון
  • כתובת ה-URL של התנאים וההגבלות
  • כתובת אתר של מדיניות פרטיות
 השדות שצריך למלא:
  • שם אפליקציה
  • כתובת אימייל לתמיכה
  • קהל (פנימי או חיצוני)
  • אימייל ליצירת קשר
  • סמל הלוגו
  • כתובת ה-URL של אתר האפליקציה
  • כתובת URL של מדיניות פרטיות
  • כתובת ה-URL של התנאים וההגבלות
  • דומיין מורשה
סוגי אפליקציות המפתח צריך לבחור:
  • שרת
  • לקוח
  • Personal
  • אפליקציית אינטרנט
  • Android
  • תוסף ל-Chrome
  • iOS
  • טלוויזיות
  • אפליקציה לשולחן העבודה
  • פלטפורמת Universal Windows
Client-ID הרישום מתבצע כששומרים את הגדרות האפליקציה רשום בנפרד
סוג הגישה גישת קריאה וכתיבה נשלטת ברמת האפליקציה גישת קריאה וכתיבה נשלטת ברמת ההיקף
כתובות URL נוספות
  • כתובת URL להפניה מחדש: האתר שאליו המשתמשים מופנים אחרי שהם מאשרים את היקפי ההרשאות
  • מקורות מורשים של JavaScript: מקור HTTP שמארח את אפליקציית האינטרנט
  • כתובת URL להפניה מחדש: האתר שאליו המשתמשים מופנים אחרי שהם מאשרים את היקפי ההרשאות

הטמעה של OAuth

אפליקציות של Google Health API תומכות רק בספריות הלקוח של Google OAuth2. יש ספריות לקוח למסגרות פופולריות, ולכן קל יותר להטמיע OAuth 2.0. ההבדלים בין ספריות Google OAuth2 לבין ספריות OAuth2 בקוד פתוח הם:

‫Fitbit Web API ‫Google Health API
תמיכה בספריית OAuth2 קוד פתוח ספריות לקוח של Google OAuth2
פונקציונליות חוסר עקביות בין הפלטפורמות עקביות בפלטפורמות שונות
כתובת URL של הרשאה https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
כתובת URL לטוקן https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
משך החיים של טוקן גישה 8 שעות שעה אחת
גודל טוקן הגישה ‫1,024 בייטים ‫2048 בייטים
רענון הטוקן טוקני רענון נוצרים כשמשתמשים בתהליך הענקת קוד הרשאה. אפשר ליצור רק אסימון רענון אחד לכל משתמש. הטוקנים לא פוקעים לעולם ואפשר להשתמש בהם רק פעם אחת. כדי ליצור טוקן רענון, מחרוזת ההרשאה צריכה להכיל את פרמטר השאילתה access_type=offline. אפשר ליצור כמה טוקנים לרענון עבור משתמש יחיד. אסימוני רענון יכולים להיות מבוססים על זמן. הם יפוגו אם לא נעשה בהם שימוש במשך 6 חודשים, אם המשתמש העניק גישה מוגבלת בזמן או אם האפליקציה במצב 'בדיקה'. פרטים נוספים זמינים במאמר בנושא תפוגה של אסימון רענון.
תגובת טוקן תגובת ה-JSON מכילה:
  • טוקן גישה
  • תפוגה של טוקן גישה
  • היקפים
  • סוג הטוקן
  • טוקן רענון
  • מזהה משתמש
 תגובת ה-JSON מכילה:
  • טוקן גישה
  • תפוגה של טוקן גישה
  • היקפים
  • סוג הטוקן
  • טוקן רענון

כדי לקבל את מזהה המשתמש, משתמשים בנקודת הקצה users.getIdentity.

משתמשי Fitbit צריכים להביע הסכמה מחדש לשילוב החדש, כי האפליקציה שלך משתמשת בספריית OAuth אחרת. אי אפשר להעביר טוקנים של גישה וטוקנים של רענון אל Google Health 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.

מיפויי היקף הרשאות

כך ממופים ההיקפים של Fitbit Web API להיקפים של Google Health API:

טבלה: מיפויים של היקפי Fitbit Web API ל-Google Health API
היקפי Fitbit Web API היקפי הגישה של Google Health API
פעילות ‪.activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness ‪.activity_and_fitness
.activity_and_fitness.readonly
קצב לב ‪.health_metrics_and_measurements
.health_metrics_and_measurements.readonly
location .location.readonly
תזונה ‪.nutrition
.nutrition.readonly
oxygen_saturation ‪.health_metrics_and_measurements
.health_metrics_and_measurements.readonly
פרופיל ‪.profile
.profile.readonly
respiratory_rate ‪.health_metrics_and_measurements
.health_metrics_and_measurements.readonly
הגדרות ‫.settings
‫.settings.readonly
שינה ‪.sleep
.sleep.readonly
טמפרטורה ‪.health_metrics_and_measurements
.health_metrics_and_measurements.readonly
משקל ‪.health_metrics_and_measurements
.health_metrics_and_measurements.readonly

סוגי נתונים

בהמשך מפורטים סוגי הנתונים של Google Health API והמיפוי שלהם ל-Fitbit Web API.

טבלה: מיפוי סוגי הנתונים מ-Fitbit Web API ל-Google Health API
סוג הנתונים של Fitbit Web API סוג הנתונים של Google Health API
  מזהה נקודת הקצה
דקות טווח דופק דקות טווח דופק
  active-zone-minutes
כולל שינויים ברמות הפעילות של המשתמש רמת הפעילות
  activity-level
גובה גובה
  altitude
אחוז השומן בגוף Body Fat
  body-fat
caloriesOut בכל טווח דופק ‫Calories In Heart Rate Zone
  calories-in-heart-rate-zone
סיכום HRV Daily Heart Rate Variability
  daily-heart-rate-variability
סיכום סטורציה Daily Oxygen Saturation
  daily-oxygen-saturation
הדופק במנוחה דופק במנוחה יומי
  daily-resting-heart-rate
טמפרטורת העור Daily Sleep Temperature Derivations
  daily-sleep-temperature-derivations
מרחק מרחק
  distance
פעילות מוקלטת תרגיל
  exercise
קומות Floors
  floors
דופק ‫Heart Rate (דופק)
  heart-rate
HRV Intraday שונות קצב הלב
  heart-rate-variability
נתוני סטורציה במהלך היום רמת החמצן בדם
  oxygen-saturation
ערך ה-VO2 Max כשהמשתמש רץ ‫Run VO2 Max
  run-vo2-max
סדרת זמן של דקות בישיבה תקופה בישיבה
  sedentary-period
שינה שינה
  sleep
שלבים Steps
  steps
פעילות caloriesOut ‫Total Calories
  total-calories
ערך צריכת החמצן המרבית (VO2 max) ‫VO2 Max
  vo2-max
משקל משקל
  weight

נקודות קצה

נקודות הקצה של 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

מיפוי נקודות קצה

בטבלה זמינות של סוגי נתונים מפורטים סוגי הנתונים הזמינים ושיטות ה-API שהם תומכים בהן.

Fitbit Web API Endpoint Type ‫Google Health API
‫GET (Log | Summary | Daily Summary) where you are requesting a single day of data ‫dailyRollup עם windowSize = 1 day
‫GET (במהלך היום) כשמבקשים נתונים מפורטים שיטת list
GET (Time Series) by Date or Interval השיטה rollUp או dailyRollUp כולל טווח תאריכים
GET (רשימת יומנים) שיטת list
יצירה ועדכון של יומנים שיטת patch
מחיקת יומנים השיטה batchDelete
GET Profile ‫users.getProfile מחזירה את הפרטים הספציפיים של המשתמש ‫
‫users.getSettings מחזירה את היחידות ואזורי הזמן של המשתמש
עדכון הפרופיל ‫users.updateProfile משנה את הפרטים הספציפיים של המשתמש ‫
users.updateSettings משנה את היחידות ואת אזורי הזמן של המשתמש
קבלת מזהה משתמש ‫users.getIdentity מחזירה את מזהה המשתמש ב-Fitbit בגרסה הקודמת וב-Google.

העברת המשתמשים

המעבר מ-Fitbit Web API אל Google Health API הוא יותר מעדכון טכני. המשתמשים שלכם צריכים להביע הסכמה מחדש לשילוב החדש, כי שינינו את ספריית OAuth. אי אפשר להעביר אסימוני גישה ואסימוני רענון אל Google Health API ולהשתמש בהם. כדי לעזור לכם לשמר את המשתמשים במהלך המיגרציה, ריכזנו כאן כמה הצעות טכניות ואסטרטגיות למיגרציה מוצלחת.

האסטרטגיה של שתי ספריות

מכיוון ש-Fitbit Web API ו-Google Health API משתמשים בספריות שונות של OAuth2, צריך לנהל תקופת גישור שבה שתי הספריות קיימות בבסיס הקוד.

ניהול הרשאות מקביל

  • הוספת שכבת הפשטה ללקוחות: יוצרים שכבת הפשטה או ממשק ל'שירות הבריאות'. כך שאר האפליקציה יכולה לבקש נתונים בלי לדעת איזו ספרייה (Fitbit OAuth או Google OAuth) פעילה עבור אותו משתמש ספציפי.
  • עדכון סכימת מסד הנתונים: צריך לעדכן את טבלת המשתמשים כדי לכלול דגל oauth_type. לדוגמה, משתמשים ב-fitbit עבור Fitbit OAuth וב-google עבור Google OAuth.
    • משתמשים חדשים: ברירת המחדל היא Google Health API וספריית Google OAuth. מגדירים את oauth_type לערך google.
    • משתמשים קיימים: ממשיכים להשתמש ב-Fitbit Web API עד שהם משלימים את תהליך ההסכמה מחדש. מגדירים את oauth_type לערך fitbit.

תהליך קבלת הסכמה חוזרת (Step-Up)

במקום לכפות יציאה מהחשבון, כדאי להשתמש בגישה של הרשאה מצטברת:

  1. זיהוי טוקן קוד פתוח של Fitbit: כשמשתמש ב-Fitbit Web API פותח את האפליקציה, מופעלת הודעה על עדכון שירות.
  2. הפעלת תהליך OAuth של Google: כשהמשתמש לוחץ על 'עדכון', מפעילים את תהליך ספריית OAuth2 של Google.
  3. החלפה וביטול: אחרי קבלת אסימון Google OAuth, שומרים אותו בפרופיל המשתמש, מעדכנים את oauth_type מ-fitbit ל-google, ואם אפשר, מבטלים באופן אוטומטי את האסימון הישן fitbit כדי לשמור על פרופיל האבטחה של המשתמש.

מקסום שימור המשתמשים

בקשת הסכמה חוזרת היא "אזור הסכנה" שבו יש סיכון לנטישה. כדי למנוע מצב שבו משתמשים נוטשים את האפליקציה, כדאי לפעול לפי השיטות המומלצות הבאות לשיפור חוויית המשתמש:

התקשורת שמתמקדת בערך

אל תתחילו במילים "עדכנו את ה-API שלנו". כדאי להתחיל עם היתרונות של המערכת החדשה שנתמכת על ידי Google:

  • אבטחה משופרת: כדאי לציין את ההגנה על החשבון של Google, שהיא מובילה בתחום, ואת האימות הדו-שלבי.
  • מהימנות: זמני סנכרון מהירים יותר וחיבורי נתונים יציבים יותר.
  • הגבלת גישה לתכונות: כדאי להודיע למשתמשים בצורה עדינה שנדרש עדכון כדי להשתמש בתכונות חדשות ובסוגי נתונים חדשים.

תזמון חכם

  • אל תפריעו למשימות חשובות: אל תציגו את מסך הבקשה להסכמה חוזרת בזמן שהמשתמש באמצע אימון או בזמן שהוא מתעד את האוכל שהוא אוכל.
  • שלב ה'תזכורת': במהלך 30 הימים הראשונים, מוצג באנר שאפשר לסגור.
  • השלב של 'הפסקת התמיכה': חובה לבקש הסכמה מחדש רק אחרי כמה שבועות של אזהרות, בהתאם למועדים הרשמיים להוצאה משימוש של Fitbit Web API.

השוואה בין תהליכי מיגרציה

ההבדלה החזותית הברורה בין התהליכים הישנים והחדשים עוזרת למפתחים להבין איפה ההיגיון מתפצל.

תכונה ‫Fitbit Web API (גרסה קודמת) ‫Google Health API (Google-Identity)
ספריית אימות קוד פתוח רגיל ‫Google Identity Services (GIS) / Google Auth
חשבונות משתמש פרטי כניסה מדור קודם של Fitbit חשבון Google
סוג הטוקן גישה או רענון ספציפיים ל-Fitbit טוקנים של גישה/רענון שהונפקו על ידי Google
ניהול היקף הרשאות רחבות הרשאות פרטניות / מצטברות

התמודדות עם ניואנסים בהעברת חשבונות

לפי התיעוד של Fitbit, משתמשים שמעבירים את החשבון שלהם ל-Google בדרך כלל לא מאבדים את החיבורים שלהם לצדדים שלישיים באופן מיידי, אבל שינוי גרסת ה-API הוא דרישה מצד המפתחים.

  • בדיקת תוקף הטוקן: משתמשים ב-backgroundworker כדי לבדוק אם טוקנים של Fitbit נכשלים עם שגיאות מסוג Unauthorized. יכול להיות שהמשתמש העביר את החשבון שלו, אבל האפליקציה שלכם לא עודכנה בהתאם.
  • כשלים שאינם משפיעים על חוויית המשתמש: אם קריאת Fitbit OAuth נכשלת, צריך להפנות את המשתמש לדף מותאם אישית של 'התחברות מחדש ל-Fitbit' שמשתמש ספציפית בתהליך החדש של Google OAuth.

קוד לדוגמה

כדי לעבור מ-Fitbit Web API מדור קודם אל Google Health API, תצטרכו לעבור מספריות OAuth2 כלליות אל Google Auth Library. בהמשך מוצגת הצעה לארכיטקטורה ומימוש של פסאודו-קוד שנכתב ב-JavaScript כדי לטפל במצב הזה של 'ספרייה כפולה'.

1. האפשרות 'החלפת תוכנת ביניים'

מכיוון שאי אפשר להעביר את כל המשתמשים בבת אחת, הבק-אנד צריך לקבוע באיזו ספרייה להשתמש על סמך 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);
  }
}

2. העברת תהליך חוויית המשתמש

כדי למקסם את שיעור השימור, כדאי להשתמש בתבנית הפרעה ושדרוג. כך המשתמש לא נאלץ להתחבר מחדש עד שהוא כבר משתמש באפליקציה.

לוגיקת הפניה לכתובת אחרת

כשמשתמש ב-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 });
});

3. מעברים טכניים חשובים

כשכותבים סקריפטים להעברה של JavaScript, חשוב לזכור את ההבדלים האלה:

תכונה ‫Fitbit Web API (גרסה קודמת) ‫Google Health API (Google-Identity)
Token Endpoint https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
ספריית אימות קוד פתוח רגיל אימות גוגל
היקף פעילות https://www.googleapis.com/auth/googlehealth.activity_and_fitness
מזהה המשתמש מזהה מקודד של Fitbit שמוחזר בתגובה של ‎ /oauth2/token מזהה המשתמש שמוחזר מנקודת הקצה users.getIdentity

4. רשימת משימות בנושא שימור נתונים

  • שמירת נתוני הסשן: אל תנקו את נתוני הסשן הישנים של Fitbit Web API של המשתמש עד שתוודאו ש-access_token של Google Health API אומת ונשמר במסד הנתונים שלכם.
  • ביטול הרשאה אוטומטי: אחרי השלמת ההעברה ל-Google Health API, צריך להשתמש בבקשת POST לנקודת הקצה של ביטול ההרשאה בגרסה הקודמת של Fitbit: https://api.fitbit.com/oauth2/revoke. כך מוודאים שהמשתמש לא יראה הרשאות שניתנות לאפליקציה 'כפולות' בהגדרות Fitbit.
  • טיפול בשגיאות: אם קריאה ל-Fitbit מחזירה 401 Unauthorized, צריך להפנות אוטומטית לזרימת Google OAuth במקום להציג הודעת שגיאה.