מינויים ל-webhook

בקרוב יהיה אפשר לרכוש מינויים.

‫Google Health API מאפשר לאפליקציה שלכם לקבל התראות בזמן אמת כשנתוני הבריאות של המשתמש משתנים. במקום לבצע בדיקות חוזרות כדי לראות אם יש שינויים, השרת שלכם מקבל בקשת HTTPS POST ‏ (webhook) ברגע שהנתונים זמינים ב-Google Health API.

סוגי נתונים נתמכים

יש תמיכה בהתראות של Webhook לסוגי הנתונים הבאים:

• שלבים
• גובה
• מרחק
• קומות
• משקל
• שינה

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

• פעילות, שכוללת את סוגי הנתונים הבאים: צעדים, גובה, מרחק וקומות:
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• מדדי בריאות, שכוללים את סוג הנתונים של המשקל:
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
• שינה, שכולל את סוג הנתונים של השינה:
  • https://www.googleapis.com/auth/googlehealth.sleep
  • https://www.googleapis.com/auth/googlehealth.sleep.readonly

ניהול המנויים

כדי לקבל התראות, צריך לרשום מנוי שמייצג את נקודת הקצה של ההתראות באפליקציה. אפשר לנהל אפליקציות רשומות באמצעות ה-API בארכיטקטורת REST שזמין בכתובת projects.subscribers.

נקודת הקצה של המנויים חייבת להשתמש ב-HTTPS ‏ (TLSv1.2 ומעלה) ולהיות נגישה לכולם. במהלך יצירה ועדכונים של מנויים, Google Health API מבצע אתגר אימות כדי לוודא שאתם הבעלים של ה-URI של נקודת הקצה. אם האימות נכשל, פעולות היצירה והעדכון של המינויים נכשלות עם FailedPreconditionException.

יצירת מנוי

כדי לרשום מנוי חדש לפרויקט, משתמשים בנקודת הקצה create. תצטרכו לספק:

• ‫endpointUri: כתובת היעד של התראות ה-webhook.
• ‫subscriberConfigs: סוגי הנתונים שרוצים לקבל עליהם התראות, ומדיניות המינוי לכל אחד מהם.
• ‫endpointAuthorization: מנגנון ההרשאה של נקודת הקצה. הוא צריך לכלול authorization_token שאתם מספקים. הערך של authorization_token נשלח בכותרת Authorization עם כל הודעת התראה. אפשר להשתמש בטוקן הזה כדי לוודא שהבקשות הנכנסות מגיעות מ-Google Health API. לדוגמה, אפשר להגדיר את authorization_token ל-Bearer R4nd0m5tr1ng123 לאימות Bearer, או ל-Basic dXNlcjpwYXNzd29yZA== לאימות בסיסי.
• ‫subscriberId: מזהה ייחודי שאתם מספקים למנוי. המזהה הזה צריך לכלול בין 4 ל-36 תווים, ולהתאים לביטוי הרגולרי ([a-z]([a-z0-9-]{2,34}[a-z0-9])).

ב-subscriberConfigs צריך להגדיר את subscriptionCreatePolicy לכל סוג נתונים. מגדירים את הערך ל-AUTOMATIC כדי להשתמש במינויים אוטומטיים, או ל-MANUAL אם אתם מתכוונים לנהל את מינויי המשתמשים בעצמכם. לפרטים נוספים על כל אפשרות, אפשר לעיין במאמרים בנושא מינויים אוטומטיים ומינויים ידניים.

בקשה

POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
  "endpointUri": "https://myapp.com/webhooks/health",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorization_token": "Bearer example-secret-token"
  }
}

תשובה

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

הצגת רשימת המנויים

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

בקשה

GET https://health.googleapis.com/v4/projects/project-id/subscribers

תשובה

{
  "subscribers": [
    {
      "name": "projects/project-id/subscribers/subscriber-id",
      "endpointUri": "https://myapp.com/webhooks/health",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

עדכון מנוי

משתמשים בנקודת הקצה patch כדי לעדכן מנוי בפרויקט. אלה השדות שאפשר לעדכן: endpointUri, subscriberConfigs ו-endpointAuthorization.

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

אם מעדכנים את endpointUri או את endpointAuthorization, מתבצעת בדיקה של נקודת קצה (endpoint). פרטים נוספים מופיעים במאמר בנושא בדיקה של נקודת קצה (endpoint).

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

בקשה

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

תשובה

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/new-webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

בדיקה של נקודת קצה (endpoint)

כדי להבטיח את האבטחה והמהימנות של מסירת ההתראות, Google Health API מבצע תהליך אימות דו-שלבי מחייב בכל פעם שיוצרים מנוי או מעדכנים את הגדרת נקודת הקצה שלו (endpointUri או endpointAuthorization). התהליך הזה מתבצע באופן סינכרוני במהלך קריאה ל-API. השירות שולח שתי בקשות POST אוטומטיות למזהה ה-URI של נקודת הקצה, באמצעות User-Agent‏ Google-Health-API-Webhooks-Verifier, עם גוף JSON‏ {"type": "verification"}.

• העברת נתונים מאומתת: הבקשה הראשונה נשלחת עם הכותרת Authorization שהגדרתם. השרת צריך להגיב עם סטטוס 200 OK או 201 Created.
• אתגר לא מורשה: הבקשה השנייה נשלחת ללא פרטי כניסה. השרת צריך להגיב עם סטטוס 401 Unauthorized או 403 Forbidden.

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

רוטציית מפתחות

אם אתם צריכים לסובב מפתחות עבור endpointAuthorization, אתם יכולים לפעול לפי השלבים הבאים:

1. מגדירים את נקודת הקצה כך שתקבל גם ערכים ישנים וגם ערכים חדשים של endpointAuthorization המאפיין.
2. מעדכנים את הגדרות המנוי עם הערך החדש endpointAuthorization באמצעות בקשת patch עם ?updateMask=endpointAuthorization.
3. מגדירים את נקודת הקצה כך שתקבל רק ערך חדש של endpointAuthorization אחרי שמוודאים ששלב 2 בוצע בהצלחה.

מחיקת מנוי

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

בקשה

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

תשובה

אם המחיקה בוצעה בהצלחה, מוחזר גוף תגובה ריק עם סטטוס HTTP ‏ `200 OK`.

{}

מינויים של משתמשים

‫Google Health API עוזר לכם לנהל את מינויי המשתמשים ביעילות, וכך מצמצם את הצורך ברישום ידני במהלך צירוף משתמשים.

מינויים אוטומטיים

מומלץ להשתמש במינויים אוטומטיים. כדי להפעיל את התכונה הזו, צריך להגדיר את subscriptionCreatePolicy לערך AUTOMATIC ב-subscriberConfigs עבור סוגי הנתונים הספציפיים. הנתונים שאתם מציינים במדיניות dataTypes הם אותם סוגי נתונים ש-Google Health API שולח לגביהם התראות, בתנאי שגם ניתנה הסכמה מהמשתמש לסוגי הנתונים האלה.AUTOMATIC

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

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

מינויים ידניים

אם אתם מעדיפים לנהל את המינויים של כל משתמש באופן ידני, צריך להגדיר את subscriptionCreatePolicy לערך MANUAL ב-subscriberConfigs. במדיניות הזו, מינויים של משתמשים לא נוצרים באופן אוטומטי. הפונקציונליות הזו תשמש בעתיד כשממשקי API לניהול מינויים ידניים יהיו זמינים. עד שממשקי ה-API האלה יהיו זמינים, מומלץ להשתמש במינויים.AUTOMATIC

התראות

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

פורמט ההתראות

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

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-0B01:29:00Z",
          "endTime": "2026-03-08T01:34:00Z"
        },
        "civilDateTimeInterval": {
          "startDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 29
            }
          },
          "endDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 34
            }
          }
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-03-07T17:29:00",
          "endTime": "2026-03-07T17:34:00"
        }
      }
    ]
  }
}

השדה operation מציין את סוג השינוי שהפעיל את ההתראה:

• ‫UPSERT: נשלח כשמוסיפים נתונים או משנים אותם.
• ‫DELETE: נשלח כשמשתמש מוחק נתונים, או כשנתונים מוסרים בגלל אירוע במערכת, כמו ביטול הרשאה של משתמש או מחיקת החשבון שלו.

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

השדה clientProvidedSubscriptionName הוא מזהה ייחודי. למינויים עם מדיניות MANUAL, השדה הזה מכיל את שם המינוי הקבוע שסופק על ידי המפתח והוגדר כשנוצר המינוי. כך אפשר לקבל מזהה יציב לניהול מינויים ידניים. למינויים שנוצרו עם מדיניות AUTOMATIC, Google Health API יוצר ומקצה באופן אוטומטי מזהה ייחודי (UUID אקראי) לשדה הזה לכל התראה. הכללת clientProvidedSubscriptionName במדיניות ידנית ובמדיניות אוטומטית מבטיחה פורמט עקבי של מטען ייעודי (Payload) של התראות בכל סוגי המינויים.

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

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

איך משיבים להודעות

השרת שלכם צריך להגיב להתראות באופן מיידי עם קוד סטטוס 204 No Content של HTTP. כדי למנוע מצבים של זמן קצוב לתפוגה, צריך לעבד את מטען ייעודי (payload) של ההתראה באופן אסינכרוני אחרי שליחת התשובה. אם Google Health API מקבל קוד סטטוס אחר או שהבקשה נכשלת בגלל פסק זמן, המערכת מנסה לשלוח את ההתראה שוב מאוחר יותר.

דוגמה ל-Node.js ‏ (Express):

app.post('/webhook-receiver', (req, res) => {
    // 1. Immediately acknowledge the notification
    res.status(204).send();

    // 2. Process the data asynchronously in the background
    const notification = req.body;
    setImmediate(() => {
        console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
        // Trigger your data retrieval logic here
    });
});

סטטוס המנוי ושחזור

אם נקודת הקצה של המנוי לא זמינה או מחזירה קוד סטטוס של שגיאה (כל קוד אחר מלבד 204), Google Health API מאחסן התראות בהמתנה למשך עד 7 ימים ומנסה שוב לשלוח אותן עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

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