با استفاده از Google Health API، تجربه‌های ورزشی خود را توسعه دهید

رابط برنامه‌نویسی کاربردی گوگل هلث (Google Health API) جلسات تمرین کاربر و سابقه ورزش را با استفاده از نوع داده جلسه exercise ردیابی می‌کند. یک جلسه به عنوان ظرفی عمل می‌کند که فراداده‌های فعالیت، رویدادهای مکث و از سرگیری، تعداد دورها یا تقسیم‌بندی‌ها و معیارهای خلاصه را در خود جای می‌دهد.

نحوه خواندن، نوشتن و ساختاردهی تمرین‌ها در برنامه خود را درک کنید تا بهترین تجربه را برای کاربران خود ارائه دهید.

انواع داده پشتیبانی شده

این API از نوع داده زیر برای ردیابی تمرینات و جلسات فعالیت پشتیبانی می‌کند:

جدول: انواع داده‌های تمرینی API گوگل هلث
نوع داده
dataType
پارامتر filter		 رکورد
نوع		 موجود است
عملیات		 دامنه وب‌هوک
پشتیبانی		 صفرهای واقعی
پشتیبانی
ورزش
exercise
exercise		 جلسه لیست کردن، دریافت کردن، تطبیق دادن، ایجاد کردن، به‌روزرسانی کردن، حذف دسته‌ای فعالیت_و_تناسب_اندام

در حالی که جلسات تمرین از نوع داده exercise به عنوان ظرف استفاده می‌کنند، ردیاب‌های تمرین معمولی در طول جلسه، داده‌های تله‌متری با فرکانس بالا و با جزئیات را می‌نویسند و می‌خوانند. این اندازه‌گیری‌ها (مانند ضربان قلب یا تعداد گام‌ها) باید با استفاده از انواع داده مربوط به خود خوانده یا نوشته شوند.

جدول زیر فیلدهای داخل شیء metricsSummary از نوع داده exercise را به انواع داده خام تله‌متری مربوطه در Google Health API نگاشت می‌کند:

فیلد خلاصه ( metricsSummary ) نام نوع داده تله‌متری درون‌روزی شناسه نوع داده تله‌متری API
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 data points استفاده کنید.

مثال نمایش 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 و ردیابی موقعیت مکانی

این API خلاصه‌های اولیه جلسات را مستقیماً در نقطه داده 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 payload با 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

اگر یک محدوده مورد نیاز در هدرهای مجوز وجود نداشته باشد، API سلامت گوگل خطای مجوز را برمی‌گرداند.

دستورالعمل‌ها

هنگام ادغام ردیابی تمرین در برنامه خود، این دستورالعمل‌های طراحی و پیاده‌سازی را دنبال کنید.

مدت زمان فعال در مقابل کل مدت زمان

برای محاسبه‌ی معیارهای سرعت یا گام، همیشه از activeDuration به جای تفاوت بین startTime و endTime استفاده کنید. این کار از ایجاد انحراف در معیارهای شما توسط فواصل مکث جلوگیری می‌کند.

برای مثال، اگر کاربری تمرینی را ساعت ۰۸:۰۰ شروع کند و ساعت ۰۸:۳۵ تمام کند، مدت زمان کل تمرین ۲۱۰۰ ثانیه خواهد بود. اگر کاربر تمرین را به مدت ۵ دقیقه (۳۰۰ ثانیه) متوقف کند، activeDuration روی "1800s" (۲۱۰۰ - ۳۰۰) تنظیم کنید. API از مدت زمان فعال برای محاسبه میانگین‌ها استفاده می‌کند و مسافت کل را به جای ۲۱۰۰ بر ۱۸۰۰ ثانیه تقسیم می‌کند.

درخواست مکان را زودتر انجام دهید

اگر برنامه شما مسیرهای تمرین را نقشه‌برداری می‌کند، علاوه بر محدوده فعالیت و تناسب اندام، مجوزهای مکان و محدوده location Google Health را نیز درخواست کنید. هنگام بررسی تمرینات GPS، برای کاربران توضیح دهید که چرا برنامه شما به محدوده مکان نیاز دارد.

وقتی برنامه شما محدوده مکان را درخواست می‌کند ( https://www.googleapis.com/auth/googlehealth.location.readonly )، Google OAuth یک درخواست رضایت به کاربر نمایش می‌دهد. به کاربران خود توضیح دهید که این مجوز برای رندر کردن پوشش‌های مسیر و خروجی گرفتن از فایل‌های مسیر GPS (TCX) ضروری است. اگر کاربری محدوده فعالیت را اعطا کند اما مجوز مکان را رد کند، exportExerciseTcx خطای مجوزدهی را برمی‌گرداند، اگرچه شما همچنان می‌توانید به داده‌های نشست در metricsSummary دسترسی داشته باشید.

همگام‌سازی بلادرنگ با استفاده از وب‌هوک‌ها

برای اطلاع‌رسانی به backend خود از طریق webhooks در زمان در دسترس قرار گرفتن داده‌های جدید تمرین، در نوع داده exercise مشترک شوید. این به شما امکان می‌دهد تجربیات پس از تمرین را در زمان واقعی فعال کنید.

وقتی سرور شما یک اعلان وب‌هوک دریافت می‌کند، حاوی healthUserId و فاصله زمانی فیزیکی خاص تمرین است. سرور شما باید اعلان را به صورت ناهمزمان پردازش کند و سپس نقطه داده exercise جدید را از نقطه پایانی /users/me/dataTypes/exercise/dataPoints درخواست کند. برای جزئیات بیشتر در مورد نحوه تنظیم اشتراک‌ها، به اشتراک‌های وب‌هوک مراجعه کنید.

معیارهای ثابت را حفظ کنید

برای ارائه یک تجربه کامل ورزشی، برنامه شما باید نقاط داده تله‌متری با فرکانس بالا را با کل جلسه exercise همگام‌سازی کند. این امر تضمین می‌کند که مجموع روزانه کاربر، روندهای تاریخی و نمودارهای جزئیات کاملاً هماهنگ باقی بمانند.

همگام‌سازی تله‌متری و جلسات (مسیر نوشتن)

هنگام وارد کردن یا نوشتن یک تمرین کامل به 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. خلاصه جلسات را جستجو کنید : برای دریافت جزئیات کلی تمرین و metricsSummary نهایی /users/me/dataTypes/exercise/dataPoints را فراخوانی کنید.
  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 را برای دانلود مختصات مسیر فراخوانی کنید.
قبلی
کالری و انرژی