Phát triển trải nghiệm tập luyện bằng Google Health API

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:

Bảng: Các kiểu dữ liệu về bài tập thể dục trong Google Health API
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: exercise
filter 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

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, BIKING hoặc AEROBIC_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á cho exerciseType, chẳng hạn như "Run" cho RUNNING.
  • 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ạng Duration (ví dụ: "1800s"). Trên máy chủ, activeDuration được tính từ phiên interval trừ đi mọi khoảng thời gian PAUSE/RESUME hoặc AUTO_PAUSE/AUTO_RESUME trong exerciseEvents.

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:

  • startTime và endTime cụ thể.
  • activeDuration biểu thị thời gian thực tế của vòng đua.
  • metricsSummary chỉ 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, DURATION hoặc MANUAL).

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 đó:

  1. Tìm nạp buổi tập thể dục từ điểm cuối exercise bằng bộ lọc civil_start_time để lấy interval và 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. Sử dụng interval.startTime và interval.endTime của phiên để truy vấn các điểm cuối đo từ xa cho khung thời gian thực tế đó.

  3. Nếu exerciseMetadata.hasGps là true, hãy gọi exportExerciseTcx để tải toạ độ tuyến đường xuống.