فیلتر کردن داده‌ها

‫Google Health API برای محدود کردن نقاط داده برگشتی هنگام فراخوانی روش‌های بازیابی استاندارد، به عبارت‌های فیلتر متکی است. به‌طور خاص، فیلترها با موارد زیر استفاده می‌شوند:

• list نقطه پایان: درحال پُرسمان نقاط داده خام.
• reconcileنقطه‌های پایانی: درحال پُرسمان کردن نقطه‌های داده جاری‌سازی آشتی‌داده‌شده.

این راهنما نحوه پیاده‌سازی فیلتر کردن، نحو و قراردادها، و نمونه‌هایی برای هر نوع گزارش را توضیح می‌دهد.

قراردادهای فیلتر

«میانای برنامه‌سازی کاربردی Google Health» فیلترها را براساس استاندارد پیشنهادهای بهبود Google API (AIP-160) پیاده‌سازی می‌کند.

پارامترهای پُرسمان

فیلترها بااستفاده از رشته پُرسمان نشانی وب در پارامتر filter منتقل می‌شوند. ازآنجایی‌که فیلترها حاوی نویسه‌های خاص (مثل <، >=، و نقل‌قول) هستند، وقتی در درخواست HTTP منتقل می‌شوند باید کدبندی نشانی وب شوند.

برای مثال، درخواستی با فیلتر steps.interval.civil_start_time >= "2026-03-04T00:00:00" باید به‌صورت زیر کدبندی شود:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time%20%3E%3D%20%222026-03-04T00%3A00%3A00%22

قالب نام‌گذاری

اگر نوع داده‌ای بیش‌از یک کلمه داشته باشد، قالب شناسه بین مسیر منبع و فیلتر متفاوت است:

• مسیر نقطه پایانی: از خط تیره استفاده کنید (برای مثال، /dataTypes/body-fat).
• رشته فیلتر: از زیرخط استفاده کنید (برای مثال، body_fat).

اگر در شناسه فیلتر از خط تیره استفاده کنید، API 400 Bad Request را با دلیل خطا INVALID_DATA_POINT_FILTER برمی‌گرداند.

فیلتر کردن انواع و فیلدها

فیلدهایی که در فیلتر استفاده می‌کنید به نوع گزارش نوع داده‌ای که پُرسمان می‌کنید بستگی دارد. جدول زیر فیلدهای پشتیبانی‌شده برای هر نوع سابقه را شرح می‌دهد:

عملگرهای پشتیبانی‌شده و قوانین قالب

عبارت‌های فیلتر باید از قوانین قالب‌بندی زیر پیروی کنند:

عملگرهای مقایسه

فقط از دو عملگر مقایسه پشتیبانی می‌شود:

استفاده از اپراتورهای مقایسه دیگر (مثل >، <=، یا =) باعث می‌شود 400 Bad Request با INVALID_DATA_POINT_FILTER_RESTRICTION_COMPARATOR برگردانده شود.

عملگرهای منطقی

حروف زمان

ثابت‌های زمان در عبارت‌های فیلتر باید از این قالب‌ها استفاده کنند:

قوانین اعتبارسنجی فیلتر

فیلترها از این قوانین پیروی می‌کنند:

میانای برنامه‌سازی کاربردی برای فیلترهای نامعتبر، 400 Bad Request‏ HTTP برمی‌گرداند. برای کد دلیل خطا، error.details[].metadata.detailedReasons را بررسی کنید.

حوزه‌های OAuth الزامی

برای پُرسمان کردن نقاط داده بااستفاده از فیلترها، کاربر مجاز باید محدوده OAuth مربوط به آن نوع داده را اعطا کند. اگر محدوده موردنیاز وجود نداشته باشد، API وضعیت 403 Forbidden را با MISSING_OAUTH_SCOPE برمی‌گرداند.

جدول زیر حوزه‌های OAuth را به انواع داده‌هایی که دسترسی خواندن به آن‌ها را اعطا می‌کنند تخصیص می‌دهد. جدول محدوده‌ها را در قالب نسبی آن‌ها نمایش می‌دهد (برای مثال، .activity_and_fitness.readonly نشان‌دهنده https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly است):

اگر کارخواه شما فقط محدوده نوشتن (مثل .activity_and_fitness.writeonly) برای نوع داده درخواستی داشته باشد، همچنان می‌توانید از نقاط داده‌ای که کارخواه خودتان نوشته است پُرسمان کنید. در این مورد، درخواست‌ها به‌طور ضمنی به خانواده منبع داده self-sources محدود می‌شوند. برای جزئیات و محدودیت‌های نوع داده، به فیلتر براساس خانواده منبع داده مراجعه کنید.

موارد استفاده و مثال‌ها

مثال‌های زیر نشان می‌دهد که چگونه فیلترها را برای سناریوهای رایج بسازید:

مراحل پُرسمان براساس محدوده زمانی فیزیکی

مراحل پُرسمان ضبط‌شده بین 2026-03-01T00:00:00Z (شامل) و 2026-03-02T00:00:00Z (غیرشامل):

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.start_time >= "2026-03-01T00:00:00Z"
  AND steps.interval.start_time < "2026-03-02T00:00:00Z"

مراحل پُرسمان براساس محدوده زمان مدنی

مراحل پُرسمان برای کل روز ۴ مارس ۲۰۲۶، نسبت به ساعت محلی کاربر:

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time >= "2026-03-04"
  AND steps.interval.civil_start_time < "2026-03-05"

پرسش چربی بدن براساس زمان نمونه فیزیکی

پرسش کردن درباره اندازه‌گیری‌های چربی بدن که از مارس ۲۰۲۶ (به زمان UTC) ضبط شده است:

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

وزن پُرسمان براساس زمان نمونه مدنی

گزارش‌های وزن پُرسمان ضبط‌شده پس‌از زمان محلی مشخص:

GET https://health.googleapis.com/v4/users/me/dataTypes/weight/dataPoints
  ?filter=weight.sample_time.civil_time >= "2026-03-01T08:00:00"

پُرسمان خلاصه روزانه تغییرپذیری ضربان قلب

پرسش تغییرپذیری ضربان قلب (HRV) خلاصه روزانه ضبط‌شده قبل‌از تاریخی خاص:

GET https://health.googleapis.com/v4/users/me/dataTypes/daily-heart-rate-variability/dataPoints
  ?filter=daily_heart_rate_variability.date < "2026-08-15"

جلسه‌های تمرین را براساس زمان شروع مدنی پُرسمان کنید

جلسه‌های تمرین را که در هفته‌ای خاص در منطقه زمانی محلی کاربر رخ داده است پُرسمان کنید:

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
  ?filter=exercise.interval.civil_start_time >= "2026-03-01"
  AND exercise.interval.civil_start_time < "2026-03-08"

پُرسمان جلسات خواب براساس زمان پایان مدنی

گزارش‌های خواب را براساس زمان پایان جلسه پُرسمان کنید:

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
  ?filter=sleep.interval.civil_end_time >= "2026-03-04T05:00:00"
  AND sleep.interval.civil_end_time < "2026-03-04T12:00:00"

الکتروقلب‌نگاره‌ها را براساس زمان شروع پُرسمان کنید

پُرسمان کردن از ضبط‌های نوار قلب از یک نقطه زمانی UTC فیزیکی. توجه داشته باشید که پُرسمان‌های نوار قلب فقط از مقایسه >= در start_time پشتیبانی می‌کنند:

GET https://health.googleapis.com/v4/users/me/dataTypes/electrocardiogram/dataPoints
  ?filter=electrocardiogram.interval.start_time >= "2026-03-10T12:00:00Z"

فیلتر کردن براساس خانواده منبع داده

خانواده منبع داده یک گروه‌بندی منطقی از منابع داده است (مثل ساعت‌های هوشمند، برنامه‌های تلفن همراه، یا ورودی‌های دستی). این ویژگی به شما امکان می‌دهد داده‌های انواع خاصی از منابع (برای مثال، دستگاه‌های پوشیدنی فیزیکی، ورودی‌های دستی، یا داده‌های نوشته‌شده توسط کارخواه خودتان) را مجزا یا تجمیع کنید.

نقطه‌های پایانی list،‏ reconcile،‏ rollUp، و dailyRollUp همه از پارامتر dataSourceFamily پشتیبانی می‌کنند. سازوکار انتقال به نقطه پایانی بستگی دارد:

خانواده‌های منبع داده پشتیبانی‌شده

جدول زیر مقادیر پشتیبانی‌شده dataSourceFamily را شرح می‌دهد:

اگر هیچ نقطه داده‌ای با خانواده منبع داده درخواست‌شده مطابقت نداشته باشد، پاسخ به‌جای خطا، فهرست خالی است.

خودمنابع و محدوده‌های فقط نوشتنی

تماس‌گیرندگانی که فقط دامنه‌های نوشتن (مثل .activity_and_fitness.writeonly) برای انواع داده‌های درخواست‌شده به آن‌ها اعطا شده است می‌توانند داده‌هایی را که خودشان نوشته‌اند بخوانند و فقط همان داده‌ها را بخوانند.

• درخواست‌های بدون پارامتر صریح dataSourceFamily، یا با dataSourceFamily تنظیم‌شده روی users/me/dataSourceFamilies/self-sources، به‌طور ضمنی به self-sources محدود می‌شوند.
• درخواست برای هر خانواده منبع داده دیگری (مثل all-sources، google-wearables، یا google-sources) با تنها یک محدوده نوشتن با خطای 403 Forbidden (PERMISSION_DENIED) مواجه می‌شود.

محدودیت‌های نوع داده در نقطه پایان فهرست

در نقطه پایانی list (users.dataTypes.dataPoints.list)، فیلتر کردن براساس dataSourceFamily برای انواع داده sleep، food، و food-measurement-unit پشتیبانی نمی‌شود:

• تنظیم صریح dataSourceFamily در list برای sleep،‏ food، یا food-measurement-unit با خطای 400 Bad Request (INVALID_ARGUMENT) ناموفق است.
• فراخوانی list برای این نوع داده‌ها وقتی فقط محدوده نوشتن اعطا شده باشد (در جایی که محدودیت self-sources با محدوده‌های تماس‌گیرنده ضمنی است) با خطای 403 Forbidden (PERMISSION_DENIED) ناموفق است.
• برای فیلتر کردن sleep نقطه داده براساس dataSourceFamily، به‌جای آن از نقطه پایان reconcile استفاده کنید.

نمونه‌های خانواده منبع داده

برای فهرست کردن نقطه‌های داده خام که کارخواه خودتان برای کاربر نوشته است، list نقطه پایانی را با پارامتر پُرسمان dataSourceFamily تنظیم‌شده روی users/me/dataSourceFamilies/self-sources فراخوانی کنید.

برای مثال، درخواست GET زیر فهرست اندازه‌گیری‌های body-fat خام را که مشتری تماس‌گیرنده از تاریخ ۲۰۲۶-۰۳-۰۱ نوشته است ارائه می‌دهد:

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints
  ?dataSourceFamily=users/me/dataSourceFamilies/self-sources
  &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": ""
}

برای دریافت جاری‌سازی داده‌های تطبیق‌داده‌شده از خانواده منبع داده‌ای خاص، با پارامتر پُرسمان dataSourceFamily، نقطه پایانی reconcile را فراخوانی کنید.

برای مثال، درخواست GET زیر خواب ضبط‌شده با ردیاب را برای روز بعداز ۲۰۲۶-۰۳-۰۳ واکشی می‌کند:

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