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

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

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

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

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

الجدول: أنواع بيانات التمارين في Google Health API
نوع البيانات
  dataType
  filter المَعلمة		 نوع
السجلّ
العمليات المتاحة		 النطاق إتاحة استخدام ويب هوك
 التوافق مع القيم الصفرية
التمرين
  exercise
  exercise 		الجلسة list, get, reconcile, create, update, batchDelete activity_and_fitness

في حين أنّ جلسات التمرين تستخدم نوع البيانات 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. تعرض نقطة النهاية هذه المسار بتنسيق 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

إذا كان نطاق مطلوب غير متوفّر في عناوين التفويض، ستعرض Google Health API خطأ في التفويض.

الإرشادات

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

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

لاحتساب مقاييس السرعة أو الوتيرة، استخدِم دائمًا 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)، يعرض بروتوكول OAuth من Google رسالة طلب موافقة للمستخدم. وضِّح للمستخدمين أنّ هذا الإذن ضروري لعرض تراكبات المسار وتصدير ملفات تتبُّع نظام تحديد المواقع العالمي (GPS) (ملف TCX). إذا منح المستخدم نطاق النشاط ولكنّه رفض إذن تحديد الموقع الجغرافي، ستعرض الدالة exportExerciseTcx خطأ في التفويض، ولكن سيظل بإمكانك الوصول إلى إحصاءات الجلسات في metricsSummary.

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

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

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

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

لتوفير تقييم التمرين الرياضي الكامل، يجب أن يزامن تطبيقك نقاط بيانات القياس عن بُعد العالية التردد مع جلسة 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): إذا كانت البيانات الوصفية للجلسة تشير إلى توفّر بيانات نظام تحديد المواقع العالمي (exerciseMetadata.hasGps هو true)، استخدِم طريقة المساعد exportExerciseTcx لتنزيل إحداثيات المسار.
السابق
السعرات الحرارية والطاقة