نقطه‌های پایانی

این صفحه مروری بر قراردادهای REST API، به همراه فهرستی از وظایف رایج Google Health API و نمونه‌هایی از هر کدام ارائه می‌دهد.

قراردادهای REST API

رابط برنامه‌نویسی کاربردی گوگل هلث (Google Health API) از استانداردهای پیشنهادهای بهبود رابط کاربری گوگل (AIP) ، به‌ویژه AIP-127 (ترانس‌کدینگ HTTP و gRPC) و AIP-131 تا AIP-135 (روش‌های استاندارد) پیروی می‌کند. این استانداردها نحوه نگاشت داده‌ها از یک پیام اولیه به یک درخواست HTTP را تعریف می‌کنند.

پارامترهای پرس و جو

پارامترهای پرس‌وجو زمانی استفاده می‌شوند که داده‌ها بخشی از URL باشند. این در درجه اول برای درخواست‌های GET (دریافت یک منبع) یا درخواست‌های LIST (فیلتر کردن/صفحه‌بندی) است، اما برای عملیات DELETE نیز استفاده می‌شود.

• محل قرارگیری : بعد از علامت ? به آدرس اینترنتی (URL) اضافه می‌شود.
• نحو : جفت‌های کلید-مقدار با & از هم جدا می‌شوند.
• نگاشت : هر فیلدی در پیام درخواست که بخشی از الگوی مسیر URL نیست، به یک پارامتر پرس‌وجو نگاشت می‌شود.
• مناسب برای : انواع داده ساده (رشته‌ها، اعداد صحیح، اعداد شمارشی) و فیلدهای تکراری.

مثال نحوی:

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 استفاده می‌شود.

• محل قرارگیری : درون بار داده HTTP (در URL قابل مشاهده نیست).
• سینتکس : به صورت یک شیء JSON قالب‌بندی شده است.
• نگاشت : در حاشیه‌نویسی google.api.http تعریف شده است.
  • body: "*" به این معنی است که کل پیام بدنه است.
  • body: "resource_name" یعنی فقط یک فیلد خاص در پروتو، بدنه است.
• بهترین برای : اشیاء پیچیده، پیام‌های تو در تو و داده‌های حساس.

مثال نحوی:

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"
}

مورد ترکیبی

در یک متد Update منطبق با AIP-134 یا یک عملیات PATCH ، هر دو استفاده می‌شوند. 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

خرما

تمام تاریخ‌ها در API گوگل هلث با فرمت YYYY-MM-DD نمایش داده می‌شوند. API تغذیه از استاندارد ISO-8601 برای مقادیر تاریخ با شرایط زیر پشتیبانی می‌کند:

• یک سال چهار رقمی YYYY
• مقادیر سال در محدوده ۰۰۰۰-۹۹۹۹
• عدم اعمال محدودیت‌های تاریخ شروع مندرج در استاندارد ISO-8601 یا سایر استانداردهای دوره‌ای

سربرگ‌ها

اجرای نقاط پایانی API گوگل هلث نیاز به استفاده از هدرها و توکن دسترسی مناسب دارد. هدر زیر برای هر دو درخواست GET و POST توصیه می‌شود:

Authorization: Bearer access-token
Accept: application/json

فهرست وظایف API

این بخش فهرستی از وظایف رایج API سلامت گوگل و نمونه‌هایی از هر کدام را ارائه می‌دهد.

شناسه کاربری Fitbit یا Google را دریافت کنید

پس از اینکه کاربر از طریق Google OAuth 2.0 رضایت خود را اعلام کرد، پاسخ توکن حاوی شناسه کاربری Fitbit یا Google نیست. برای دریافت شناسه کاربری، نقطه پایانی getIdentity را فراخوانی کنید. getIdentity هم شناسه کاربری قدیمی Fitbit و هم شناسه کاربری Google را برمی‌گرداند.

توصیه می‌کنیم به محض اینکه کاربر جدید از طریق OAuth موافقت خود را اعلام کرد، نقطه پایانی getIdentity را فراخوانی کرده و هر دو شناسه کاربر را ذخیره کنید. این کار سازگاری رو به عقب و رو به جلو را در ادغام شما فراهم می‌کند.

برای مثال:

درخواست

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

پاسخ

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

داده‌های روزانه یا داده‌های دقیقی را که در طول روز جمع‌آوری شده‌اند، دریافت کنید

از نقطه پایانی 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"
}

فیلتر کردن داده‌ها بر اساس زمان شروع مدنی با فاصله زمانی

از نقطه پایانی list به همراه یک پارامتر filter برای فیلتر کردن داده‌ها بر اساس زمان مدنی یا یک بازه زمانی استفاده کنید.

نکته مهم: قالب شناسه‌های نوع داده زمانی که نوع داده بیش از یک کلمه دارد، متفاوت است. در یک نقطه پایانی، نام نوع داده باید به صورت kebab باشد، مانند body-fat . با این حال، در یک پارامتر فیلتر، نام نوع داده باید به صورت snake باشد، مانند body_fat .

برای مثال:

درخواست

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 برای فیلتر کردن داده‌ها بر اساس زمان فیزیکی مشاهده نمونه استفاده کنید.

نکته مهم: قالب شناسه‌های نوع داده زمانی که نوع داده بیش از یک کلمه دارد، متفاوت است. در یک نقطه پایانی، نام نوع داده باید به صورت kebab باشد، مانند body-fat . با این حال، در یک پارامتر فیلتر، نام نوع داده باید به صورت snake باشد، مانند body_fat .

برای مثال:

درخواست

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/2515055256096816351/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 برای دریافت داده‌ها بر اساس یک "خانواده منبع داده" در یک جریان تطبیق داده شده استفاده کنید.

نکته مهم: قالب شناسه‌های نوع داده زمانی که نوع داده بیش از یک کلمه دارد، متفاوت است. در یک نقطه پایانی، نام نوع داده باید به صورت kebab باشد، مانند body-fat . با این حال، در یک پارامتر فیلتر، نام نوع داده باید به صورت snake باشد، مانند body_fat .

در اینجا مثالی از فیلتر کردن فقط خواب ثبت‌شده توسط ردیاب برای روز بعد از 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 برای بازگرداندن مجموع نقاط داده بر اساس یک پنجره در واحد ثانیه، در محدوده datetime بر اساس زمان فیزیکی کاربر (به UTC) استفاده کنید.

هنگام فراخوانی نقطه پایانی rollUp ، باید بدنه درخواست را که نشان‌دهنده محدوده تاریخ مورد نیاز در زمان مدنی کاربر است، ارائه دهید. برای مثال:

درخواست

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

{
  "range": {
    "startTime": "2026-02-17T17:00:00Z",
    "endTime": "2026-02-17T17:59:59Z"
  },
  "windowSize": "30s"
}

پاسخ

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

جمع‌آوری داده‌ها در طول یک روز یا چند روز

نقطه پایانی dailyRollUp باید زمانی استفاده شود که می‌خواهید داده‌ها را در طول یک روز یا چند روز، که به عنوان windowSize شناخته می‌شود، جمع‌آوری کنید. محدوده زمانی مدنی بسته-باز را برای بازه مورد نیاز در بدنه درخواست ارائه دهید. بسته به نوع داده، یا مجموع یا میانگین را در بازه دریافت خواهید کرد.

برای مثال:

درخواست

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": 2,
        "day": 26
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 23,
        "minutes": 59,
        "seconds": 59,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1
}

پاسخ

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "3822"
      }
    }
  ]
}

داده‌های سلامت کاربر را وارد یا به‌روزرسانی کنید

از نقطه پایانی patch برای درج یا به‌روزرسانی داده‌های برنامه Fitbit کاربر استفاده کنید.

در اینجا مثالی آورده شده است که در آن یک کاربر چربی بدن خود را در ترازویی به نام "HumanScale" از شرکت "Scales R Us" ثبت کرده است. میزان چربی بدن جدید کاربر برای تاریخ 2026-03-10، 20٪ است.

درخواست

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
content-length: 329

{
  "name": "bodyFatName",
  "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/2515055256096816351/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
    }
  }
}

حذف داده‌های سلامت کاربر

از نقطه پایانی batchDelete برای حذف آرایه‌ای از داده‌های برنامه 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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

پاسخ

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