נקודות קצה

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

מוסכמות של API בארכיטקטורת REST

‫Google Health API פועל לפי התקנים של Google API Improvement Proposals (AIP), ובמיוחד AIP-127 (המרת קידוד של HTTP ו-gRPC) ו-AIP-131 עד AIP-135 (שיטות סטנדרטיות). התקנים האלה מגדירים איך הנתונים ממופים מהודעת proto לבקשת HTTP.

פרמטרים של שאילתה

פרמטרים של שאילתה משמשים כשהנתונים הם חלק מכתובת ה-URL. הוא מיועד בעיקר לבקשות GET (אחזור משאב) או לבקשות LIST (סינון/עימוד), אבל משמש גם לפעולות DELETE.

  • מיקום: נוסף לכתובת ה-URL אחרי ?.
  • תחביר: צמדי מפתח/ערך שמופרדים באמצעות &.
  • מיפוי: כל שדה בהודעת הבקשה שלא נכלל בתבנית של נתיב כתובת ה-URL ממופה לפרמטר של שאילתה.
  • הכי מתאים ל: סוגים פשוטים (מחרוזות, מספרים שלמים, טיפוסי enum) ושדות חוזרים.

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

תחביר לדוגמה:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

גוף הבקשה

גוף הבקשה משמש כשהנתונים משנים את המצב של המשאב או כשהם גדולים מדי בשביל כתובת URL. גוף הבקשה הוא בדרך כלל ייצוג ב-JSON של המשאב עצמו. בדרך כלל משתמשים בהן לפעולות POST, PATCH ו-PUT.

  • מיקום: בתוך המטען הייעודי (payload) של HTTP (לא גלוי בכתובת ה-URL).
  • תחביר: בפורמט של אובייקט JSON.
  • מיפוי: מוגדר בהערה google.api.http.
    • body: "*" פירושו שכל ההודעה היא הגוף.
    • body: "resource_name" פירושו שרק שדה ספציפי ב-proto הוא גוף הבקשה.
  • הכי מתאים ל: אובייקטים מורכבים, הודעות בתצוגת עץ ומידע אישי רגיש.

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

תחביר לדוגמה:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

המקרה המשולב

ב-method‏ Update או בפעולה PATCH שתואמים ל-AIP-134, משתמשים בשניהם. כתובת ה-URL מכילה את שם המשאב, גוף הבקשה מכיל את נתוני המשאב המעודכנים, ופרמטר של שאילתה (בדרך כלל update_mask) מציין אילו שדות לשנות.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

ההבדלים העיקריים בקצרה

תכונה פרמטרי שאילתה גוף הבקשה
הנחיות בנושא AIP משמש לפעולות חיפוש, סינון וקריאה. משמש לפעולות כתיבה.
חשיפה גלויים בהיסטוריית הגלישה וביומני השרת. מוסתר מכתובת ה-URL.
מורכבות מוגבל למבנים שטוחים או חוזרים. תומך באובייקטים של JSON עם רמות רבות של הטמעה.
קידוד הערך צריך להיות מקודד בקידוד URL (לדוגמה, רווחים הופכים ל-%20). קידוד JSON רגיל.

תאריכים

כל התאריכים ב-Google Health API מוצגים בפורמט YYYY-MM-DD. ‫Nutrition API תומך בתקן ISO-8601 לערכי תאריכים בתנאים הבאים:

  • שנה בפורמט 4 ספרות YYYY
  • ערכי שנה בטווח 0000-9999
  • אין אכיפה של הגבלות על תאריך ההתחלה שמשתמעות מתקן ISO-8601 או מתקופה אחרת

כותרות

כדי להריץ את נקודות הקצה ל-API של Google Health, צריך להשתמש בכותרות ובטוקן הגישה המתאימים. מומלץ להשתמש בכותרת הבאה גם בבקשות GET וגם בבקשות POST:

Authorization: Bearer access-token
Accept: application/json

אינדקס המשימות של ה-API

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

איך מקבלים את מזהה המשתמש ב-Fitbit או ב-Google

אחרי שהמשתמש נותן הסכמה דרך Google OAuth 2.0, התגובה של האסימון לא מכילה את מזהה המשתמש ב-Fitbit או ב-Google. אחרי שמעניקים לפחות היקף הרשאות אחד של Google Health, צריך להפעיל את נקודת הקצה (endpoint) של getIdentity מיד אחרי החלפת קוד ההרשאה כדי לאחזר את legacyUserId וגם את healthUserId, ולוודא שחשבון Google של המשתמש מקושר ל-Google Health. צריך להשאיר את הטוקנים הקודמים של Fitbit פעילים עד ש-legacyUserId יאומת. אם החשבון עדיין לא מקושר, getIdentity מחזיר את קוד ה-HTTP‏ 400 Bad Request (status: "FAILED_PRECONDITION", ErrorInfo.reason: "ACCOUNT_NOT_LINKED", ראו טיפול בחשבונות Google לא מקושרים).

לדוגמה:

בקשה

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

תגובה (200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

תגובה (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

קבלת נתונים מפורטים שנאספו במהלך היום או נתונים תוך-יומיים

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

לדוגמה:

בקשה

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

תשובה

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

תצוגה מותאמת של נתוני המרווחים

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

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

בדוגמה הבאה מוצגת השוואה בין התגובה של list (שמחזירה את שתי הרשומות החופפות) לבין התגובה של reconcile (שפותרת את ההתנגשות על ידי החזרת הרשומה המוסמכת) למשתמש עם שני אימונים חופפים:

רשימה גולמית

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

ההזמנה הוסדרה

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

ההתאמה פותרת סשנים סותרים על ידי ביטול כפילויות ובחירת הרשומה המוסמכת, במקום ליצור איחוד זמן מלאכותי (כמו 11:00:00Z עד 11:50:00Z). התגובה המותאמת מחזירה את נקודה על הגרף המנצחת (7797422996486764704) עם המרווח המקורי שתועד (11:20:00Z עד 11:50:00Z), תוך שמירה על תקינות הטלמטריה והמדדים שנמדדו בסשן הזה.

סנן נתונים

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

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

סינון לפי משפחת מקורות נתונים

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

במדריך בנושא סינון נתונים, בקטע סינון לפי משפחה של מקור נתונים, מפורטות הנחיות מפורטות, משפחות נתמכות ודוגמאות לבקשות ולתגובות ל-reconcile, ל-rollUp ול-dailyRollUp.

סינון נתונים לפי שעת התחלה אזרחית של מרווח זמן

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

לדוגמה:

בקשה

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

תשובה

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

סינון נתונים לפי זמן פיזי של תצפית לדוגמה

משתמשים בנקודת הקצה list עם הפרמטר filter כדי לסנן נתונים לפי הזמן הפיזי של תצפית הדגימה.

לדוגמה:

בקשה

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

תשובה

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

סינון וצבירה לפי משפחת מקורות נתונים

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

נקודות הקצה reconcile,‏ rollUp ו-dailyRollUp תומכות בפרמטר dataSourceFamily. מנגנון ההעברה תלוי בנקודת הקצה:

נקודת קצה (שיטת HTTP) מנגנון
reconcile (GET) מעבירים את dataSourceFamily כפרמטר של שאילתה בכתובת URL.
rollUp (POST) מעבירים את dataSourceFamily כשדה בגוף הבקשה ב-JSON.
dailyRollUp (POST) מעבירים את dataSourceFamily כשדה בגוף הבקשה ב-JSON.

משפחות של מקורות נתונים נתמכים

בטבלה הבאה מפורטים הערכים הנתמכים של dataSourceFamily:

אפשרות תיאור
users/me/dataSourceFamilies/all-sources ערך ברירת המחדל. הפונקציה מחזירה נקודות על הגרף שתואמות לכל מקורות הנתונים הרשומים מאינטראקציה ישירה (First-Party) ומצד שלישי (3P). האפשרות הזו תחזיר נתונים מאפליקציות של צד שלישי (למשל, צעדים משעון חכם + צעדים מאפליקציה של צד שלישי + צעדים מטלפון נייד + צעדים שהוזנו ידנית).
users/me/dataSourceFamilies/google-wearables כולל נתונים שתועדו על ידי מכשירי מעקב של Google ו-Fitbit (כמו מכשירי מעקב לבישים של Fitbit ו-Pixel Watch). לא כולל נתונים שנרשמו באופן ידני ונתונים משוערים מהטלפון. האפשרות הזו מתאימה אם השילוב שלכם דורש נתוני טלמטריה גולמיים של חיישנים, שמתועדים ישירות על ידי חומרה של מכשיר לביש.
users/me/dataSourceFamilies/google-sources כולל מקורות מאינטראקציה ישירה (First-Party) של Google ו-Fitbit. הנתונים האלה כוללים רשומות ממכשיר מעקב פיזי, נתונים מ-Health Connect וכל רשומה שהוזנה באופן ידני דרך אפליקציות של צד ראשון (כמו אפליקציית Fitbit או Google Fit).

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

לדוגמה, בקשת ה-GET הבאה מאחזרת את נתוני השינה שתועדו במכשיר המעקב ביום שאחרי 2026-03-03:

בקשה

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

תשובה

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

כדי לצבור נקודות על הגרף בחלון בגודל מסוים שמוגבל למשפחה מסוימת של מקורות נתונים, צריך להפעיל את נקודת הקצה rollUp ולהעביר את השדה dataSourceFamily בגוף הבקשה ב-JSON.

בקשת ה-POST הבאה שולחת שאילתה על ספירת הצעדים במהלך היום במרווחים של שעה (3600s), שנאספה אך ורק ממכשירים לבישים:

בקשה

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

תשובה

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

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

לדוגמה, הבקשה הבאה מחשבת את הסיכומים היומיים של הצעדים של המשתמש, כולל כל המקורות של Google ו-Fitbit (מכשירים לבישים ורשומות ידניות):

בקשה

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

תשובה

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

צבירת נקודות על הגרף בטווח זמן מסוים

משתמשים בנקודת הקצה (endpoint) rollUp כדי להחזיר את הנתונים המצטברים על סמך חלון זמן בשניות (windowSize), בטווח של datetime בזמן הפיזי של המשתמש (ב-UTC).

כשקוראים לנקודת הקצה rollUp, צריך לספק את גוף הבקשה שמייצג את הזמן הנדרש של סגירה-פתיחה range ו-windowSize (לפחות "1s"). להנחיות מפורטות לגבי הדרישות של windowSize, התאמה של רזולוציית האחסון, כללי חלוקה לקטגוריות ודוגמאות לבקשות ולתגובות, קראו את המאמר צבירה על פני מרווחי זמן פיזיים במדריך לנתונים נצברים.

צבירת נתונים של יום אחד או של כמה ימים

משתמשים בנקודת הקצה (endpoint) dailyRollUp כדי לצבור נתונים ביום אחד או בכמה ימים (windowSizeDays). מספקים את הזמן האזרחי (civil time) הסגור-פתוח range למרווח הזמן הנדרש בגוף הבקשה. בהתאם לסוג הנתונים, נקודת הקצה מחזירה את הסכום או את הממוצע בכל חלון.

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

עדכון נתוני הבריאות והכושר של המשתמש

כדי לעדכן את נתוני הבריאות והכושר של המשתמש, משתמשים בנקודת הקצה patch.

נקודת הקצה patch מעדכנת רשומה קיימת על סמך המזהה שצוין בכתובת ה-URL של הבקשה. מציינים את המזהה של נקודה על הגרף שהוספתם בעבר. ה-API מחליף את הרשומה הקיימת ומחזיר wrapper סינכרוני של google.longrunning.Operation.

כשיוצרים (POST) או מעדכנים (PATCH) נקודות על הגרף, סוגי נתונים של דגימות (כמו weight ו-body-fat) דורשים את sampleTime.utcOffset, וסוגי נתונים של מרווחים (כמו steps,‏ sleep ו-exercise) דורשים את interval.startUtcOffset ו-interval.endUtcOffset. מציינים את ההיסטים האלה כמשכי זמן בשניות ביחס ל-UTC, למשל "-14400s" ל-UTC-4 או "3600s" ל-UTC+1.

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

חותמות הזמן של המרווחים של נקודה על הגרף (startTime ו-endTime) יכולות להתעדכן גם על ידי הבעלים של הרשומה או להתפשט מפלטפורמות קודמות כמו Health Connect. לפרטים על שינוי חותמות זמן, קראו את המדריך לניהול נתונים. לדוגמה לעדכון חותמות זמן של מרווחים, ראו עדכון חותמות זמן של מרווחים לנתונים קיימים.

מתי כדאי להשתמש במזהה של נקודה על הגרף

מזהה נקודת הנתונים חיוני בתרחישים הבאים:

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

בדוגמה הבאה, משתמש מעדכן את קריאת אחוז השומן בגוף במשקל שנקרא HumanScale של החברה Scales R Us. הקריאה החדשה של אחוז השומן בגוף של המשתמש היא 20% לתאריך 2026-03-10:

בקשה

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z",
      "utcOffset": "-14400s"
    },
    "percentage": 20
  }
}

תשובה

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z",
        "utcOffset": "-14400s"
      },
      "percentage": 20
    }
  }
}

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

כדי לעדכן את חותמות הזמן של המרווח (startTime ו-endTime במטענים הייעודיים (payloads) של REST JSON, או start_time ו-end_time ב-gRPC) של נקודה קיימת על הגרף, שולחים בקשת PATCH ל-URI של המשאב של הנקודה על הגרף. רק היוצר או הבעלים המקוריים של רשומה יכולים לשנות את השדות שלה. אפליקציות לא יכולות לערוך נקודות על הגרף שהן לא יצרו.

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

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

בקשה

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "startUtcOffset": "-14400s",
      "endTime": "2026-09-03T10:19:59Z",
      "endUtcOffset": "-14400s"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

תשובה

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "startUtcOffset": "-14400s",
        "endTime": "2026-09-03T10:19:59Z",
        "endUtcOffset": "-14400s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 6,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 6,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

רישום פריט מזון

כדי לתעד פריט מזון, שולחים בקשת POST לנקודת הקצה nutrition-log dataPoints. גוף הבקשה מכיל DataPoint עם אובייקט nutritionLog. מידע נוסף זמין במדריך התזונה.

לדוגמה:

בקשה

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "startUtcOffset": "3600s",
      "endTime": "2026-06-16T12:30:00Z",
      "endUtcOffset": "3600s"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

תשובה

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "3600s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "3600s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

מחיקת נתוני הבריאות והכושר של המשתמשים

משתמשים ב-batchDelete method עם {"names": [...]} כדי למחוק מערך של נקודות על הגרף של משתמש. אין שיטת HTTP DELETE לנקודות על הגרף, והפונקציה batchDelete מחזירה wrapper סינכרוני של google.longrunning.Operation.

לדוגמה, משתמש תיעד בעבר את אחוז השומן בגוף שלו באמצעות משקל, אבל הוא רוצה למחוק את התיעוד. משתמשים ב-user-id וב-data-point-id מפעולת ההוספה המקורית:

בקשה

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

תשובה

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

איך למצוא את פרטי המכשיר

משתמשים בנקודת הקצה list כדי לאחזר את רשימת המכשירים שמותאמים לחשבון של המשתמש. המידע הזה כולל את פרטי הדגם של המכשיר (deviceVersion) ואת הפעם האחרונה שבה הוא סונכרן עם אפליקציית Google Health לנייד (lastSyncTime).

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

לדוגמה:

בקשה

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

תשובה

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

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

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

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

  • חלוקה אוטומטית לדפים: אם אתם שולחים שאילתה על טווח נתונים ארוך, ה-API יחזיר רק את הדף הראשון של התוצאות עד למגבלת גודל הדף של נקודת הקצה הזו, יחד עם nextPageToken. כדי לבקש את הדפים הבאים, צריך להשתמש ב-nextPageToken.
  • גודלי דפים משתנים: המגבלות תלויות בנקודת הקצה ובסוג הנתונים. ברוב סוגי הנתונים, גודל הדף מוגבל ל-10,000 לכל היותר. עם זאת, בסוגי נתונים מסוימים כמו exercise ו-sleep, גודל הדף המקסימלי וגודל ברירת המחדל מוגבלים ל-25. לדוגמה, אם לקוח מבקש את כל נתוני השינה מ-10 השנים האחרונות, ה-API עדיין יחזיר רק 25 רשומות שינה בדף הראשון.
  • הגבלות על טווחי תאריכים של אוסף נתונים: בנקודות קצה (endpoint) של אוסף נתונים וצבירת נתונים (כמו rollUp ו-dailyRollUp), טווחי התאריכים של השאילתות מוגבלים בהתאם לסוג הנתונים:
    • טווח מקסימלי של 14 ימים ל-calories-in-heart-rate-zone, heart-rate, active-minutes ו-total-calories.
    • טווח מקסימלי של 90 ימים לכל שאר סוגי הנתונים המצטברים.

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

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

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

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

חלוקת שאילתות לצבירה

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

שימוש באוספים נתונים שנצברו מראש

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

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

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