הגדרת 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.

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

כברירת מחדל, לקוחות 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.

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

כדי לשמור על גישה לטווח ארוך לממשקי ה-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 ימים.

הגנה על כל החשבונות (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 זמין במאמר הגנה על חשבונות משתמשים באמצעות הגנה על כל החשבונות.