Google Health API จะติดตามเซสชันการออกกำลังกายและประวัติการออกกำลังกายของผู้ใช้โดยใช้ประเภทข้อมูลเซสชัน exercise เซสชันทำหน้าที่เป็นคอนเทนเนอร์ที่รวมข้อมูลเมตาของกิจกรรม เหตุการณ์หยุดชั่วคราวและเล่นต่อ รอบหรือการแยก และเมตริกสรุป
ทำความเข้าใจวิธีอ่าน เขียน และจัดโครงสร้างการออกกำลังกายในแอปพลิเคชันเพื่อมอบประสบการณ์ที่ดีที่สุดให้แก่ผู้ใช้
ประเภทข้อมูลที่รองรับ
API รองรับประเภทข้อมูลต่อไปนี้สำหรับการติดตามการออกกำลังกายและเซสชันกิจกรรม
| ประเภทข้อมูล | การดำเนินการ ที่ใช้ได้ |
ขอบเขต |
|---|---|---|
|
การออกกำลังกาย
dataType:
exercisefilter 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
ค้นหาข้อมูลโดยละเอียดสำหรับแผนภูมิ (เส้นทางการอ่าน)
หากต้องการสร้างแดชบอร์ดหรือแผนภูมิการออกกำลังกายสำหรับเซสชันที่เฉพาะเจาะจง ให้ค้นหาปลายทางการวัดและส่งข้อมูลทางไกลที่ปรับยอดแล้วสำหรับกรอบเวลาของการออกกำลังกายนั้นๆ ดังนี้
ดึงข้อมูลเซสชันการออกกำลังกายจากปลายทาง
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"
ใช้
interval.startTimeและinterval.endTimeของเซสชันเพื่อค้นหาปลายทาง Telemetry สำหรับกรอบเวลาจริงนั้นหาก
exerciseMetadata.hasGpsเป็นtrueให้เรียกใช้exportExerciseTcxเพื่อดาวน์โหลดพิกัดเส้นทาง