Google Health API theo dõi các buổi tập và nhật ký tập thể dục của người dùng bằng cách sử dụng loại dữ liệu phiên exercise. Phiên hoạt động đóng vai trò là vùng chứa gộp siêu dữ liệu hoạt động, sự kiện tạm dừng và tiếp tục, số vòng hoặc số lần phân tách và chỉ số tóm tắt.
Tìm hiểu cách đọc, ghi và cấu trúc các bài tập thể dục trong ứng dụng để mang lại trải nghiệm tốt nhất cho người dùng.
Các loại dữ liệu được hỗ trợ
API này hỗ trợ loại dữ liệu sau để theo dõi các buổi tập thể dục và phiên hoạt động:
| Loại dữ liệu | Các thao tác có thể thực hiện |
Phạm vi |
|---|---|---|
|
Tập thể dục
dataType:
exercisefilter parameter: exercise
Loại bản ghi: Phiên
Thiết bị tương thích
|
list, get, reconcile, create, update, batchDelete | .activity_and_fitness.readonly.activity_and_fitness.writeonly |
Các loại dữ liệu đo từ xa có liên quan
Mặc dù các buổi tập thể dục sử dụng loại dữ liệu exercise làm vùng chứa, nhưng thiết bị đeo cũng ghi lại dữ liệu đo từ xa chi tiết, tần suất cao trong một buổi tập. Trong
API Google Health, các loại dữ liệu đo từ xa chi tiết trong ngày này chỉ có thể đọc
và không thể tạo hoặc sửa đổi trực tiếp thông qua các điểm cuối REST của riêng chúng.
Khi ghi một buổi tập thông qua API REST, hãy truyền các chỉ số tổng hợp về buổi tập vào bên trong đối tượng metricsSummary của điểm dữ liệu exercise.
Bảng sau đây liên kết các trường tóm tắt bên trong exercise.metricsSummary với các loại dữ liệu đo từ xa trong ngày chỉ có thể đọc tương ứng mà bạn có thể truy vấn trong khung thời gian của bài tập thể dục đó:
Trường tóm tắt (metricsSummary) |
Tên loại dữ liệu đo từ xa trong ngày | Mã loại dữ liệu đo từ xa của API (chỉ đọc) | Trường bộ lọc (?filter=) |
Phạm vi OAuth đọc bắt buộc |
|---|---|---|---|---|
caloriesKcal |
Năng lượng đốt cháy khi hoạt động | active-energy-burned |
active_energy_burned.interval.start_time |
activity_and_fitness.readonly |
distanceMillimeters |
Khoảng cách | distance |
distance.interval.start_time |
activity_and_fitness.readonly |
steps |
Các bước | steps |
steps.interval.start_time |
activity_and_fitness.readonly |
averageHeartRateBeatsPerMinute |
Nhịp tim | heart-rate |
heart_rate.sample_time.physical_time |
health_metrics_and_measurements.readonly |
activeZoneMinutes |
Số phút hoạt động cho vùng nhịp tim | active-zone-minutes |
active_zone_minutes.interval.start_time |
activity_and_fitness.readonly |
Các phần sau đây cung cấp thông tin kỹ thuật về loại dữ liệu exercise, bao gồm cả ví dụ về cách biểu thị REST, cách xử lý tuyến đường GPS và nguyên tắc tích hợp.
Phiên tập thể dục
Ghi dữ liệu về các hoạt động hoặc bài tập thể dục hằng ngày dưới dạng điểm dữ liệu của phiên exercise. Mỗi điểm dữ liệu mô tả toàn bộ phiên, thông tin chi tiết về khoảng thời gian diễn ra sự kiện (chẳng hạn như hành động tạm dừng và tiếp tục) và cung cấp các chỉ số tóm tắt (như tổng quãng đường, số bước và tần số tim trung bình).
Thuộc tính của phiên
Khi tạo cấu trúc cho một điểm dữ liệu bài tập thể dục, hãy xác minh các thành phần cốt lõi sau:
- Thời gian của buổi tập (
interval): Thời gian bắt đầu và thời gian kết thúc của toàn bộ buổi tập, cùng với độ lệch múi giờ có hiệu lực tại các thời điểm đó. - Loại hoạt động (
exerciseType): Danh mục hoạt động được thực hiện (chẳng hạn nhưRUNNING,WALKING,BIKINGhoặcAEROBIC_WORKOUT). Hãy chỉ định chính xác loại hình tập luyện thể chất. - Tên hiển thị (
displayName): Tên thân thiện với người dùng cho buổi tập thể dục. Khi được tạo thông qua API REST, máy chủ sẽ điền tên hiển thị đã bản địa hoá choexerciseType, chẳng hạn như"Run"choRUNNING. - Thời lượng hoạt động (
activeDuration): Thời gian hoạt động thực tế của bài tập thể dục, không bao gồm các khoảng thời gian tạm dừng. Định dạng chuẩn sử dụng định dạngDuration(ví dụ:"1800s"). Trên máy chủ,activeDurationđược tính từ phiênintervaltrừ đi mọi khoảng thời gianPAUSE/RESUMEhoặcAUTO_PAUSE/AUTO_RESUMEtrongexerciseEvents.
Chỉ số tóm tắt
Đối tượng lồng nhau metricsSummary chứa các chỉ số tổng và trung bình được tính trong toàn bộ thời lượng của buổi tập:
caloriesKcal: Tổng lượng calo đã đốt cháy trong quá trình tập luyện, tính bằng kilocalories (kcal).distanceMillimeters: Tổng quãng đường đã đi, được đo bằng milimét để duy trì độ chính xác cao trên các đơn vị.steps: Tổng số bước thực hiện trong bài tập.averageHeartRateBeatsPerMinute: Tần số tim trung bình của người dùng trong số phút hoạt động của phiên.activeZoneMinutes: Tổng số phút hoạt động cho vùng nhịp tim đạt được trong buổi tập.averageSpeedMillimetersPerSecond: Tốc độ di chuyển trung bình tính bằng milimét/giây.averagePaceSecondsPerMeter: Tốc độ trung bình trong số phút hoạt động của phiên, được đo bằng giây/mét.elevationGainMillimeters: Tổng mức tăng độ cao trong phiên.
Vòng và phân tách
Đối với những bài tập có vòng (chẳng hạn như chạy trên đường đua hoặc bơi trong hồ bơi) được đồng bộ hoá từ các thiết bị được hỗ trợ, splitSummaries sẽ phân đoạn phiên tập theo vòng hoặc phân đoạn.
Mỗi phần phân tách chứa:
startTimevàendTimecụ thể.activeDurationbiểu thị thời gian thực tế của vòng đua.metricsSummarychỉ trong phạm vi phân khúc đó.splitTypeđể xác định ranh giới phân tách (chẳng hạn nhưDISTANCE,DURATIONhoặcMANUAL).
Sự kiện tập thể dục
Để tính toán chính xác thời lượng hoạt động, hãy theo dõi các chuyển đổi trạng thái (như sự kiện tạm dừng thủ công hoặc tự động) bằng exerciseEvents.
Mỗi sự kiện đều chứa dấu thời gian (eventTime) và loại:
START/STOP: Cho biết dấu thời gian ranh giới khi người dùng bắt đầu hoặc dừng bản ghi một cách rõ ràng.PAUSE/RESUME: Cho biết thời điểm phiên được tạm dừng hoặc tiếp tục theo cách thủ công.AUTO_PAUSE/AUTO_RESUME: Cho biết tính năng tự động tạm dừng/tiếp tục dựa trên cảm biến.
Ghi dữ liệu về buổi tập thể dục
Để tạo, cập nhật hoặc nhập một buổi tập thể dục, hãy ghi một điểm dữ liệu vào tập hợp loại dữ liệu exercise. Sử dụng điểm cuối create dataPoints.
Ví dụ về cách trình bày REST
Ví dụ sau đây minh hoạ cách ghi một buổi tập bằng phương thức POST:
Yêu cầu
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"
}
]
}
}Phản hồi
{
"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"
}
}
}Tuyến đường GPS và theo dõi vị trí
API này lưu thông tin tóm tắt cơ bản về phiên trực tiếp trong điểm dữ liệu exercise, nhưng xử lý nhật ký vị trí chi tiết và toạ độ tuyến đường GPS dưới dạng một luồng riêng biệt.
Để tải dữ liệu tuyến đường chi tiết cho một buổi tập ngoài trời, hãy gọi phương thức tuỳ chỉnh exportExerciseTcx. Điểm cuối này trả về tuyến đường ở định dạng Training Center XML (TCX) theo tiêu chuẩn ngành.
Xuất tuyến đường GPS
Yêu cầu
GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media Authorization: Bearer access-token
Phản hồi
Một tải trọng HTTP có Content-Type: application/tcx+xml và
tiêu đề hướng dẫn trình duyệt lưu tệp.
<?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>Phạm vi và vị trí bắt buộc
Để sử dụng tính năng theo dõi vị trí và tuyến đường GPS, ứng dụng của bạn phải yêu cầu các phạm vi OAuth sau:
- Đọc:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly - Viết:
https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly - Đọc:
https://www.googleapis.com/auth/googlehealth.location.readonly
Nguyên tắc
Khi tích hợp tính năng theo dõi hoạt động tập thể dục vào ứng dụng, hãy làm theo các nguyên tắc thiết kế và triển khai sau đây.
Thời lượng hoạt động so với tổng thời lượng
Để tính toán chỉ số tốc độ hoặc nhịp độ, hãy luôn sử dụng activeDuration thay vì sự khác biệt giữa startTime và endTime. Việc này giúp các khoảng thời gian tạm dừng
không làm sai lệch chỉ số của bạn.
Ví dụ: nếu người dùng bắt đầu tập thể dục lúc 08:00 và kết thúc lúc 08:35, thì tổng thời gian tập thể dục là 2.100 giây. Nếu người dùng tạm dừng bài tập thể dục trong 5 phút (300 giây) và bạn đưa các sự kiện PAUSE và RESUME vào exerciseEvents, thì thời lượng hoạt động là "1800s" (2.100 – 300). API này sử dụng thời lượng hoạt động để tính giá trị trung bình, chia tổng quãng đường cho 1.800 giây thay vì 2.100 giây.
Tính toán tốc độ và nhịp độ
API Google Health sử dụng các công thức chuẩn để tính tốc độ và nhịp độ:
- Tốc độ =
distance / time(hour) - Tốc độ =
time(seconds) / distance
Tiêu đề Accept-Language được chỉ định trong yêu cầu sẽ xác định đơn vị khoảng cách.
Yêu cầu quyền truy cập thông tin vị trí sớm
Nếu ứng dụng của bạn lập bản đồ lộ trình tập luyện, hãy yêu cầu quyền truy cập vị trí và phạm vi Google Health location ngoài phạm vi hoạt động và thể dục. Giải thích cho người dùng lý do ứng dụng của bạn cần có phạm vi vị trí khi xem lại các bài tập thể dục có GPS.
Khi ứng dụng của bạn yêu cầu phạm vi vị trí (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth sẽ hiển thị lời nhắc đồng ý cho người dùng. Giải thích cho người dùng rằng quyền này là cần thiết để hiển thị lớp phủ tuyến đường và xuất tệp theo dõi qua GPS (TCX). Nếu người dùng cấp quyền truy cập vào phạm vi hoạt động nhưng từ chối cấp quyền truy cập vị trí, thì exportExerciseTcx sẽ trả về lỗi uỷ quyền, mặc dù bạn vẫn có thể truy cập vào dữ liệu tổng hợp của phiên trong metricsSummary.
Đồng bộ hoá bằng webhook
Đăng ký loại dữ liệu exercise để thông báo cho phần phụ trợ của bạn bằng webhook khi có dữ liệu mới về bài tập thể dục. Nhờ vậy, bạn có thể tự động kích hoạt
trải nghiệm sau khi tập luyện.
Khi máy chủ của bạn nhận được thông báo webhook, thông báo đó sẽ chứa healthUserId và khoảng thời gian dân sự (civilIso8601TimeInterval) của bài tập thể dục đã cập nhật. Máy chủ của bạn phải xác nhận thông báo ngay lập tức bằng 204 No Content, xử lý tải trọng không đồng bộ và truy vấn điểm cuối exercise đã đối chiếu bằng bộ lọc exercise.interval.civil_start_time (lưu ý rằng exercise chỉ hỗ trợ lọc theo 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"
Để biết thông tin chi tiết về cách thiết lập gói thuê bao, hãy xem phần Gói thuê bao webhook.
Duy trì các chỉ số nhất quán
Để mang lại trải nghiệm tập luyện hoàn chỉnh, hãy thêm các chỉ số tóm tắt khi ghi lại các phiên exercise và truy vấn các điểm cuối đo từ xa chỉ có thể đọc bằng bộ lọc phạm vi thời gian khi kết xuất biểu đồ chi tiết.
Ghi chỉ số tóm tắt về hoạt động tập thể dục (đường dẫn ghi)
Khi nhập hoặc ghi một bài tập đã hoàn thành vào API Google Health, hãy thêm các chỉ số đo từ xa tổng hợp của bài tập (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute và averagePaceSecondsPerMeter) vào bên trong đối tượng metricsSummary của điểm dữ liệu exercise:
POST https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Truy vấn dữ liệu chi tiết cho biểu đồ (đường dẫn đọc)
Để tạo trang tổng quan hoặc biểu đồ tập luyện cho một phiên cụ thể, hãy truy vấn các điểm cuối đo từ xa đã điều chỉnh cho khung thời gian của bài tập đó:
Tìm nạp buổi tập thể dục từ điểm cuối
exercisebằng bộ lọccivil_start_timeđể lấyintervalvà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"
Sử dụng
interval.startTimevàinterval.endTimecủa phiên để truy vấn các điểm cuối đo từ xa cho khung thời gian thực tế đó.Nếu
exerciseMetadata.hasGpslàtrue, hãy gọiexportExerciseTcxđể tải toạ độ tuyến đường xuống.