סוגי נתונים ב-Google Health API

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

חשוב: הפורמט של מזהי סוגי הנתונים שונה כשסוג הנתונים כולל יותר ממילה אחת. בנקודת קצה, שם סוג הנתונים צריך להיות בפורמט kebab-case, כמו body-fat. לעומת זאת, בפרמטר של מסנן, שם סוג הנתונים צריך להיות בפורמט snake case, למשל body_fat.

טבלה: סוגי נתונים של Google Health API

סוג הנתונים   dataType הפרמטר   filter	סוג הרשומה	פעולות זמינות	היקף	תמיכה ב-Webhook	תמיכה בערכים אפסיים אמיתיים
האנרגיה הפעילה שנשרפה   active-energy-burned   active_energy_burned	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Active Minutes   active-minutes   active_minutes	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
דקות טווח פעילות   active-zone-minutes   active_zone_minutes	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
רמת הפעילות   activity-level   activity_level	מרווח	רשימה, התאמה	.activity_and_fitness.readonly .activity_and_fitness.writeonly
גובה   altitude   altitude	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
סוכר בדם   blood-glucose   blood_glucose	דוגמה	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Body Fat   body-fat   body_fat	דוגמה	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
קלוריות שנשרפו בטווח הדופק   calories-in-heart-rate-zone   calories_in_heart_rate_zone	מרווח	סיכום, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Core Body Temperature   core-body-temperature   core_body_temperature	דוגמה	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Heart Rate Variability   daily-heart-rate-variability   daily_heart_rate_variability	יומי	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Heart Rate Zones   daily-heart-rate-zones   daily_heart_rate_zones	יומי	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
רמת החמצן בדם מדי יום   daily-oxygen-saturation   daily_oxygen_saturation	יומי	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Respiratory Rate   daily-respiratory-rate   daily_respiratory_rate	יומי	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Resting Heart Rate   daily-resting-heart-rate   daily_resting_heart_rate	יומי	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily Sleep Temperature Derivations   daily-sleep-temperature-derivations   daily_sleep_temperature_derivations	יומי	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Daily VO2 Max   daily-vo2-max   daily_vo2_max	יומי	רשימה, התאמה	.activity_and_fitness.readonly .activity_and_fitness.writeonly
מרחק   distance   distance	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Electrocardiogram (ECG)   electrocardiogram   electrocardiogram	סשן	list	.ecg.readonly
תרגיל   exercise   exercise	סשן	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly
קומות   floors   floors	מרווח	התאמה, איחוד לתצוגה אחת, סיכום יומי	.activity_and_fitness.readonly .activity_and_fitness.writeonly
אוכל   food   food	אוכל	list, get	.nutrition.readonly .nutrition.writeonly
יחידת מידה של מזון   food-measurement-unit   food_measurement_unit	אוכל	list, get	.nutrition.readonly .nutrition.writeonly
דופק   heart-rate   heart_rate	דוגמה	list, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Heart Rate Variability   heart-rate-variability   heart_rate_variability	דוגמה	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
גובה   height   height	דוגמה	list, get, reconcile, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
יומן מאזן נוזלים   hydration-log   hydration_log	סשן	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
התראה על הפרעת קצב (IRN)   irregular-rhythm-notification   irregular_rhythm_notification	סשן	list	.irn.readonly
Menstrual Period   menstrual-period   menstrual_period	מרווח	create, update, batchDelete	.reproductive_health.writeonly
מצבי רוח   moods   moods	דוגמה	create, update, batchDelete	.mindfulness.writeonly
יומן תזונה   nutrition-log   nutrition_log	דוגמה	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
בדיקת ביוץ   ovulation-test   ovulation_test	דוגמה	create, update, batchDelete	.reproductive_health.writeonly
ריווי חמצן בדם   oxygen-saturation   oxygen_saturation	דוגמה	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
סיכום קצב הנשימה בשינה   respiratory-rate-sleep-summary   respiratory_rate_sleep_summary	דוגמה	רשימה, התאמה	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Run VO2 Max   run-vo2-max   run_vo2_max	דוגמה	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
תקופה של חוסר פעילות   sedentary-period   sedentary_period	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
שינה   sleep   sleep	סשן	list, get, reconcile, create, update, batchDelete	.sleep.readonly .sleep.writeonly
שלבים   steps   steps	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
נתונים של אורך הבריכה   swim-lengths-data   swim_lengths_data	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
תסמינים   symptoms   symptoms	דוגמה	create, update, batchDelete	.logged_symptoms.writeonly
Time in Heart Rate Zone   time-in-heart-rate-zone   time_in_heart_rate_zone	מרווח	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
סה"כ קלוריות   total-calories   total_calories	מרווח	סיכום, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
VO2 Max   vo2-max   vo2_max	דוגמה	רשימה, התאמה	.activity_and_fitness.readonly .activity_and_fitness.writeonly
משקל   weight   weight	דוגמה	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly

מגבלות על שאילתות

כשמבצעים שאילתות על נקודות נתונים, סיכומי נתונים או סיכומי נתונים יומיים מה-API, חשוב לזכור את המגבלות הבאות:

• דרישות סינון: חלק מסוגי הנתונים הנגזרים לקריאה בלבד, כמו total-calories, דורשים מסנן שמציין את שעת ההתחלה של המרווח (באמצעות זמן פיזי או זמן אזרחי).
• מגבלות על טווח השאילתות: טווח השאילתות המקסימלי עבור calories-in-heart-rate-zone, heart-rate, active-minutes ו- total-calories הוא 14 ימים. טווח השאילתות המקסימלי לכל סוגי הנתונים האחרים הוא 90 יום.

זמינות הנתונים

העדכונים של נתוני המשתמש זמינים רק אחרי שהמשתמש מסנכרן את מנהל מעקב אחר פעילות שלו או מזין נתונים חדשים באופן ידני באפליקציה לנייד של Fitbit או באפליקציית אינטרנט. מכשיר Fitbit ואפליקציית Fitbit לנייד יכולים להסתנכרן אוטומטית כל 15 דקות כשאפליקציית Fitbit פתוחה במכשיר הנייד ושני המכשירים מחוברים באופן פעיל לנתונים ונמצאים בטווח ה-Bluetooth. אם המשתמש עוקב אחרי הפעילות באמצעות MobileTrack, הנתונים מסתנכרנים כל שעה כל עוד האפליקציה פתוחה.

שליחת שאילתות לגבי נתונים היסטוריים

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

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

• כל נקודת קצה מחזירה גודל דף מקסימלי של 10,000 נקודות נתונים לכל דף.
• טווח התאריכים של השאילתה מוגבל ל-14 עד 90 ימים לכל בקשה.

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

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

סנכרון נתונים בשלבים (טעינה חמה לעומת הפעלה מההתחלה)

• טעינה ראשונית של נתונים 'פעילים': במהלך רצף הטעינה העיקרי, המערכת מאחזרת ומציגה רק את הנתונים מ-7 עד 14 הימים האחרונים. כך המשתמשים יכולים לראות את הנתונים באופן מיידי בלי לחכות לשאילתות ארוכות.
• טעינה "קרה" ברקע: אחזור של נתונים היסטוריים ישנים יותר מועבר לתור אסינכרוני בעדיפות נמוכה יותר או לתהליך ברקע אחרי שהממשק הראשי מעובד.

חלוקה של שאילתות לחלקים לפי זמן

• אל תבקשו טווחי זמן של כמה שנים או כמה חודשים בקריאה ל-API אחת. כדאי לפצל שאילתות היסטוריות גדולות למרווחי זמן קטנים יותר ורציפים (לדוגמה, שבוע אחד לכל בקשה).
• כדי לכבד את מגבלות הריצה המקבילה ולשמור על אינדיקטורים יציבים של התקדמות ממשק המשתמש, כדאי להריץ את שאילתות המשנה האלה באצווה או ברצף.

שימוש בסיכומי נתונים מצטברים שהוגדרו מראש

ארגון מחדש של לוחות הבקרה של הסקירה הכללית ושל תרשימי המגמות כך שישתמשו בנקודות קצה של סיכום שעברו צבירה מראש (כמו DailyRollUpDataPoints). כך יצטמצם באופן משמעותי העומס על המחשוב בשרת העורפי וזמן העברת הנתונים ללקוח.

טיפול בשגיאות בצורה גמישה (ניסיונות חוזרים חכמים)

• צריך להטמיע טיפול קפדני בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כשנתקלים במגבלות קצב (429 Too Many Requests) ובפסק זמן של שער השרת (504 Gateway Timeout). אסור לנסות לשלוח שוב מטען ייעודי גדול שנכשל באופן מיידי. ניסיונות חוזרים מיידיים מגבירים את העומס על השרתים ומחמירים את הירידה בביצועי המערכת.
• אם חלף הזמן הקצוב לתפוגה של שאילתה שוב ושוב, המערכת תעבור אוטומטית לחלון זמן קטן יותר (לדוגמה, תקטין נתח של שבוע ל-3 ימים).

אזהרה: אי-ציות להנחיות האלה עלול לגרום להתנהגות לא צפויה ולשגיאות.

גישה של צד שלישי

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

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

סטנדרטים של מרחק

מרחקי פעילות גופנית, כמו elevationGainMillimeters, נמדדים במילימטרים כיחידת המידה הסטנדרטית מהסיבות הבאות:

1. שמירה על דיוק הנתונים: הסיבה הכי חשובה לשימוש במילימטרים היא לוודא שלא נאבד דיוק בנתונים שאנחנו קוראים ומספקים. שימוש ביחידה מדויקת כמו מילימטרים מאפשר לנו להציג מדידות ברמת דיוק גבוהה.
2. תקינה: מילימטרים הם יחידת המידה הסטנדרטית שנקבעה בשירותים שלנו. העקביות הזו עוזרת להבטיח חוויה אחידה למפתחים שמשתמשים בחלקים שונים של ה-API.
3. תמיכה רחבה במערכות מדידה: שימוש ביחידת בסיס כמו מילימטרים מאפשר למפתחים להמיר בקלות לכל יחידה אחרת, בלי קשר למערכת המדידה שבה הם משתמשים (מטרית, אימפריאלית או אחרת).

משך יום משתנה

ב-Health API, הטיפול בזמן מתבצע לפי הזמן של המשתמש כדי להתחשב באורכי ימים משתנים שנגרמים בגלל שעון קיץ או נסיעות. כל נקודת נתונים מאוחסנת עם חותמת זמן פיזית ב-UTC ועם ההפרש מ-UTC שהיה פעיל בזמן האירוע. כך המערכת יכולה:

• מיפוי האירוע לנקודת זמן פיזית מדויקת.
• השעה תתוקן בהתאם להקשר המקומי של המשתמש לצורך צבירה.

שעון קיץ

כששעון הקיץ מסתיים, יש "חזרה לאחור" שגורמת לכך שהיום האזרחי נמשך 25 שעות, ונתוני הסיכום של התאריך הזה יכללו נתונים של 25 שעות. הזזת השעון קדימה גורמת ליום אזרחי של 23 שעות, שבו השעה מוחזרת לשעון רגיל.

נסיעות

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

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