הגדרת Google Cloud ו-OAuth

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

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

יצירת פרויקט ולקוח OAuth

כדי להפעיל את Google Health API ולקבל מזהה לקוח ב-OAuth 2.0, לוחצים על הלחצן הפעלת ה-API וקבלת מזהה לקוח ב-OAuth 2.0:

  1. אם יש לכם פרויקט קיים ב-Google Cloud שבו אתם רוצים להשתמש ב-Google Health API, ודאו שאתם מחוברים קודם לחשבון האדמין של הפרויקט הזה. אחר כך בוחרים את הפרויקט הקיים מתוך רשימת הפרויקטים הזמינים אחרי שלוחצים על הלחצן. אם לא, צריך ליצור פרויקט חדש.
  2. כשמופיעה השאלה 'מאיפה מתקשרים?', בוחרים באפשרות Web Server.
  3. מזינים את הערך https://www.google.com בשדה Authorized redirect URIs. כדי לקבל קוד הרשאה באמצעות OAuth 2.0, צריך להזין כתובת URI להפניה אוטומטית.
  4. אחרי שמסיימים את ההגדרה, מעתיקים את הערכים של מזהה הלקוח וסוד הלקוח של OAuth 2.0 ומורידים את קובץ ה-JSON של פרטי הכניסה למחשב המקומי.
הפעלת ה-API וקבלת מזהה לקוח ב-OAuth 2.0

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

  1. מפעילים את Google Health API בדף API Enablement.
  2. מקבלים מזהה לקוח ב-OAuth 2.0 בדף פרטי כניסה.

למידע נוסף על הגדרת OAuth 2.0 באמצעות מסוף Google, אפשר לעיין במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

שימוש בפרויקטים נפרדים לסביבת Staging ולסביבת ייצור

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

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

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

הוספת משתמשי בדיקה

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

מעדכנים את רשימת משתמשי הבדיקה בדף קהל:

  1. בדף הזה, הערך של 'סטטוס הפרסום' צריך להיות בדיקה, והערך של 'סוג המשתמש' צריך להיות חיצוני.
  2. בקטע 'משתמשי בדיקה', לוחצים על + הוספת משתמשים. מזינים את כתובת האימייל של משתמשי הבדיקה שצריכה להיות להם אפשרות להעניק לאפליקציה הרשאה לגשת לנתוני בריאות וכושר שלהם.
  3. לוחצים על שמירה.

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

הוספת היקפי הרשאות

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

  1. בדף הזה, לוחצים על הוספה או הסרה של היקפי הרשאה.
  2. בעמודה API, מחפשים את Google Health API. בוחרים את היקפי ההרשאות שנדרשים לאפליקציה.
  3. אחרי שבוחרים את כל ההיקפים שצריך, לוחצים על עדכון כדי לחזור לדף 'גישה לנתונים'.
  4. לוחצים על שמירה.

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

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

עדכון היקפי ההרשאות

כדי לבקש מהמשתמש להעניק הרשאה מחדש לאפליקציה, צריך להגדיר את פרמטר ההנחיה consent בבקשת האימות. אם prompt=consent נכלל, מסך ההסכמה מוצג בכל פעם שהאפליקציה מבקשת הרשאה להיקפי גישה, גם אם כל ההיקפים הוענקו בעבר לפרויקט Google APIs.

כדי להוסיף או לשנות היקפי הרשאה באמצעות הפרמטר prompt=consent, פועלים לפי השלבים הבאים:

  1. מזהים את הרשימה המלאה של ההיקפים שהאפליקציה צריכה. צריך לכלול את ההיקפים הקיימים ואת ההיקפים החדשים שרוצים להוסיף.

  2. משנים את פרמטר ההיקף בכתובת ה-URL של ההרשאה כך שיכלול את הרשימה המעודכנת של ערכי ההיקף, מופרדים ברווחים.

  3. מוסיפים את prompt=consent לפרמטרים של URI האימות. הפעולה הזו מאלצת את שרת ההרשאות לבקש מהמשתמש הסכמה לפני שהוא מחזיר מידע ללקוח.

    בדוגמה הבאה מוצגת בקשת GET של HTTPS לנקודת הקצה של הרשאת OAuth 2.0 של Google, שבה מבוקשים כמה היקפי הרשאות עם prompt=consent שנוסף בסוף:

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

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

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

ספריות לקוח OAuth2

רשימת ספריות הלקוח הזמינות של OAuth2 שמשמשות לשילוב עם מסגרות פופולריות זמינה במאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

כשמטמיעים את Google OAuth באפליקציות לנייד או למחשב, צריך תמיד להשתמש בדפדפני מערכת (כמו כרטיסיות מותאמות אישית ב-Chrome ב-Android או ASWebAuthenticationSession ב-iOS) ואסור להשתמש ב-WebViews מוטמעים, שחוסמים מפתחות גישה ומשבשים את תהליכי העבודה של Google OAuth. כדאי לעיין בשיטות המומלצות לכניסה באמצעות חשבון Google לקבלת הנחיות.

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

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

  1. מורידים ופותחים את אפליקציית Google Health לנייד מחנות Google Play או מ-App Store של אפל.
  2. מקישים על כניסה באמצעות Google ובוחרים את חשבון Google שרוצים לקשר לאפליקציה.
  3. פועלים לפי ההנחיות באפליקציה כדי ליצור פרופיל חדש ב-Google Health, או פועלים לפי השלבים להעברת חשבון Fitbit כדי להעביר חשבון Fitbit קיים לחשבון Google.

אחרי שמחליפים את קוד ההרשאה באסימוני OAuth, קוראים לנקודת הקצה users.getIdentity ‏ (GET https://health.googleapis.com/v4/users/me/identity) כדי לוודא שחשבון Google של המשתמש מקושר ל-Google Health לפני שמסמנים את החשבון כמקושר באפליקציה. לפרטים על טיפול בחשבונות לא מקושרים (400 ACCOUNT_NOT_LINKED), אפשר לעיין במאמר טיפול בחשבונות Google לא מקושרים.

אסימוני רענון

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

כדי להחליף טוקן רענון בטוקן גישה, שולחים קריאת HTTPS POST לנקודת הקצה של טוקן Google OAuth 2.0. בקטע הקוד הבא מוצגות דוגמה לבקשה ולתגובה:

בקשה

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

תשובה

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

מתי צריך לרענן טוקן

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

לא מומלץ לרענן אסימונים בקבוצות מהסיבות הבאות:

  • רענון באצווה מונע התאמה של עדכוני אסימונים עם דפוסי סנכרון של משתמשים פעילים. אפשר להשתמש בקריאה Get Devices כדי לראות את זמן הסנכרון האחרון של משתמש, אבל זה דורש היקף OAuth נוסף שהמשתמשים לא מחויבים לאשר.
  • עיבוד באצווה מעדכן אסימונים שלא צריך לרענן, וכך נוצר עומס עיבוד מיותר במערכות שלכם ובשרתים של Google.
  • אם מתרחשת בעיה ברשת או הפסקת פעולה של השרת במהלך רענון של קבוצת אסימונים, כל האסימונים של המשתמשים שמושפעים מכך מושפעים בבת אחת. רענון של טוקנים בנפרד במהלך ההתקדמות הטבעית של סנכרון המשתמשים מבודד את ההשפעה של כשלים זמניים למשתמש יחיד.
  • קשה יותר לאבחן בעיות בעבודות אצווה. בקשות באצווה מתרחשות בתדירות נמוכה יותר ומייצרות הרבה רשומות ביומן בבת אחת, ולכן קשה יותר לאתר את תחילת האירוע.
  • עלייה חדה במספר הבקשות לטוקנים במהלך הפעלות של אצווה מגדילה את הסיכוי להגיע למגבלות הקצב או לחוות שגיאות אימות לסירוגין.

התנהגות של טוקנים במהלך בדיקה

חשוב להבין איך טוקנים לרענון מתנהגים בהתאם לסטטוס הפרסום של הפרויקט שלכם ב-Google Cloud:

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

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

יצירת נתונים לדוגמה

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

  • עונדים מכשיר מעקב: עונדים מכשיר מעקב של Fitbit,‏ Pixel Watch או שעון חכם אחר שתואם לאפליקציית Google Health, ומסתובבים כדי ליצור נתונים של צעדים, קצב לב ואימונים.
  • הפעלת מעקב בנייד: מפעילים את MobileTrack באפליקציית Google Health ומסתובבים עם המכשיר הנייד.
  • רישום נתונים באופן ידני: אפשר להזין באופן ידני מדדים בריאותיים (כמו שינה, משקל, צריכת מים או צריכת מזון) דרך אפליקציית Google Health.
  • כתיבת נתונים באמצעות ה-API: שולחים בקשות כתיבה (כמו POST או PATCH) ישירות לנקודות הקצה של ה-API בארכיטקטורת REST כדי לאכלס נתונים באופן פרוגרמטי. מידע נוסף על יצירה ועדכון של נקודות נתונים זמין במאמרי העזרה בנושא REST.

הגנה על כל החשבונות (RISC API)

אם רוצים לקבל הודעות על שינויים בטוקנים של אירועים או בקישור לחשבון, כמו חשבונות מנותקים או טוקנים שבוטלו, כדי לנקות טוקנים מאוחסנים ולעדכן את סטטוס החיבור בממשק המשתמש, צריך להפעיל את התכונה Risk and Incident Sharing and Coordination (שיתוף ותיאום של סיכונים ותקריות, RISC). הפעלת RISC API היא אופציונלית.

כדי להפעיל את RISC API בפרויקט שלכם ב-Google Cloud:

  1. פותחים את הדף RISC API במסוף Google Cloud. מוודאים שהפרויקט שבו אתם משתמשים ב-Google Health API נבחר.
  2. קוראים את התנאים של RISC ומוודאים שמבינים את הדרישות.
  3. אם אתם מסכימים לתנאים, לוחצים על הפעלה.

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

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