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

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

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

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

تتوافق واجهة برمجة التطبيقات مع نوع البيانات التالي لتتبُّع جلسات التمارين الرياضية والأنشطة:

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

نوع البيانات   dataType   مَعلمة filter	نوع السجلّ	العمليات المتاحة	النطاق	إمكانية استخدام إشعارات الويب	إمكانية استخدام الأصفار الحقيقية
التمرين الرياضي   exercise   exercise	الجلسة	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly

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

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

يربط الجدول التالي الحقول داخل العنصر metricsSummary لنوع البيانات exercise بأنواع بيانات القياس عن بُعد الأولية المقابلة في Google Health API:

حقل الملخّص (metricsSummary)	اسم نوع بيانات القياس عن بُعد خلال اليوم	رقم تعريف نوع بيانات القياس عن بُعد في واجهة برمجة التطبيقات
caloriesKcal	السعرات الحرارية المحروقة أثناء النشاط البدني	active-energy-burned
distanceMillimeters	المسافة	distance
steps	الخطوات	steps
averageHeartRateBeatsPerMinute	معدّل نبضات القلب	heart-rate
activeZoneMinutes	دقائق منطقة نشطة	active-zone-minutes

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

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

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

سمات الجلسة

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

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

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

يحتوي العنصر الفرعي 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 لنقاط البيانات.

مثال على تمثيل 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"
  },
  "exercise": {
    "interval": {
      "startTime": "2026-04-20T08:00:00Z",
      "startUtcOffset": "0s",
      "endTime": "2026-04-20T08:35:00Z",
      "endUtcOffset": "0s"
    },
    "exerciseType": "RUNNING",
    "displayName": "Morning Trail Run",
    "activeDuration": "1800s",
    "metricsSummary": {
      "caloriesKcal": 380.0,
      "distanceMillimeters": 5000000.0,
      "steps": "6200",
      "averageSpeedMillimetersPerSecond": 2777.78,
      "averagePaceSecondsPerMeter": 360.0,
      "averageHeartRateBeatsPerMinute": "148",
      "activeZoneMinutes": "30"
    },
    "exerciseMetadata": {
      "hasGps": true
    },
    "exerciseEvents": [
      {
        "eventTime": "2026-04-20T08:15:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "PAUSE"
      },
      {
        "eventTime": "2026-04-20T08:20:00Z",
        "eventUtcOffset": "0s",
        "exerciseEventType": "RESUME"
      }
    ],
    "splitSummaries": [
      {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:15:00Z",
        "endUtcOffset": "0s",
        "splitType": "DISTANCE",
        "metricsSummary": {
          "distanceMillimeters": 2500000.0,
          "caloriesKcal": 190.0
        }
      }
    ]
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/me/dataTypes/exercise/dataPoints/morning-trail-run-123456",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "application": {
        "packageName": "com.example.workoutapp"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "exercise": {
      "interval": {
        "startTime": "2026-04-20T08:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-04-20T08:35:00Z",
        "endUtcOffset": "0s"
      },
      "exerciseType": "RUNNING",
      "displayName": "Morning Trail Run",
      "activeDuration": "1800s",
      "metricsSummary": {
        "caloriesKcal": 380.0,
        "distanceMillimeters": 5000000.0,
        "steps": "6200",
        "averageSpeedMillimetersPerSecond": 2777.78,
        "averagePaceSecondsPerMeter": 360.0,
        "averageHeartRateBeatsPerMinute": "148",
        "activeZoneMinutes": "30"
      },
      "exerciseMetadata": {
        "hasGps": true
      },
      "exerciseEvents": [
        {
          "eventTime": "2026-04-20T08:15:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "PAUSE"
        },
        {
          "eventTime": "2026-04-20T08:20:00Z",
          "eventUtcOffset": "0s",
          "exerciseEventType": "RESUME"
        }
      ],
      "splitSummaries": [
        {
          "startTime": "2026-04-20T08:00:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-04-20T08:15:00Z",
          "endUtcOffset": "0s",
          "activeDuration": "900s",
          "splitType": "DISTANCE",
          "metricsSummary": {
            "distanceMillimeters": 2500000.0,
            "caloriesKcal": 190.0
          }
        }
      ]
    }
  }
}

مسارات نظام تحديد المواقع العالمي (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. يمنع ذلك الفواصل الزمنية التي تم إيقافها مؤقتًا من التأثير في مقاييسك.

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

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

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

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

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

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

عندما يتلقّى الخادم إشعارًا عبر إشعارات الويب، يحتوي على healthUserId والفترة الزمنية الفعلية المحدّدة للتمرين الرياضي. يجب أن يعالج الخادم الإشعار بشكل غير متزامن ثم يطلب نقطة البيانات الجديدة exercise من /users/me/dataTypes/exercise/dataPoints نقطة النهاية. لمعرفة تفاصيل حول كيفية إعداد الاشتراكات، اطّلِع على الاشتراكات في إشعارات الويب.

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

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

مزامنة بيانات القياس عن بُعد والجلسات (مسار الكتابة)

عند استيراد تمرين رياضي مكتمل أو كتابته في Google Health API، نفِّذ نمط كتابة متعدد الخطوات:

1. كتابة الجلسة: سجِّل حدث الملخّص من خلال نشر نقطة بيانات في POST /users/me/dataTypes/exercise/dataPoints.
2. كتابة الفواصل الزمنية المتسلسلة زمنيًا: اكتب في الوقت نفسه نقاط البيانات الدقيقة التي تم تسجيلها أثناء التمرين الرياضي (على سبيل المثال، الخطوات أو الفواصل الزمنية لحرق السعرات الحرارية كل دقيقة) في المجموعات الخاصة بها:
   • POST /users/me/dataTypes/steps/dataPoints
   • POST /users/me/dataTypes/active-energy-burned/dataPoints
   • POST /users/me/dataTypes/heart-rate/dataPoints

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

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

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

1. طلب ملخّصات الجلسة: استخدِم /users/me/dataTypes/exercise/dataPoints لجلب تفاصيل التمرين الرياضي بشكل عام و وmetricsSummary النهائي.
2. جلب مقاييس الرسم البياني: اطّلِع على interval.startTime و interval.endTime للتمرين الرياضي. استخدِم طلبات GET ثانوية لمجموعات بيانات القياس عن بُعد لهذه النافذة الزمنية المحدّدة:
   • GET /users/me/dataTypes/heart-rate/dataPoints?startTime=2026-04-20T08:00:00Z&endTime=2026-04-20T08:35:00Z
3. جلب مسارات نظام تحديد المواقع العالمي (GPS): إذا كانت البيانات الوصفية للجلسة تشير إلى توفّر بيانات نظام تحديد المواقع العالمي (GPS) (exerciseMetadata.hasGps هي true)، استخدِم الطريقة المساعدة exportExerciseTcx لتنزيل إحداثيات المسار.