נקודות קצה

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

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

ה-Google Health API פועל לפי התקנים של Google API Improvement Proposals (AIP), ובמיוחד AIP-127 (המרת קוד של HTTP ו-gRPC) ו-AIP-131 עד AIP-135 (שיטות סטנדרטיות). התקנים האלה מגדירים איך הנתונים ממופים מהודעת פרוטו לבקשת 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. קוראים לנקודת הקצה (endpoint) getIdentity מיד אחרי החלפת קוד ההרשאה כדי לאחזר את legacyUserId ו-healthUserId, ומוודאים שחשבון Google של המשתמש מקושר ל-Google Health. אם החשבון עדיין לא מקושר, getIdentity מחזיר את הערך 400 Bad Request עם הסיבה 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).

כדי לקבל מקור נתונים מותאם ממשפחה ספציפית של מקורות נתונים, צריך להפעיל את נקודת הקצה (endpoint) של 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"
      }
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

בקשה

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"
    },
    "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"
      },
      "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",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "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",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "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",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "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": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

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

משתמשים ב-batchDeletemethod כדי למחוק מערך של נתוני אפליקציית Fitbit של משתמש.

הנה דוגמה למקרה שבו משתמש תיעד בעבר את אחוז השומן בגוף שלו באמצעות משקל, אבל הוא רוצה למחוק את התיעוד. משתמשים ב-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) גדול שנכשל. ניסיונות חוזרים מיידיים מכפילים את העומס בקצה העורפי ומחמירים את הפגיעה במערכת.
הקודם
ספריות לקוח
הבא
מסננים