تطوير تجارب تمارين باستخدام Google Health API

تتتبّع واجهة Google Health API جلسات تمرين المستخدم وسجلّ التمارين باستخدام نوع بيانات الجلسة exercise. تعمل الجلسة كحاوية تجمع البيانات الوصفية للنشاط وأحداث الإيقاف المؤقت والاستئناف والجولات أو التقسيمات ومقاييس الملخّص.

تعرَّف على كيفية قراءة التمارين وكتابتها وتنظيمها في تطبيقك لتقديم أفضل تجربة للمستخدمين.

أنواع البيانات المتوافقة

تتيح واجهة برمجة التطبيقات استخدام نوع البيانات التالي لتتبُّع التمارين وجلسات النشاط:

الجدول: أنواع بيانات التمارين في Google Health API

نوع البيانات	العمليات المتاحة	النطاق
التمارين الرياضية dataType: exercise filter parameter: exercise نوع التسجيل: جلسة التوافق مع الويب هوك دليل التمارين الأجهزة المتوافقة Fitbit Air Fitbit Alta Fitbit Alta HR Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Edge Fitbit Flex 2 Fitbit Inspire Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Inspire HR Fitbit Ionic Fitbit Luxe Fitbit MobileTrack Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly

أنواع بيانات القياس عن بُعد ذات الصلة

على الرغم من أنّ جلسات التمارين الرياضية تستخدم نوع البيانات exercise كحاوية، تسجّل الأجهزة القابلة للارتداء أيضًا بيانات قياس عن بُعد مفصّلة وعالية التردد أثناء الجلسة. في Google Health API، تكون أنواع بيانات القياس عن بُعد الدقيقة هذه خلال اليوم للقراءة فقط ولا يمكن إنشاؤها أو تعديلها مباشرةً من خلال نقاط نهاية REST الخاصة بها. عند كتابة جلسة تمرين من خلال REST API، يجب إدخال مقاييس التمرين المجمّعة داخل العنصر metricsSummary لنقطة البيانات exercise.

يوضّح الجدول التالي حقول الملخّص داخل exercise.metricsSummary وربطها بأنواع بيانات القياس عن بُعد المقابلة لها التي تكون إذن بالقراءة فقط والتي يمكنك طلبها للفترة الزمنية الخاصة بالتمرين:

حقل الملخّص (metricsSummary)	اسم نوع بيانات القياس عن بُعد خلال اليوم	رقم تعريف نوع بيانات القياس عن بُعد في واجهة برمجة التطبيقات (للقراءة فقط)	حقل الفلتر (?filter=)	نطاق OAuth المطلوب للقراءة
caloriesKcal	سعرات حرارية محروقة بالنشاط	active-energy-burned	active_energy_burned.interval.start_time	activity_and_fitness.readonly
distanceMillimeters	المسافة	distance	distance.interval.start_time	activity_and_fitness.readonly
steps	الخطوات	steps	steps.interval.start_time	activity_and_fitness.readonly
averageHeartRateBeatsPerMinute	معدّل نبضات القلب	heart-rate	heart_rate.sample_time.physical_time	health_metrics_and_measurements.readonly
activeZoneMinutes	دقائق نطاق النشاط	active-zone-minutes	active_zone_minutes.interval.start_time	activity_and_fitness.readonly

تقدّم الأقسام التالية تفاصيل فنية عن نوع البيانات exercise، بما في ذلك أمثلة على تمثيل REST ومعالجة مسار GPS وإرشادات الدمج.

جلسات التمارين الرياضية

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

سمات الجلسة

عند تنظيم نقطة بيانات تمرين، تحقَّق من المكوّنات الأساسية التالية:

• وقت الجلسة (interval): وقت بدء جلسة التمرين بشكل عام ووقت انتهائها، بالإضافة إلى فروق التوقيت النشطة في تلك النقاط
• نوع النشاط (exerciseType): فئة النشاط الذي تم تنفيذه (مثل RUNNING أو WALKING أو BIKING أو AEROBIC_WORKOUT). حدِّد النوع الدقيق للتدريب البدني.
• الاسم المعروض (displayName): اسم سهل الاستخدام لجلسة التمرين عند إنشاء السمة من خلال REST API، يملأ الخادم الاسم المعروض المترجَم للسمة exerciseType، مثل "Run" للسمة RUNNING.
• مدة النشاط (activeDuration): الوقت الفعلي للنشاط في التمرين، باستثناء الفترات التي تم إيقافها مؤقتًا. يستخدم التنسيق العادي تنسيق Duration (على سبيل المثال، "1800s"). على الخادم، يتم احتساب activeDuration من interval الجلسة مطروحًا منها أي فواصل زمنية لـ PAUSE/RESUME أو AUTO_PAUSE/AUTO_RESUME في exerciseEvents.

ملخّص المقاييس

يحتوي العنصر المُدمَج metricsSummary على مقاييس إجمالية ومتوسطة يتم احتسابها على مدار مدة جلسة التمرين بالكامل:

• caloriesKcal: إجمالي السعرات الحرارية المحروقة النشطة أثناء التمرين، ويتم قياسها بالكيلو كالوري (kcal).
• ‫distanceMillimeters: إجمالي المسافة المقطوعة، ويتم قياسها بالملليمتر للحفاظ على دقة عالية في جميع الوحدات
• steps: إجمالي عدد الخطوات التي تم قطعها أثناء التمرين
• ‫averageHeartRateBeatsPerMinute: متوسط معدّل نبضات قلب المستخدم خلال الدقائق النشطة من الجلسة
• ‫activeZoneMinutes: دقائق نطاق النشاط التراكمية التي تم تحقيقها خلال التمرين
• ‫averageSpeedMillimetersPerSecond: متوسط سرعة الحركة بالملليمتر في الثانية
• ‫averagePaceSecondsPerMeter: متوسط وتيرة الجري خلال الدقائق النشطة من الجلسة، ويتم قياسه بالثواني لكل متر.
• ‫elevationGainMillimeters: إجمالي الزيادة في الارتفاع خلال الجلسة

اللفّات والفواصل الزمنية

بالنسبة إلى التمارين التي تتضمّن دورات (مثل الجري في المضمار أو السباحة في المسبح) والتي تتم مزامنتها من الأجهزة المتوافقة، يقسّم تطبيق splitSummaries الجلسة حسب الدورة أو التقسيم.

يحتوي كل تقسيم على:

• startTime وendTime محدّدان
• ‫activeDuration يمثّل الوقت الفعلي للدورة
• ‫metricsSummary يقتصر نطاقه على هذه الشريحة فقط
• ‫splitType لتحديد حدود التقسيم (مثل DISTANCE أو DURATION أو MANUAL)

أحداث التمارين الرياضية

لاحتساب المدة النشطة بدقة، يمكنك تتبُّع عمليات الانتقال بين الحالات (مثل أحداث الإيقاف المؤقت اليدوية أو التلقائية) باستخدام exerciseEvents.

يحتوي كل حدث على الطابع الزمني (eventTime) والنوع:

• ‫START / STOP: تشير إلى الطوابع الزمنية للحدود التي بدأ فيها المستخدم التسجيل أو أوقفه بشكل صريح.
• ‫PAUSE / RESUME: يشير إلى وقت إيقاف الجلسة مؤقتًا أو استئنافها يدويًا.
• ‫AUTO_PAUSE / AUTO_RESUME: يشير إلى عمليات الإيقاف المؤقت/الاستئناف التلقائية التي يتم تشغيلها بواسطة أداة الاستشعار.

كتابة بيانات جلسة تمرين

لإنشاء جلسة تمرين أو تعديلها أو استيرادها، اكتب نقطة بيانات في مجموعة أنواع البيانات exercise. استخدِم نقطة النهاية create dataPoints.

مثال على تمثيل REST

يوضّح المثال التالي كيفية كتابة جلسة تمرين باستخدام طريقة POST:

طلب

POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "platform": "GOOGLE_WEB_API"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageHeartRateBeatsPerMinute": "148",
      "averagePaceSecondsPerMeter": 0.36
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ]
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/999298779973222220/dataTypes/exercise/dataPoints/3054085373369111216",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "googleWebClientId": "438076457939-example.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "metricsSummary": {
        "caloriesKcal": 380,
        "distanceMillimeters": 5000000,
        "steps": "6200",
        "averagePaceSecondsPerMeter": 0.36,
        "averageHeartRateBeatsPerMinute": "148"
      },
      "exerciseMetadata": {},
      "displayName": "Run",
      "activeDuration": "1800s",
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "updateTime": "2026-04-20T08:35:10.123456Z",
      "createTime": "2026-04-20T08:35:10.123456Z"
    }
  }
}

مسارات من نظام تحديد المواقع العالمي (GPS) وتتبُّع الموقع الجغرافي

تحفظ واجهة برمجة التطبيقات ملخّصات الجلسات الأساسية مباشرةً ضمن نقطة بيانات exercise، ولكنّها تعالج سجلّ المواقع الجغرافية المفصّل وإحداثيات مسار نظام تحديد المواقع العالمي (GPS) كبيانات منفصلة.

لتنزيل بيانات المسار التفصيلية لجلسة في الهواء الطلق، يمكنك استدعاء الطريقة المخصّصة exportExerciseTcx. تعرض نقطة النهاية هذه المسار بتنسيق Training Center XML (TCX) المتّبع في المجال.

تصدير مسار GPS

طلب

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

الردّ

حمولة HTTP مع Content-Type: application/tcx+xml وعناوين تطلب من المتصفّح حفظ الملف

<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Id>2026-04-20T08:00:00Z</Id>
      <Lap StartTime="2026-04-20T08:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>380</Calories>
        <Intensity>Active</Intensity>
        <TriggerMethod>Manual</TriggerMethod>
        <Track>
          <Trackpoint>
            <Time>2026-04-20T08:00:00Z</Time>
            <Position>
              <LatitudeDegrees>37.7749</LatitudeDegrees>
              <LongitudeDegrees>-122.4194</LongitudeDegrees>
            </Position>
            <AltitudeMeters>15.0</AltitudeMeters>
            <DistanceMeters>0.0</DistanceMeters>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>

ملاحظة مهمة: يجب إلحاق `?alt=media` بعنوان URL للطلب لتنزيل ملف TCX الأوّلي. وإلا، يستجيب الخادم باستخدام مغلّف JSON عادي.

النطاقات والموقع الجغرافي المطلوبان

لاستخدام ميزة تتبُّع الموقع الجغرافي والمسارات من نظام تحديد المواقع العالمي (GPS)، يجب أن يطلب تطبيقك نطاقات OAuth التالية:

• القراءة: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• الكتابة: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
• القراءة: https://www.googleapis.com/auth/googlehealth.location.readonly

الإرشادات

عند دمج ميزة تتبُّع التمارين في تطبيقك، اتّبِع إرشادات التصميم والتنفيذ التالية.

المدة النشطة مقابل المدة الإجمالية

لحساب مقاييس السرعة أو الوتيرة، استخدِم دائمًا activeDuration بدلاً من الفرق بين startTime وendTime. يمنع ذلك الفترات المتوقفة مؤقتًا من تحريف المقاييس.

على سبيل المثال، إذا بدأ المستخدم تمرينًا في الساعة 08:00 وانتهى في الساعة 08:35، يكون إجمالي المدة المنقضية للتمرين 2,100 ثانية. إذا أوقف المستخدم التمرين مؤقتًا لمدة 5 دقائق (300 ثانية) وأدرجت حدثَي PAUSE وRESUME في exerciseEvents، ستكون المدة النشطة هي "1800s" (2,100 - 300). تستخدم واجهة برمجة التطبيقات المدة النشطة لاحتساب المتوسطات، وذلك من خلال قسمة إجمالي المسافة على 1,800 ثانية بدلاً من 2,100 ثانية.

احتساب السرعة والوتيرة

تستخدم واجهة Google Health API صيغًا عادية لاحتساب السرعة والوتيرة:

• السرعة = distance / time(hour)
• مستوى السرعة = time(seconds) / distance

يحدّد العنوان Accept-Language المحدّد في الطلب وحدة المسافة.

طلب الموقع الجغرافي مبكرًا

إذا كان تطبيقك يحدّد مسارات التمارين الرياضية، اطلب أذونات تحديد الموقع الجغرافي ونطاق Google Health location بالإضافة إلى نطاق النشاط واللياقة البدنية. يُرجى توضيح سبب حاجة تطبيقك إلى نطاق الموقع الجغرافي للمستخدمين عند مراجعة تمارين نظام تحديد المواقع العالمي (GPS).

عندما يطلب تطبيقك نطاق الموقع الجغرافي (https://www.googleapis.com/auth/googlehealth.location.readonly)، يعرض Google OAuth طلب موافقة للمستخدم. يجب أن توضّح للمستخدمين أنّ هذا الإذن ضروري لعرض تراكبات المسارات وتصدير ملفات التتبُّع عبر GPS ‏(TCX). إذا منح المستخدم إذن الوصول إلى نطاق النشاط ولكن رفض إذن تحديد الموقع الجغرافي، ستعرض واجهة برمجة التطبيقات exportExerciseTcx خطأ في التفويض، ولكن سيظل بإمكانك الوصول إلى إحصاءات الجلسات في metricsSummary.

المزامنة في الوقت الفعلي باستخدام الردود التلقائية على الويب

اشترِك في نوع البيانات exercise لإرسال إشعارات إلى الخلفية باستخدام الردود التلقائية على الويب عند توفّر بيانات جديدة عن التمارين. يتيح لك ذلك تفعيل تجارب ما بعد التمرين في الوقت الفعلي.

عندما يتلقّى خادمك إشعارًا من الويب هوك، يتضمّن الإشعار healthUserId والفاصل الزمني المدني (civilIso8601TimeInterval) للتمرين المعدَّل. يجب أن يقرّ الخادم الخاص بك باستلام الإشعار على الفور باستخدام 204 No Content، ومعالجة الحمولة بشكل غير متزامن، والاستعلام عن نقطة نهاية exercise التي تمت تسويتها باستخدام فلتر exercise.interval.civil_start_time (يُرجى العِلم أنّ exercise يتيح فقط الفلترة حسب civil_start_time):

GET https://health.googleapis.com/v4/users/healthUserId/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T08:00:00" AND exercise.interval.civil_start_time < "2026-04-20T10:00:00"

للحصول على تفاصيل حول كيفية إعداد الاشتراكات، يُرجى الاطّلاع على اشتراكات الويب هوك.

الحفاظ على اتساق المقاييس

لتوفير تجربة تمرين كاملة، يجب تضمين مقاييس الملخّص عند كتابة جلسات exercise والاستعلام عن نقاط نهاية القياس عن بُعد التي تتيح إذنًا بالقراءة فقط باستخدام فلاتر النطاق الزمني عند عرض الرسوم البيانية التفصيلية.

كتابة مقاييس ملخّص التمرين (مسار الكتابة)

عند استيراد تمرين مكتمل أو كتابته في Google Health API، يجب تضمين مقاييس القياس عن بُعد المجمّعة للتمرين (steps وcaloriesKcal وdistanceMillimeters وaverageHeartRateBeatsPerMinute وaveragePaceSecondsPerMeter) داخل عنصر metricsSummary لنقطة بيانات exercise:

• POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints

ملاحظة: إنّ أنواع بيانات القياس عن بُعد خلال اليوم (`steps` و`active-energy-burned` و`distance` و`معدّل نبضات القلب` و `active-zone-minutes`) تكون إذن بالقراءة فقط ولا يمكن إنشاؤها أو تعديلها مباشرةً من خلال نقاط نهاية REST الخاصة بها. بدلاً من ذلك، يمكنك تمرير مقاييس ملخّص التمرين من خلال حقل `metricsSummary` في نقطة بيانات `exercise`.

الاستعلام عن البيانات التفصيلية للرسوم البيانية (مسار القراءة)

لإنشاء لوحات بيانات أو رسوم بيانية للتمارين لجلسة معيّنة، يمكنك طلب البحث عن نقاط نهاية بيانات القياس عن بُعد التي تمت تسويتها خلال الفترة الزمنية لهذا التمرين:

1. يمكنك جلب جلسة التمرين من نقطة نهاية exercise باستخدام فلتر civil_start_time للحصول على interval وmetricsSummary:

   GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile?filter=exercise.interval.civil_start_time >= "2026-04-20T00:00:00" AND exercise.interval.civil_start_time < "2026-04-21T00:00:00"

2. استخدِم interval.startTime وinterval.endTime للجلسة لطلب نقاط نهاية بيانات القياس عن بُعد لتلك الفترة الزمنية الفعلية.

3. إذا كانت قيمة exerciseMetadata.hasGps هي true، يمكنك استدعاء exportExerciseTcx لتنزيل إحداثيات المسار.