ניהול נתונים ב-Google Health API

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

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

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

מחזור החיים של סנכרון רגיל

איור 1: מחזור חיים סטנדרטי של סנכרון ב-Google Health API

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

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

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

כתיבה

1. הכנת נתונים חדשים לכתיבה – העברת נתונים ממכשיר או מאפליקציה חיצוניים ועיצוב נקודות נתונים לייצוגים בפורמט JSON שתואמים לסוגי הנתונים של Google Health API. שימו לב: בשלב הזה, Health API לא תומך במזהים מותאמים אישית שהלקוח מקצה לפעולות כתיבה. אפשר לציין מזהים כאלה ב-POST, אבל המערכת מתעלמת מהם.
2. Upsert records – שליחת נקודות נתונים ל-Google Health API באמצעות נקודות קצה של REST. משתמשים ב-POST כדי ליצור רשומות, וב-PATCH כדי להוסיף ולעדכן רשומות קיימות. המזהים שנדרשים לפעולה PATCH הגיעו מפעולה קודמת POST (השלב הבא במחזור הקודם).
3. עיבוד מזהי משאבים שמוחזרים – כשמשתמשים במזהים שנוצרים בשרת, צריך לחלץ את המשאב name או המזהה שמוחזרים מהשרת ולשמור אותם במאגר הנתונים של המפתחים כדי לאפשר עדכונים (PATCH) או מחיקות (DELETE) בעתיד. מידע נוסף על שני הסוגים זמין במאמר בנושא אסטרטגיות זיהוי.

קריאה

1. קריאת רשומות – שליפת נתונים חדשים ושינויים בנתונים קיימים מ-Google Health API באמצעות נקודות קצה של REST (‫GET עם פרמטרים של שאילתות filter וחלוקה לדפים pageToken, או נקודות קצה של צבירה כמו rollUp ו-dailyRollUp), או קבלת התראות בזמן אמת באמצעות מינויים ל-Webhook ‏ (projects.subscribers). התראה מציינת רק שיש נתונים חדשים, ולא מה הנתונים בפועל.
2. התאמה של מאגר הנתונים של המפתחים – התאמה של הנתונים החדשים והמעודכנים למאגר הנתונים של המפתחים.

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

שיטות זיהוי

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

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

1. מזהים שנוצרו על ידי השרת (אפשרות ברירת המחדל): הלקוח שולח נתונים ללא מזהה, והבק-אנד של Google Health API יוצר ומחזיר מזהה מערכת ייחודי.
2. מזהים מותאמים אישית שהוקצו על ידי הלקוח (לפי AIP-133, עדיין לא נתמך): אפליקציית הלקוח יוצרת מזהה ייחודי (לדוגמה, מזהה UUID או מפתח ראשי של מסד נתונים מקומי) ומספקת אותו בנתיב המשאב בזמן היצירה.

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

תכונה	מזהים שנוצרו על ידי השרת	מזהים מותאמים אישית שהוקצו על ידי הלקוח
יצירת מזהים	השרת יוצר מזהה מערכת אקראי במהלך הביצוע של POST.	הלקוח יוצר מזהה יציב באופן מקומי (UUID v4 / מפתח ראשי פנימי) לפני הכתיבה.
נתיב משאב	‫.../dataPoints/{server_id} (מוחזר בתגובה)	.../dataPoints/{custom_id}
Post-Write Local Step	חובה. צריך לאחסן את הערך המוחזר server_id במסד נתונים מקומי כדי לאפשר עדכונים או מחיקות בעתיד.	ללא. האפליקציה כבר בבעלות המזהה.
טבלת מיפוי מזהים	חובה. הלקוח צריך לשמור על מיפוי דו-כיווני (local_id ↔ server_id).	אין צורך. הלקוח משתמש ישירות במפתח הראשי שלו.
התנהגות של ניסיון חוזר (רשת חלשה)	סיכון לכפילויות. ניסיון חוזר של POST שפג הזמן שלו יוצר רשומה כפולה עם מזהה שרת חדש.	בטוח ואידמפוטנטי. ניסיון חוזר של POST עם אותו custom_id מונע יצירה כפולה (מחזיר 409 ALREADY_EXISTS).
תמיכה בסנכרון אופליין	מוגבלת. צריך להמתין לתגובה מהשרת כדי לקבל מזהי משאבים רשמיים לפני שמתייחסים אליהם.	מלאה. אפשר ליצור ישויות ולשנות אותן במצב אופליין עם מזהים יציבים, ואז לסנכרן אותן בצורה חלקה כשמתחברים מחדש.
מגבלות פורמט	הטיפול מתבצע כולו בשרת.	חייב להיות בהתאם ל-^[a-z0-9-]{4,63}$ (4-63 אותיות קטנות אלפאנומריות ומקפים).
מתי כדאי לבחור	כדאי לבחור מזהים שנוצרו בשרת אם: האפליקציה שלך היא רק לכתיבה או רק להוספה (למשל, שליחת טלמטריה או ספירת צעדים שלא מתעדכנים או נמחקים בהמשך). האפליקציה לא מתחזקת מסד נתונים מקומי קבוע של נקודות נתונים פרטניות. אתם מעדיפים פתרון פשוט בלי לנהל אילוצים של אימות מחרוזות (כמו 4-63 תווים).	מומלץ לבחור מזהים מותאמים אישית אם: אתם מפעילים אפליקציית סנכרון דו-כיוונית שקוראת, כותבת ומעדכנת רשומות בריאותיות במכשירים שונים. באפליקציה יש מסד נתונים מקומי (כמו Room או SQLite) שבו מאוחסנים רשומות עם מפתחות ראשיים מקומיים. המשתמשים שלכם מתעדים נתונים במצב אופליין או בחיבורים ניידים לסירוגין, שבהם נדרים ניסיונות חוזרים בטוחים. אתם רוצים לבטל את טבלאות מיפוי הזהויות בין מסד הנתונים של העורף האחורי לבין ה-API.

מחזור החיים של סינכרון לקריאה בלבד

איור 2: מחזור החיים של סנכרון לקריאה בלבד ב-Google Health API

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

אותן משימות שמוסברות בקטע קריאה רלוונטיות גם כאן.

איור 2 מציג את מחזור החיים של קריאה בלבד.