داده‌های تجمیعی

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

• نقطه پایانی rollUp نقاط داده را در فواصل زمانی فیزیکی در ساعت هماهنگ جهانی بااستفاده از مدت پنجره قابل‌پیکربندی برحسب ثانیه (windowSize) جمع‌آوری می‌کند.
• نقطه پایانی dailyRollUp نقاط داده را در یک یا چند روز تقویمی (windowSizeDays) بااستفاده از زمان رسمی نسبت به ساعت محلی کاربر تجمیع می‌کند.

هر دو نقطه پایان به‌طور خودکار نقاط داده هم‌پوشان را در دستگاه‌های متصل تطبیق می‌دهند و دوره‌هایی را که دستگاه روی مچ نبوده است برای انواع داده‌های پوشیدنی که از تشخیص روی مچ پشتیبانی می‌کنند مستثنی می‌کنند.

مقایسه نقاط پایانی انبوهش

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

ویژگی	rollUp نقطه پایانی	dailyRollUp نقطه پایانی
درخواست HTTP	POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp	POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:dailyRollUp
نمایش زمان	زمان فیزیکی در UTC (startTime و endTime در قالب RFC 3339).	زمان مدنی (start و end به‌عنوان اشیای CivilDateTime).
پارامتر پنجره	windowSize (مدت زمان رشته موردنیاز برحسب ثانیه، حداقل "1s").	windowSizeDays (تعداد روزها به‌صورت عدد صحیح اختیاری، پیش‌فرض 1 است).
شیء پاسخ	RollupDataPoint	DailyRollupDataPoint
ترتیب پاسخ‌ها	ترتیب زمانی معکوس (جدیدترین پنجره اول).	ترتیب زمانی معکوس (جدیدترین پنجره اول).
بهترین برای	نمودارهای درون‌روزی، هیستوگرام‌های ساعتی یا دقیقه‌ای، و تحلیل UTC با مدت ثابت.	داشبوردهای روزانه، روندهای چندروزه، و خلاصه‌هایی که سفر در مناطق زمانی مختلف یا ساعت تابستانی را درنظر می‌گیرند.

هر دو نقطه پایانی حداکثر محدودیت‌های محدوده پُرسمان را براساس نوع داده اعمال می‌کنند:

• حداکثر محدوده پُرسمان ۱۴ روزه برای calories-in-heart-rate-zone، heart-rate، active-minutes، و total-calories اعمال می‌شود.
• حداکثر محدوده پُرسمان ۹۰ روز برای همه انواع داده‌های پشتیبانی‌شده دیگر اعمال می‌شود.

برای بررسی اینکه کدام نوع داده از rollup و dailyRollup پشتیبانی می‌کند، به مرجع انواع داده Google Health API مراجعه کنید.

مجموع در بازه‌های زمانی فیزیکی

از نقطه پایان rollUp برای تجمیع نقاط داده در یک زمان فیزیکی range (به‌وقت ساعت هماهنگ جهانی) که براساس مدت زمان پنجره به ثانیه (windowSize) گروه‌بندی شده است استفاده کنید.

هنگام فراخوانی نقطه پایانی rollUp، یک بدنه درخواست JSON حاوی range بسته-باز (startTime شامل، endTime انحصاری) و windowSize ارائه دهید. الزامات windowSize زیر را به‌خاطر داشته باشید:

• مدت windowSize باید حداقل ۱ ثانیه ("1s") باشد. API مدت‌های کمتر از ثانیه، صفر، یا منفی را با خطای 400 Bad Request (INVALID_ROLLUP_WINDOW) رد می‌کند.
• برای جلوگیری از توزیع نابرابر داده‌های تجمیعی در زیردسته‌ها، windowSize را انتخاب کنید که برابر یا بزرگ‌تر از وضوح ذخیره‌سازی زیربنایی نوع داده باشد (مثلاً "60s" برای فاصله‌های زمانی ۱ دقیقه‌ای قدم‌ها). برای جزئیات، پنجره تجمیع و وضوح فضای ذخیره‌سازی را ببینید.

برای مثال، درخواست زیر تعداد قدم‌ها را در فاصله‌های زمانی ۱ دقیقه‌ای جمع‌آوری می‌کند (60s):

درخواست

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": "60s"
}

پاسخ

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:56:00Z",
      "steps": {
        "countSum": "72"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:55:00Z",
      "steps": {
        "countSum": "85"
      }
    },
...
  ]
}

مجموع در روزهای تقویم

از نقطه پایانی dailyRollUp برای تجمیع داده‌ها در یک روز تقویمی یا چند روز (windowSizeDays) استفاده کنید. زمان رسمی بسته-باز range (start و end) را در بدنه درخواست ارائه دهید. بسته به نوع داده، نقطه پایانی مقادیر تجمیعی مانند مجموع یا میانگین را در هر پنجره مدنی برمی‌گرداند.

ازآنجایی‌که dailyRollUp براساس زمان رسمی و بااستفاده از اختلاف‌های UTC ثبت‌شده با هر نقطه داده عمل می‌کند، به‌طور خودکار طول متغیر روزها را که ناشی از تغییرات ساعت تابستانی یا سفر در مناطق زمانی مختلف است، تطبیق می‌دهد.

برای مثال، درخواست زیر تعداد قدم‌ها را در یک روز مدنی (windowSizeDays: 1) جمع‌آوری می‌کند:

درخواست

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

تجمیع براساس خانواده منبع داده

rollUp و dailyRollUp هر دو فیلد اختیاری dataSourceFamily را در بدنه درخواست JSON می‌پذیرند تا انبوهش را به گروه‌های منبع خاص محدود کنند:

• گزینه users/me/dataSourceFamilies/all-sources (پیش‌فرض) داده‌های تطبیق‌داده‌شده در همه منابع طرف اول و طرف سوم ثبت‌شده را تجمیع می‌کند.
• گزینه users/me/dataSourceFamilies/google-wearables داده‌های ثبت‌شده توسط دستگاه‌های ردیاب پوشیدنی Google و Fitbit را تجمیع می‌کند، به‌استثنای داده‌های ثبت‌شده به‌صورت دستی و داده‌های تخمین‌زده‌شده توسط تلفن.
• گزینه users/me/dataSourceFamilies/google-sources داده‌ها را از منابع شخص اول Google و Fitbit، ازجمله ردیاب‌های پوشیدنی، Health Connect، و ورودی‌های دستی در برنامه‌های شخص اول، جمع‌آوری می‌کند.

برای اطلاع از الزامات کامل پارامتر و نمونه‌های درخواست و پاسخ، به فیلتر کردن براساس خانواده منبع داده در راهنمای فیلتر کردن داده‌ها مراجعه کنید.

پنجره جمع‌بندی و وضوح فضای ذخیره‌سازی

اگرچه نقطه پایانی rollUp هر windowSize ۱ ثانیه ("1s") یا بیشتر را می‌پذیرد، انواع مختلف داده‌ها اندازه‌گیری‌ها را با نرخ‌های نمونه‌برداری یا مدت‌زمان‌های فاصله متفاوت در فضای ذخیره‌سازی زیربنایی ثبت و حفظ می‌کنند. برای مثال، سنجه‌های فعالیت فیزیکی پوشیدنی‌ها مثل steps، distance، active-minutes، و active-energy-burned معمولاً در فواصل ۱ دقیقه‌ای (60s) ضبط می‌شوند.

جدول زیر وضوح‌های فضای ذخیره‌سازی پایه و حداقل مقادیر windowSize توصیه‌شده برای انواع داده‌های رایج را فهرست می‌کند:

وضوح ذخیره‌سازی	حداقل ملزومات توصیه‌شده windowSize	انواع داده
‫۱ ثانیه (1s)	"1s"	heart-rate
‫۱ دقیقه (60s)	"60s"	‫active-energy-burned،‏ active-minutes،‏ active-zone-minutes،‏ altitude،‏ calories-in-heart-rate-zone،‏ distance،‏ floors،‏ steps،‏ time-in-heart-rate-zone،‏ total-calories

هنگام انبوهش انواع داده‌های بازه‌ای، نقطه پایانی rollUp هر نقطه داده ثبت‌شده را در دسته‌ای قرار می‌دهد که حاوی startTime نقطه داده است. این API داده‌های بازه‌ای را در دسته‌های زیربازه‌ای تقسیم، درون‌یابی، یا توزیع نمی‌کند.

اگر windowSize را کوچک‌تر از فاصله ذخیره‌سازی داده‌های اصلی مشخص کنید (برای مثال، درخواست پنجره ۱۰ ثانیه‌ای برای steps ذخیره‌شده در فواصل ۱ دقیقه‌ای):

1. اولین زیردسته منطبق با startTime بازه (برای مثال، 10:00:00 تا 10:00:10) کل تعداد انباشته‌شده دقیقه را دریافت می‌کند (برای مثال، همه ۱۰۰ قدم ثبت‌شده برای آن دقیقه).
2. زیردسته‌های باقی‌مانده در همان دقیقه (10:00:10 تا 10:00:20، 10:00:20 تا 10:00:30، و غیره) هیچ نقطه داده‌ای دریافت نمی‌کنند، زیرا هیچ فاصله‌ای در آن پنجره‌ها شروع نمی‌شود.

این کار داده‌های نوک‌تیزی تولید می‌کند که در آن مقدار کل بازه در اولین زیرپنجره متمرکز شده است، همان‌طور که در شکل ۱ نشان داده شده است.

شکل ۱: دسته‌بندی تجمیع زیرفاصله که در آن فاصله ۱ دقیقه‌ای به اولین زیردسته ۱۰ ثانیه‌ای براساس startTime اختصاص داده شده است

برای به‌دست آوردن مجموعه‌های توزیع‌شده و معنی‌دار، همیشه windowSize را روی مدت‌زمانی برابر یا بیشتر از وضوح ذخیره‌سازی اساسی نوع داده هدف تنظیم کنید (برای مثال، "60s" یا بزرگ‌تر برای steps). برای وضوح ذخیره‌سازی و حداقل پنجره تجمیع توصیه‌شده برای هر نوع داده، به مرجع انواع داده Google Health API مراجعه کنید.

دسته‌بندی وقتی محدوده مضربی از اندازه پنجره نیست

اگر محدوده درخواستی مضرب دقیقی از windowSize (یا windowSizeDays) نباشد، آخرین دسته زمانی در نقطه پایانی بالایی محدوده کوتاه می‌شود و مدت‌زمانی کوتاه‌تر از اندازه پنجره را پوشش می‌دهد. ‫API درخواست شما را بدون تغییر می‌پذیرد و گرد کردن، تغییر زمان، یا درون‌یابی داده‌ها را انجام نمی‌دهد.

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

Number of windows = ceiling(Range duration / Window size)

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

نحوه عملکرد دسته‌بندی

وقتی درخواست خلاصه با محدوده‌های غیرقابل‌تقسیم می‌دهید، API قوانین زیر را اعمال می‌کند:

• دسته‌بندی از ابتدای محدوده درخواستی شما (range.startTime یا range.start) شروع می‌شود و براساس اندازه پنجره (windowSize یا windowSizeDays) پیش می‌رود.
• آخرین دسته زمانی در انتهای محدوده درخواستی شما (range.endTime یا range.end) قرار می‌گیرد و مدت‌زمان کوتاه‌تری نسبت به اندازه پنجره درخواستی را پوشش می‌دهد.
• اشیاء RollupDataPoint یا DailyRollupDataPoint برگردانده‌شده شامل مُهرهای زمان شروع و پایان صریح خودشان هستند که می‌توانید از آن‌ها برای بررسی مدت واقعی دسته کوتاه شده استفاده کنید.
• چون میانای برنامه‌سازی کاربردی داده‌های تجمیعی را به‌ترتیب زمانی معکوس (جدیدترین در ابتدا) برمی‌گرداند، آخرین دسته زمانی (دسته کوتاه‌شده) به‌عنوان اولین عنصر (index 0) در فهرست برگردانده‌شده ظاهر می‌شود.

شکل ۲ نشان می‌دهد که چگونه API یک محدوده غیرقابل تقسیم را از range.startTime به جلو دسته‌بندی می‌کند، دسته نهایی را در range.endTime محدود می‌کند، و دسته‌های حاصل را به ترتیب زمانی معکوس برمی‌گرداند.

شکل ۲: دسته‌بندی تجمیعی، کوتاه کردن انتهای محدوده، و ترتیب پاسخ زمانی معکوس

نمونه محدوده ۱۲ دقیقه‌ای با پنجره ۵ دقیقه‌ای

فرض کنید مشتری درخواست تجمیع در محدوده ۱۲ دقیقه‌ای با windowSize ("300s") ۵ دقیقه‌ای دارد:

• مقدار range.startTime برابر با 10:00:00Z است.
• مقدار range.endTime برابر با 10:12:00Z است، برای مدت کل ۱۲ دقیقه.
• مقدار windowSize برابر با "300s" (۵ دقیقه) است.

چون ۱۲ دقیقه مضرب دقیقی از ۵ دقیقه (12 = 5 * 2 + 2) نیست، میانای برنامه‌سازی کاربردی تعداد پنجره‌ها را ceiling(12 / 5) = 3 محاسبه می‌کند. این کار سه دسته زمانی تولید می‌کند:

سطل	فاصله	مدت	وضعیت بازه زمانی
سطل ۱	[10:00:00Z, 10:05:00Z)	‫۵ دقیقه	تمام‌پنجره
سطل ۲	[10:05:00Z, 10:10:00Z)	‫۵ دقیقه	تمام‌پنجره
سطل ۳	[10:10:00Z, 10:12:00Z)	‫۲ دقیقه	در range.endTime کوتاه شد

تأثیر بر مقادیر انبوهشی

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

اگر کاربری با سرعت ثابت ۱۰۰ قدم در دقیقه در کل این بازه ۱۲ دقیقه‌ای راه برود، دسته‌ها حاوی مجموع‌های زیر خواهند بود:

• بازه ۱ (10:00:00Z تا 10:05:00Z) ۵۰۰ قدم را ثبت می‌کند (۵ دقیقه باسرعت ۱۰۰ قدم در دقیقه).
• بازه ۲ (10:05:00Z تا 10:10:00Z) ۵۰۰ قدم را ثبت می‌کند (۵ دقیقه با سرعت ۱۰۰ قدم در دقیقه).
• بازه ۳ (10:10:00Z تا 10:12:00Z) ۲۰۰ قدم را ثبت می‌کند (۲ دقیقه با ۱۰۰ قدم در دقیقه).

تعداد گام‌های کمتر (۲۰۰ گام) در «بخش ۳» به‌دلیل مدت ۲ دقیقه‌ای پنجره کوتاه‌شده است، نه کاهش فعالیت کاربر. هنگام رسم یا تحلیل این داده‌ها، تعداد را بااستفاده از مدت زمان صریح هر دسته نرمال‌سازی کنید تا از ارائه کاهش گمراه‌کننده در فعالیت کاربر جلوگیری شود.

شکل ۳ مجموع گام‌های افزایشی خام (countSum) را با نرخ‌های نرمال‌شده براساس مدت در سه دسته مقایسه می‌کند.

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

نمونه پاسخ میانای برنامه‌سازی کاربردی که ترتیب را نشان می‌دهد

چون API نتایج را به‌ترتیب زمانی معکوس برمی‌گرداند، سطل کوتاه شده به‌عنوان اولین عنصر در فهرست برگردانده‌شده ظاهر می‌شود:

{
  "rollupDataPoints": [
    {
      "startTime": "2026-08-20T10:10:00Z",
      "endTime": "2026-08-20T10:12:00Z",
      "steps": {
        "countSum": "200"
      }
    },
    {
      "startTime": "2026-08-20T10:05:00Z",
      "endTime": "2026-08-20T10:10:00Z",
      "steps": {
        "countSum": "500"
      }
    },
    {
      "startTime": "2026-08-20T10:00:00Z",
      "endTime": "2026-08-20T10:05:00Z",
      "steps": {
        "countSum": "500"
      }
    }
  ]
}