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

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

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

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

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

الجدول: أنواع بيانات التمارين الرياضية في Google Health API
نوع البيانات العمليات
المتاحة		 النطاق
التمرين الرياضي
dataType: exercise
filter parameter: 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 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"
  },
  "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>

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

لاستخدام ميزة مسارات نظام تحديد المواقع العالمي (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 ثانية.

حساب السرعة ومستوى السرعة

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

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

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

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

إذا كان تطبيقك يرسم خرائط لمسارات التمارين الرياضية، اطلب أذونات الموقع الجغرافي ونطاق 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 لتنزيل إحداثيات المسار.
السابق
المؤشرات الحيوية
التالي
المعلومات الغذائية