بيانات مجمّعة

توفّر Google Health API نقاط نهاية مخصّصة لتجميع البيانات، حيث يتم تجميع السجلات الصحية وتلخيصها في فترات زمنية محدّدة. بدلاً من استرداد السجلات الأولية الفردية وجمعها على العميل، استخدِم نقاط نهاية التجميع لاحتساب المقاييس (مثل الإجماليات والمتوسطات والحدود الدنيا والقصوى) على مصدر بيانات تمت تسويته:

• تجمع نقطة النهاية rollUp نقاط البيانات على مدار فترات زمنية فعلية بالتوقيت العالمي المنسق (UTC) باستخدام مدة نافذة قابلة للضبط بالثواني (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
تمثيل الوقت	الوقت الفعلي بالتوقيت العالمي المنسَّق (startTime وendTime بتنسيق RFC 3339)	التوقيت المدني (start وend كعناصر CivilDateTime)
مَعلمة النافذة	‫windowSize (المدة المطلوبة للسلسلة بالثواني، والحد الأدنى هو "1s")	‫windowSizeDays (عدد صحيح اختياري للأيام، والقيمة التلقائية هي 1)
Response object	RollupDataPoint	DailyRollupDataPoint
ترتيب الردود	ترتيب زمني عكسي (النافذة الأحدث أولاً)	ترتيب زمني عكسي (النافذة الأحدث أولاً)
أفضل مع	الرسوم البيانية خلال اليوم، والمدرّجات التكرارية على مستوى الساعة أو الدقيقة، وتحليل التوقيت العالمي المنسّق (UTC) لمدة ثابتة	لوحات بيانات يومية ومؤشرات لعدة أيام وملخّصات تأخذ في الاعتبار السفر عبر مناطق زمنية مختلفة أو نظام التوقيت الصيفي

تفرض كلتا نقطتَي النهاية حدودًا قصوى لنطاق طلبات البحث استنادًا إلى نوع البيانات:

• ينطبق الحد الأقصى لنطاق طلب البحث الذي يبلغ 14 يومًا على calories-in-heart-rate-zone وheart-rate وactive-minutes وtotal-calories.
• ينطبق الحد الأقصى لنطاق طلب البحث الذي يبلغ 90 يومًا على جميع أنواع البيانات الأخرى المتوافقة.

لمعرفة أنواع البيانات التي تتيح استخدام rollup وdailyRollup، يُرجى الاطّلاع على مرجع أنواع البيانات في Google Health API.

التجميع على فترات زمنية فعلية

استخدِم نقطة النهاية rollUp لتجميع نقاط البيانات خلال فترة زمنية فعلية range (بالتوقيت العالمي المنسق) مصنَّفة حسب مدة النافذة بالثواني (windowSize).

عند طلب نقطة النهاية rollUp، يجب تقديم نص طلب JSON يحتوي على range المغلق والمفتوح (startTime شامل، endTime حصري) و windowSize. يُرجى مراعاة متطلبات windowSize التالية:

• يجب أن تكون مدة windowSize ثانية واحدة على الأقل ("1s"). ترفض واجهة برمجة التطبيقات المدد التي تقل عن ثانية أو المدد الصفرية أو السالبة مع ظهور الخطأ 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 لنقطة البيانات. لا تعمل واجهة برمجة التطبيقات على تقسيم بيانات الفترات الزمنية أو استكمالها أو توزيعها على مجموعات الفترات الزمنية الفرعية.

إذا حدّدت windowSize أصغر من الفاصل الزمني الأساسي لتخزين البيانات (على سبيل المثال، طلب نافذة مدتها 10 ثوانٍ لـ steps المخزّنة على فترات دقيقة واحدة):

1. يتلقّى أول قسم فرعي يطابق startTime الخاص بالفترة الزمنية (على سبيل المثال، من 10:00:00 إلى 10:00:10) العدد المتراكم للدقيقة بأكملها (على سبيل المثال، جميع الخطوات البالغ عددها 100 خطوة المسجَّلة لتلك الدقيقة).
2. لا تتلقّى المجموعات الفرعية المتبقية ضمن الدقيقة نفسها (من 10:00:10 إلى 10:00:20، ومن 10:00:20 إلى 10:00:30، وهكذا) أي نقاط بيانات، لأنّه لا تبدأ أي فترة ضمن هذه النوافذ.

يؤدي ذلك إلى إنشاء بيانات متقطعة حيث تتركز قيمة الفاصل الزمني بأكمله في النافذة الفرعية الأولى، كما هو موضح في الشكل 1.

الشكل 1: تجميع الفترات الفرعية حيث يتم تخصيص فترة دقيقة واحدة لأول مجموعة فرعية مدتها 10 ثوانٍ حسب startTime

للحصول على مجاميع موزّعة بالتساوي وذات مغزى، اضبط دائمًا windowSize على مدة تساوي أو تزيد عن دقة التخزين الأساسية لنوع البيانات المستهدف (على سبيل المثال، "60s" أو أكبر لـ steps). لمعرفة دقة التخزين والحد الأدنى الموصى به للنافذة المجمّعة لكل نوع بيانات، راجِع مرجع أنواع بيانات Google Health API.

التجميع عندما لا يكون النطاق من مضاعفات حجم النافذة

إذا لم يكن النطاق المطلوب مضاعفًا دقيقًا لـ windowSize (أو windowSizeDays)، يتم اقتطاع المجموعة الزمنية النهائية عند نقطة النهاية العليا للنطاق وتغطي مدة أقصر من حجم النافذة. تقبل واجهة برمجة التطبيقات طلبك بدون تعديل ولا تُجري أي تقريب أو تغييرات في الوقت أو استكمال للبيانات.

لتغطية النطاق المطلوب بالكامل، تستخدم واجهة برمجة التطبيقات القسمة مع التقريب للأعلى لحساب إجمالي عدد نوافذ التجميع:

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

تبدأ كل مجموعة بشكل تسلسلي من بداية النطاق. إذا كانت إضافة نافذة أخرى بالحجم الكامل تتجاوز وقت الانتهاء المطلوب، يتم اقتطاع النافذة النهائية (تثبيتها) عند وقت انتهاء النطاق.

آلية عمل التصنيف

عند طلب تجميعات بنطاقات غير قابلة للقسمة، تطبّق واجهة برمجة التطبيقات القواعد التالية:

• يبدأ التجميع في بداية النطاق المطلوب (range.startTime أو range.start) ويتقدّم للأمام حسب حجم النافذة (windowSize أو windowSizeDays).
• يتم تثبيت المجموعة الزمنية الأخيرة في نهاية النطاق المطلوب (range.endTime أو range.end)، وتغطي مدة أقصر من حجم النافذة المطلوبة.
• تتضمّن عناصر RollupDataPoint أو DailyRollupDataPoint التي يتم عرضها طوابع زمنية صريحة للبدء والانتهاء، ويمكنك استخدامها لفحص المدة الفعلية للمجموعة المقتطعة.
• بما أنّ واجهة برمجة التطبيقات تعرض بيانات مجمّعة بترتيب زمني عكسي (الأحدث أولاً)، تظهر المجموعة الزمنية النهائية (المجموعة المقتطعة) كأول عنصر (index 0) في القائمة المعروضة.

يوضّح الشكل 2 كيف تقسّم واجهة برمجة التطبيقات نطاقًا غير قابل للقسمة إلى مجموعات من range.startTime، وتثبّت المجموعة النهائية عند range.endTime، وتعرض المجموعات الناتجة بترتيب زمني عكسي.

الشكل 2: تجميع البيانات في مجموعات، واقتطاع نهاية النطاق، وترتيب الردود ترتيبًا زمنيًا عكسيًا

مثال على نطاق زمني مدته 12 دقيقة مع نافذة مدتها 5 دقائق

لنفترض أنّ أحد العملاء طلب تجميعًا على مدار نطاق زمني مدته 12 دقيقة مع windowSize ("300s") مدته 5 دقائق:

• قيمة range.startTime هي 10:00:00Z.
• قيمة range.endTime هي 10:12:00Z، لمدة إجمالية تبلغ 12 دقيقة.
• قيمة windowSize هي "300s" (5 دقائق).

بما أنّ 12 دقيقة ليست مضاعفًا دقيقًا لـ 5 دقائق (12 = 5 * 2 + 2)، تحسب واجهة برمجة التطبيقات عدد النوافذ على أنّه ceiling(12 / 5) = 3. ينتج عن ذلك ثلاث مجموعات زمنية:

الحزمة	الفاصل الزمني	المدة	حالة فترة العرض
المجموعة 1	[10:00:00Z, 10:05:00Z)	5 دقائق	نافذة كاملة
المجموعة 2	[10:05:00Z, 10:10:00Z)	5 دقائق	نافذة كاملة
المجموعة 3	[10:10:00Z, 10:12:00Z)	دقيقتان	تم اقتطاعها عند range.endTime

التأثير في القيم المجمّعة

بما أنّ النافذة الزمنية الأخيرة لها مدة أقصر، تكون المقاييس المضافة (مثل مجموع الخطوات أو عددها) أقل في المجموعة المقتطعة بسبب الفترة الزمنية الأقصر.

إذا مشى المستخدم بوتيرة ثابتة تبلغ 100 خطوة في الدقيقة خلال هذا النطاق الذي تبلغ مدته 12 دقيقة، ستحتوي المجموعات على الإجماليات التالية:

• تسجّل الفئة 1 (من 10:00:00Z إلى 10:05:00Z) 500 خطوة (5 دقائق بمعدل 100 خطوة في الدقيقة).
• وتسجّل المجموعة 2 (من 10:05:00Z إلى 10:10:00Z) 500 خطوة (5 دقائق بمعدّل 100 خطوة في الدقيقة).
• تسجّل الفئة 3 (من 10:10:00Z إلى 10:12:00Z) 200 خطوة (دقيقتان بمعدّل 100 خطوة في الدقيقة).

ويعود انخفاض عدد الخطوات إلى 200 خطوة في المجموعة 3 إلى مدة النافذة المقتطعة التي تبلغ دقيقتين، وليس إلى انخفاض في نشاط المستخدم. عند رسم هذه البيانات أو تحليلها، يجب تسوية الأعداد باستخدام المدة الصريحة لكل مجموعة لتجنُّب عرض انخفاض مضلِّل في نشاط المستخدم.

يقارن الشكل 3 بين إجمالي الخطوات المضافة الأولية (countSum) والمعدلات التي تم تطبيعها حسب المدة عبر المجموعات الثلاث.

الشكل 3: إجمالي القيم المضافة الأولية مقارنةً بالمعدلات التي تم تسويتها حسب المدة لمجموعة مجمّعة مقتطعة

مثال على ردّ من واجهة برمجة التطبيقات يعرض الترتيب

بما أنّ واجهة برمجة التطبيقات تعرض النتائج بترتيب زمني عكسي، تظهر المجموعة المقتطعة كأول عنصر في القائمة المعروضة:

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