พัฒนาประสบการณ์การออกกำลังกายด้วย Google Health API

Google Health API จะติดตามเซสชันการออกกำลังกายและประวัติการออกกำลังกายของผู้ใช้โดยใช้ประเภทข้อมูลเซสชัน exercise เซสชันทำหน้าที่เป็นคอนเทนเนอร์ที่รวมข้อมูลเมตาของกิจกรรม เหตุการณ์หยุดชั่วคราวและเล่นต่อ รอบหรือการแยก และเมตริกสรุป

ทำความเข้าใจวิธีอ่าน เขียน และจัดโครงสร้างการออกกำลังกายในแอปพลิเคชันเพื่อมอบประสบการณ์ที่ดีที่สุดให้แก่ผู้ใช้

ประเภทข้อมูลที่รองรับ

API รองรับประเภทข้อมูลต่อไปนี้สำหรับการติดตามการออกกำลังกายและเซสชันกิจกรรม

ตาราง: ประเภทข้อมูลการออกกำลังกายของ Google Health API
ประเภทข้อมูล การดำเนินการ
ที่ใช้ได้
ขอบเขต
การออกกำลังกาย
dataType: exercise
filter parameter: exercise
ประเภทระเบียน: เซสชัน

อุปกรณ์ที่เข้ากันได้

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) ชื่อประเภทข้อมูลที่ได้รับจากทางไกลระหว่างวัน รหัสประเภทข้อมูลการตรวจวัดระยะไกลของ API (อ่านอย่างเดียว) ช่องตัวกรอง (?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 และการติดตามตำแหน่ง

API จะบันทึกข้อมูลสรุปเซสชันพื้นฐานไว้ในจุดข้อมูล 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 วิธีนี้จะป้องกันไม่ให้ช่วงเวลาที่หยุดชั่วคราวทำให้เมตริกของคุณคลาดเคลื่อน

ตัวอย่างเช่น หากผู้ใช้เริ่มออกกำลังกายเวลา 08:00 น. และเสร็จสิ้นเวลา 08:35 น. การออกกำลังกายจะมีระยะเวลาที่ผ่านไปทั้งหมด 2,100 วินาที หากผู้ใช้หยุดการออกกำลังกายชั่วคราวเป็นเวลา 5 นาที (300 วินาที) และคุณรวมเหตุการณ์ PAUSE และ RESUME ไว้ใน exerciseEvents ระยะเวลาที่ใช้งานอยู่คือ "1800s" (2,100 - 300) API จะใช้ระยะเวลาที่ใช้งานอยู่เพื่อคำนวณค่าเฉลี่ย โดยหารระยะทางทั้งหมดด้วย 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"

ดูรายละเอียดเกี่ยวกับวิธีตั้งค่าการสมัครใช้บริการได้ที่การสมัครใช้บริการ Webhook

รักษาเมตริกให้สม่ำเสมอ

หากต้องการมอบประสบการณ์การออกกำลังกายที่สมบูรณ์ ให้รวมเมตริกสรุปเมื่อเขียนเซสชัน exercise และค้นหาปลายทางการวัดและส่งข้อมูลทางไกลแบบอ่านอย่างเดียวโดยใช้ตัวกรองช่วงเวลาเมื่อแสดงผลแผนภูมิรายละเอียด

เขียนเมตริกสรุปการออกกำลังกาย (เส้นทางการเขียน)

เมื่อนำเข้าหรือเขียนการออกกำลังกายที่เสร็จสมบูรณ์ไปยัง Google Health API ให้รวมเมตริกการตรวจวัดระยะไกลแบบรวมของการออกกำลังกาย (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute และ averagePaceSecondsPerMeter) ไว้ในออบเจ็กต์ metricsSummary ของจุดข้อมูล exercise ดังนี้

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

ค้นหาข้อมูลโดยละเอียดสำหรับแผนภูมิ (เส้นทางการอ่าน)

หากต้องการสร้างแดชบอร์ดหรือแผนภูมิการออกกำลังกายสำหรับเซสชันที่เฉพาะเจาะจง ให้ค้นหาปลายทางการวัดและส่งข้อมูลทางไกลที่ปรับยอดแล้วสำหรับกรอบเวลาของการออกกำลังกายนั้นๆ ดังนี้

  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 ของเซสชันเพื่อค้นหาปลายทาง Telemetry สำหรับกรอบเวลาจริงนั้น

  3. หาก exerciseMetadata.hasGps เป็น true ให้เรียกใช้ exportExerciseTcx เพื่อดาวน์โหลดพิกัดเส้นทาง