Typy danych interfejsu API Google Health

Poniższa tabela zawiera pełną listę typów danych z kilkoma kolumnami, które pomogą Ci zrozumieć reprezentację każdego typu w interfejsie Google Health API, a także zakres, w jakim jest on dostępny.

Ważne: format identyfikatorów typów danych różni się, gdy typ danych składa się z więcej niż jednego słowa. W punkcie końcowym nazwa typu danych musi być zapisana w formacie kebab-case, np. body-fat. W parametrze filtra nazwa typu danych musi być jednak zapisana w formacie snake case, np. body_fat.

Tabela. Typy danych interfejsu Google Health API

Typ danych   dataType   filter parameter	Record type	Dostępne operacje	Zakres	Webhook support	Obsługa wartości zerowych
Spalone kalorie podczas aktywności   active-energy-burned   active_energy_burned	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Aktywne minuty   active-minutes   active_minutes	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Aktywne minuty w strefie   active-zone-minutes   active_zone_minutes	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Poziom aktywności   activity-level   activity_level	Interwał	lista, uzgadnianie	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Wysokość   altitude   altitude	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Glukoza we krwi   blood-glucose   blood_glucose	Przykład	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Tkanka tłuszczowa   body-fat   body_fat	Przykład	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Kalorie w strefie tętna   calories-in-heart-rate-zone   calories_in_heart_rate_zone	Interwał	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Temperatura ciała   core-body-temperature   core_body_temperature	Przykład	list, get, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Codzienna zmienność rytmu serca   daily-heart-rate-variability   daily_heart_rate_variability	Codziennie	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Dzienne strefy tętna   daily-heart-rate-zones   daily_heart_rate_zones	Codziennie	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Codzienne nasycenie tlenem   daily-oxygen-saturation   daily_oxygen_saturation	Codziennie	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Dzienna częstość oddechów   daily-respiratory-rate   daily_respiratory_rate	Codziennie	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Dzienne tętno spoczynkowe   daily-resting-heart-rate   daily_resting_heart_rate	Codziennie	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Codzienne wyliczenia temperatury snu   daily-sleep-temperature-derivations   daily_sleep_temperature_derivations	Codziennie	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Dzienny pułap tlenowy   daily-vo2-max   daily_vo2_max	Codziennie	lista, uzgadnianie	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Odległość   distance   distance	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Elektrokardiogram (EKG)   electrocardiogram   electrocardiogram	Sesja	lista	.ecg.readonly
Ćwiczenia   exercise   exercise	Sesja	list, get, reconcile, create, update, batchDelete	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Piętra   floors   floors	Interwał	reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Jedzenie   food   food	Jedzenie	list, get	.nutrition.readonly .nutrition.writeonly
Jednostka miary żywności   food-measurement-unit   food_measurement_unit	Jedzenie	list, get	.nutrition.readonly .nutrition.writeonly
Tętno   heart-rate   heart_rate	Przykład	list, reconcile, rollup, dailyRollup	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Zmienność rytmu serca   heart-rate-variability   heart_rate_variability	Przykład	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Wysokość   height   height	Przykład	list, get, reconcile, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Zapis nawodnienia   hydration-log   hydration_log	Sesja	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
Powiadomienie o nieregularnym rytmie serca   irregular-rhythm-notification   irregular_rhythm_notification	Sesja	lista	.irn.readonly
Okres   menstrual-period   menstrual_period	Interwał	create, update, batchDelete	.reproductive_health.writeonly
Nastroje   moods   moods	Przykład	create, update, batchDelete	.mindfulness.writeonly
Dziennik odżywiania   nutrition-log   nutrition_log	Przykład	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
Test owulacyjny   ovulation-test   ovulation_test	Przykład	create, update, batchDelete	.reproductive_health.writeonly
Nasycenie tlenem   oxygen-saturation   oxygen_saturation	Przykład	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Podsumowanie snu dotyczące częstości oddechów   respiratory-rate-sleep-summary   respiratory_rate_sleep_summary	Przykład	lista, uzgadnianie	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly
Pułap tlenowy podczas biegu   run-vo2-max   run_vo2_max	Przykład	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Okres braku aktywności   sedentary-period   sedentary_period	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Sen   sleep   sleep	Sesja	list, get, reconcile, create, update, batchDelete	.sleep.readonly .sleep.writeonly
Kroki   steps   steps	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Dane o długościach pływania   swim-lengths-data   swim_lengths_data	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Objawy   symptoms   symptoms	Przykład	create, update, batchDelete	.logged_symptoms.writeonly
Czas w strefie tętna   time-in-heart-rate-zone   time_in_heart_rate_zone	Interwał	list, reconcile, rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Wszystkie kalorie   total-calories   total_calories	Interwał	rollup, dailyRollup	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Maksymalny pułap tlenowy VO2   vo2-max   vo2_max	Przykład	lista, uzgadnianie	.activity_and_fitness.readonly .activity_and_fitness.writeonly
Waga   weight   weight	Przykład	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.health_metrics_and_measurements.readonly .health_metrics_and_measurements.writeonly

Ograniczenia zapytań

Podczas wysyłania zapytań do interfejsu API o punkty danych, zbiorcze dane lub dzienne zbiorcze dane pamiętaj o tych ograniczeniach:

• Wymagania dotyczące filtra: niektóre typy danych pochodnych tylko do odczytu, np. total-calories, wymagają filtra określającego czas rozpoczęcia interwału (z użyciem czasu fizycznego lub cywilnego).
• Limity zakresu zapytań: maksymalny zakres zapytań w przypadku calories-in-heart-rate-zone, heart-rate, active-minutes i total-calories wynosi 14 dni. Maksymalny zakres zapytań w przypadku wszystkich innych typów danych wynosi 90 dni.

Dostępność danych

Aktualizacje danych użytkownika są dostępne dopiero po zsynchronizowaniu przez niego trackera aktywności lub ręcznym wprowadzeniu nowych danych w aplikacji mobilnej lub internetowej Fitbit. Urządzenie Fitbit i aplikacja mobilna Fitbit mogą automatycznie synchronizować dane co 15 minut, gdy aplikacja Fitbit jest otwarta na urządzeniu mobilnym, a oba urządzenia mają aktywne połączenie do transmisji danych i znajdują się w zasięgu Bluetooth. Jeśli użytkownik śledzi aktywność za pomocą MobileTrack, synchronizacja MobileTrack odbywa się co godzinę, o ile aplikacja jest otwarta.

Pobieranie danych historycznych

Jedną z głównych korzyści interfejsu Google Health API jest możliwość śledzenia wyników użytkownika i monitorowania jego parametrów życiowych przez długi czas. Możesz wysyłać zapytania o dane użytkownika z dowolnego okresu, w którym były one rejestrowane. Interfejs API nie nakłada żadnych ograniczeń na ilość danych historycznych, które może wykorzystywać Twoja aplikacja.

Wykonywanie zapytań dotyczących danych historycznych podlega jednak standardowym limitom częstotliwości. Aby zmniejszyć liczbę wywołań interfejsu API w stosunku do tych limitów, interfejs Google Health API obsługuje wysyłanie zapytań o dane w określonym zakresie dat. Pamiętaj o tych ograniczeniach dotyczących paginacji i żądania:

• Każdy punkt końcowy zwraca maksymalny rozmiar strony wynoszący 10 000 punktów danych na stronę.
• Zakresy dat zapytań są ograniczone do 14–90 dni na żądanie.

W zależności od ilości danych historycznych potrzebnych aplikacji pobranie całego zbioru danych może wymagać wielu kolejnych żądań i zająć więcej czasu. Pamiętaj o tym podczas projektowania procesu synchronizacji danych w aplikacji.

Aby zapewnić optymalną skuteczność i uniknąć błędów interfejsu API, podczas wysyłania zapytań o dane historyczne postępuj zgodnie z tymi wytycznymi:

Stopniowa synchronizacja danych (szybkie ładowanie a wczytywanie „na zimno”)

• Początkowe wczytywanie „na gorąco”: podczas głównej sekwencji wczytywania pobieraj i renderuj tylko dane z ostatnich 7–14 dni. Dzięki temu użytkownicy od razu widzą dane i nie muszą czekać na długotrwałe zapytania.
• Wczytywanie „na zimno” w tle: przekazywanie starszych danych historycznych do asynchronicznej kolejki o niższym priorytecie lub procesu w tle po wyrenderowaniu głównego interfejsu.

Dzielenie zapytań na części na podstawie czasu

• Nie wysyłaj w jednym wywołaniu interfejsu API żądań dotyczących okresów wieloletnich lub wielomiesięcznych. Podziel duże zapytania historyczne na mniejsze, kolejne przedziały (np. 1 tydzień na żądanie).
• Bezpiecznie grupuj lub sekwencjonuj te zapytania, aby zachować limity współbieżności i utrzymywać stałe wskaźniki postępu interfejsu.

Korzystanie z wstępnie zagregowanych podsumowań

Zmień strukturę paneli ogólnych i wykresów trendów, aby korzystać z wstępnie zagregowanych punktów końcowych podsumowania (np. DailyRollUpDataPoints). Znacznie zmniejszy to obciążenie obliczeniowe backendu i czas przesyłania danych do klienta.

Odporna obsługa błędów (inteligentne ponawianie)

• W przypadku napotkania ograniczania liczby żądań (429 Too Many Requests) i limitów czasu bramy serwera (504 Gateway Timeout) wdróż ścisłe wzrastający czas do ponowienia. Nigdy nie ponawiaj od razu prób wysyłania dużych, nieudanych ładunków. Natychmiastowe ponawianie prób zwiększa przeciążenie backendu i pogarsza działanie systemu.
• Jeśli zapytanie wielokrotnie przekracza limit czasu, automatycznie przełącz się na mniejsze okno czasowe (np. zmniejsz 1-tygodniowy przedział do 3 dni).

Ostrzeżenie: nieprzestrzeganie tych wytycznych może powodować nieoczekiwane zachowania i błędy.

Dostęp aplikacji zewnętrznych

Urządzenia Fitbit nie mogą komunikować się bezpośrednio z aplikacjami ani usługami innych firm. Te urządzenia są przeznaczone do komunikacji i synchronizacji wyłącznie z aplikacją mobilną Fitbit.

Urządzenie synchronizuje dane automatycznie przez cały dzień, gdy aplikacja Fitbit jest otwarta, lub co 15 minut, jeśli Bluetooth jest aktywny, a aplikacja działa w tle. Po zakończeniu procesu synchronizacji dane są udostępniane usługom innych firm za pomocą interfejsu Google Health API.

Standardy odległości

Odległości ćwiczeń, np. elevationGainMillimeters, są mierzone w milimetrach jako standardowej jednostce z tych powodów:

1. Zachowanie precyzji danych: najważniejszym powodem używania milimetrów jest zapewnienie, że nie utracimy precyzji danych, które odczytujemy i udostępniamy. Używanie precyzyjnej jednostki, takiej jak milimetry, pozwala nam przedstawiać pomiary z dużą dokładnością.
2. Standaryzacja: milimetry są standardową jednostką miary w naszych usługach. Ta spójność zapewnia deweloperom jednolite wrażenia podczas korzystania z różnych części interfejsu API.
3. Szerokie wsparcie dla systemów pomiarowych: używanie jednostki podstawowej, takiej jak milimetry, ułatwia programistom przeliczanie na dowolną inną wybraną jednostkę, niezależnie od tego, czy pracują w systemie metrycznym, imperialnym czy innym.

Zmienna długość dnia

Interfejs Health API traktuje czas priorytetowo, aby uwzględniać czas użytkownika i zmienną długość dnia spowodowaną zmianą czasu lub podróżą. Każdy punkt danych jest przechowywany z fizyczną sygnaturą czasową UTC i odchyleniem od czasu UTC aktywnym w momencie zdarzenia. Dzięki temu system może:

• Przypisz zdarzenie do dokładnego momentu w czasie.
• Skoryguj czas do lokalnego kontekstu użytkownika na potrzeby agregacji.

Czas letni

Gdy następuje zmiana czasu na zimowy, dzień kalendarzowy trwa 25 godzin, a podsumowanie za ten dzień zawiera dane z 25 godzin. „Przesunięcie czasu do przodu” powoduje, że dzień trwa 23 godziny, a czas wraca do czasu standardowego.

Podróże

Podróżowanie między strefami czasowymi może powodować jeszcze większe różnice w fizycznym czasie trwania jednego dnia kalendarzowego.

Użyj punktu końcowego dailyRollUp, aby uwzględnić różnice w strefach czasowych. Automatycznie przypisuje dane do dnia kalendarzowego, w którym zostały zarejestrowane, zgodnie z czasem lokalnym użytkownika, skutecznie „łącząc” dzień pomimo zmian stref czasowych.