Tworzenie funkcji związanych z treningiem za pomocą interfejsu Google Health API

Interfejs Google Health API śledzi sesje treningowe i historię ćwiczeń użytkownika, korzystając z typu danych sesji exercise. Sesja działa jak kontener, który grupuje metadane aktywności, zdarzenia wstrzymania i wznowienia, okrążenia lub odcinki oraz dane podsumowujące.

Dowiedz się, jak odczytywać, zapisywać i strukturyzować treningi w aplikacji, aby zapewnić użytkownikom jak najlepsze wrażenia.

Obsługiwane typy danych

Interfejs API obsługuje ten typ danych do śledzenia treningów i sesji aktywności:

Tabela: typy danych treningów w Google Health API
Typ danych Dostępne operacje
Zakres
Ćwiczenia
dataType: exercise
filter parameter: exercise
Typ rekordu: sesja

Zgodne urządzenia

list, get, reconcile, create, update, batchDelete .activity_and_fitness.readonly
.activity_and_fitness.writeonly

Sesje treningowe używają typu danych exercise jako kontenera, ale urządzenia do noszenia rejestrują też podczas sesji szczegółowe dane telemetryczne o wysokiej częstotliwości. W interfejsie Google Health API te szczegółowe typy danych telemetrycznych z całego dnia są tylko do odczytu i nie można ich tworzyć ani modyfikować bezpośrednio za pomocą ich własnych punktów końcowych REST. Podczas zapisywania sesji treningowej za pomocą interfejsu REST API przekazuj zbiorcze dane treningowe w obiekcie metricsSummary punktu danych exercise.

W tabeli poniżej znajdziesz mapowanie pól podsumowania w exercise.metricsSummary na odpowiadające im dane telemetryczne z danego dnia, które są tylko do odczytu i które możesz wyszukiwać w przedziale czasu danego treningu:

Pole podsumowania (metricsSummary) Nazwa typu danych telemetrycznych zbieranych w ciągu dnia Identyfikator typu danych telemetrycznych interfejsu API (tylko do odczytu) Pole filtra (?filter=) Wymagany zakres protokołu OAuth do odczytu
caloriesKcal Kalorie spalone aktywnie active-energy-burned active_energy_burned.interval.start_time activity_and_fitness.readonly
distanceMillimeters Odległość distance distance.interval.start_time activity_and_fitness.readonly
steps Kroki steps steps.interval.start_time activity_and_fitness.readonly
averageHeartRateBeatsPerMinute tętno heart-rate heart_rate.sample_time.physical_time health_metrics_and_measurements.readonly
activeZoneMinutes Aktywne minuty w strefie active-zone-minutes active_zone_minutes.interval.start_time activity_and_fitness.readonly

W poniższych sekcjach znajdziesz szczegóły techniczne dotyczące typu danych exercise, w tym przykłady reprezentacji REST, obsługę tras GPS i wytyczne dotyczące integracji.

Sesje treningowe

Zapisuj codzienne aktywności lub treningi jako punkty danych sesji exercise. Każdy punkt danych opisuje całą sesję, zawiera szczegółowe informacje o interwałach zdarzeń (takich jak wstrzymanie i wznowienie) oraz podaje dane podsumowujące (takie jak łączny dystans, liczba kroków i średnie tętno).

Atrybuty sesji

Podczas tworzenia punktu danych dotyczących ćwiczeń sprawdź te podstawowe komponenty:

  • Czas sesji (interval): czas rozpoczęcia i zakończenia całej sesji treningowej wraz z przesunięciami strefy czasowej aktywnymi w tych momentach.
  • Typ aktywności (exerciseType): kategoria wykonywanej aktywności (np. RUNNING, WALKING, BIKING lub AEROBIC_WORKOUT). Określ dokładny typ treningu fizycznego.
  • Wyświetlana nazwa (displayName): przyjazna dla użytkownika nazwa sesji treningowej. Gdy utworzysz go za pomocą interfejsu API REST, serwer wypełni zlokalizowaną wyświetlaną nazwę dla exerciseType, np. "Run" dla RUNNING.
  • Czas aktywności (activeDuration): rzeczywisty czas aktywności podczas treningu, z wyłączeniem wstrzymanych interwałów. Standardowe formatowanie używa formatu Duration (np. "1800s"). Na serwerze activeDuration jest obliczany na podstawie interval sesji pomniejszonego o interwały PAUSE/RESUME lub AUTO_PAUSE/AUTO_RESUME w exerciseEvents.

Wskaźniki podsumowujące

Zagnieżdżony obiekt metricsSummary zawiera dane sumaryczne i średnie obliczone dla całego czasu trwania sesji ćwiczeń:

  • caloriesKcal: łączna liczba aktywnych spalonych kalorii podczas treningu, mierzona w kilokaloriach (kcal).
  • distanceMillimeters: łączny pokonany dystans mierzony w milimetrach, aby zachować wysoką precyzję we wszystkich jednostkach.
  • steps: łączna liczba kroków zrobionych podczas ćwiczenia.
  • averageHeartRateBeatsPerMinute: średnie tętno użytkownika podczas aktywnych minut sesji.
  • activeZoneMinutes: łączne aktywne minuty w strefie zdobyte podczas treningu.
  • averageSpeedMillimetersPerSecond: średnia szybkość ruchu w milimetrach na sekundę.
  • averagePaceSecondsPerMeter: średnie tempo podczas aktywnych minut sesji, mierzone w sekundach na metr.
  • elevationGainMillimeters: łączne przebyte przewyższenie podczas sesji.

Etapy i odcinki

W przypadku treningów obejmujących okrążenia (takich jak bieganie na bieżni czy pływanie w basenie) zsynchronizowanych z obsługiwanych urządzeń splitSummaries dzieli sesję na okrążenia lub odcinki.

Każdy podział zawiera:

  • Określony startTime i endTime.
  • activeDuration reprezentujący rzeczywisty czas okrążenia.
  • metricsSummary, którego zakres jest ograniczony tylko do tego segmentu.
  • splitType, aby określić granice podziału (np. DISTANCE, DURATION lub MANUAL).

ćwiczenia,

Aby dokładnie obliczyć czas aktywności, śledź zmiany stanu (np. zdarzenia ręcznego lub automatycznego wstrzymania) za pomocą exerciseEvents.

Każde zdarzenie zawiera sygnaturę czasową (eventTime) i typ:

  • START / STOP: wskazuje sygnatury czasowe rozpoczęcia lub zakończenia nagrywania przez użytkownika.
  • PAUSE / RESUME: wskazuje, kiedy sesja została ręcznie wstrzymana lub wznowiona.
  • AUTO_PAUSE / AUTO_RESUME: wskazuje automatyczne wstrzymanie/wznowienie na podstawie danych z czujników.

Zapisywanie sesji treningowej

Aby utworzyć, zaktualizować lub zaimportować sesję treningową, zapisz punkt danych w kolekcji typu danych exercise. Użyj punktu końcowego create dataPoints.

Przykład reprezentacji REST

Poniższy przykład pokazuje, jak zapisać sesję treningową za pomocą metody POST:

Żądanie

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"
      }
    ]
  }
}

Odpowiedź

{
  "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"
    }
  }
}

Trasy GPS i śledzenie lokalizacji

Interfejs API zapisuje podstawowe podsumowania sesji bezpośrednio w punkcie danych exercise, ale szczegółową historię lokalizacji i współrzędne trasy GPS obsługuje jako osobny strumień.

Aby pobrać szczegółowe dane o trasie sesji na świeżym powietrzu, wywołaj metodę niestandardową exportExerciseTcx. Ten punkt końcowy zwraca trasę w standardowym formacie Training Center XML (TCX).

Eksportowanie trasy GPS

Żądanie

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints/exercise-data-point-id:exportExerciseTcx?alt=media
Authorization: Bearer access-token

Odpowiedź

Ładunek HTTP z Content-Type: application/tcx+xml i nagłówkami, które instruują przeglądarkę, aby zapisała plik.

<?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>

Wymagane zakresy i lokalizacja

Aby korzystać z funkcji śledzenia tras GPS i lokalizacji, aplikacja musi prosić o te zakresy OAuth:

  • Odczyt: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Zapis: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Odczyt: https://www.googleapis.com/auth/googlehealth.location.readonly

Wytyczne

Podczas integrowania śledzenia treningów z aplikacją postępuj zgodnie z tymi wytycznymi dotyczącymi projektowania i wdrażania.

Czas aktywności a łączny czas trwania

Aby obliczyć dane dotyczące szybkości lub tempa, zawsze używaj activeDuration, a nie różnicy między startTime i endTime. Zapobiega to zniekształcaniu danych przez wstrzymane interwały.

Jeśli na przykład użytkownik rozpocznie trening o 8:00 i zakończy go o 8:35, łączny czas trwania treningu wyniesie 2100 sekund. Jeśli użytkownik wstrzymał trening na 5 minut (300 sekund), a w exerciseEvents uwzględnisz zdarzenia PAUSE i RESUME, czas aktywności wyniesie "1800s" (2100 – 300). Interfejs API używa aktywnego czasu trwania do obliczania średnich, dzieląc łączny dystans przez 1800 sekund zamiast przez 2100.

Obliczanie prędkości i tempa

Interfejs Google Health API oblicza prędkość i tempo za pomocą standardowych wzorów:

  • Prędkość = distance / time(hour)
  • Tempo = time(seconds) / distance

Nagłówek Accept-Language określony w żądaniu określa jednostkę odległości.

Wcześniejsze wysyłanie prośby o dostęp do lokalizacji

Jeśli Twoja aplikacja mapuje trasy treningowe, poproś o uprawnienia dostępu do lokalizacji i zakres Google Health location oprócz zakresu aktywności i kondycji. Wyjaśnij użytkownikom, dlaczego Twoja aplikacja wymaga zakresu lokalizacji podczas sprawdzania ćwiczeń z GPS-em.

Gdy aplikacja prosi o zakres lokalizacji (https://www.googleapis.com/auth/googlehealth.location.readonly), Google OAuth wyświetla użytkownikowi prośbę o zgodę. Wyjaśnij użytkownikom, że to uprawnienie jest niezbędne do renderowania nakładek tras i eksportowania plików śledzenia GPS (TCX). Jeśli użytkownik przyzna uprawnienia do aktywności, ale odmówi dostępu do lokalizacji, exportExerciseTcx zwróci błąd autoryzacji, ale nadal będziesz mieć dostęp do danych zbiorczych sesji w metricsSummary.

Synchronizacja za pomocą webhooków

Zasubskrybuj typ danych exercise, aby powiadamiać backend za pomocą webhooków, gdy pojawią się nowe dane dotyczące treningu. Dzięki temu możesz automatycznie wywoływać działania po treningu.

Gdy serwer otrzyma powiadomienie webhooka, zawiera ono identyfikator healthUserId i przedział czasu cywilnego (civilIso8601TimeInterval) zaktualizowanego treningu. Serwer powinien natychmiast potwierdzić powiadomienie za pomocą 204 No Content, przetworzyć ładunek asynchronicznie i wysłać zapytanie do uzgodnionego punktu końcowego exercise za pomocą filtra exercise.interval.civil_start_time (pamiętaj, że exercise obsługuje tylko filtrowanie według 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"

Szczegółowe informacje o konfigurowaniu subskrypcji znajdziesz w artykule Subskrypcje webhooków.

Utrzymywanie spójnych danych

Aby zapewnić pełne informacje o treningu, podczas zapisywania sesji exercise uwzględniaj dane podsumowujące, a podczas renderowania wykresów szczegółowych wysyłaj zapytania do punktów końcowych telemetrii tylko do odczytu, używając filtrów zakresu czasu.

Zapisywanie danych podsumowania treningu (ścieżka zapisu)

Podczas importowania lub zapisywania ukończonego treningu w interfejsie Google Health API uwzględnij zbiorcze dane telemetryczne treningu (steps, caloriesKcal, distanceMillimeters, averageHeartRateBeatsPerMinute i averagePaceSecondsPerMeter) w obiekcie metricsSummary punktu danych exercise:

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

wykonywanie zapytań o szczegółowe dane na potrzeby wykresów (ścieżka odczytu),

Aby utworzyć panele lub wykresy treningu dla konkretnej sesji, wyślij zapytanie do uzgodnionych punktów końcowych telemetrii w przedziale czasu tego treningu:

  1. Pobierz sesję treningową z punktu końcowego exercise, używając filtra civil_start_time, aby uzyskać wartości interval i 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. Użyj wartości interval.startTime i interval.endTime sesji, aby wysłać zapytanie do punktów końcowych telemetrii w tym przedziale czasu.

  3. Jeśli exerciseMetadata.hasGps to true, wywołaj exportExerciseTcx, aby pobrać współrzędne trasy.