Zarządzanie danymi w interfejsie Google Health API

Praca z danymi w interfejsie Google Health API to w zasadzie cykl synchronizacji danych między magazynem danych interfejsu Google Health API w chmurze a Twoją aplikacją lub magazynem danych backendu. Jednak ten cykl może przybierać różne formy w zależności od wielu czynników:

  • Czy zapisujesz dane w interfejsie Google Health API? Tylko czytanie? A może i to, i to?
  • Czy magazyn danych znajduje się lokalnie w aplikacji lub na urządzeniu? A może we własnej chmurze?
  • Czy musisz synchronizować dane z interfejsu Google Health API między aplikacją użytkownika a urządzeniem do noszenia? Jak często synchronizujesz urządzenia?
  • Z jakimi typami danych pracujesz? Podstawowe liczby? Jednostki miary? Seria z różnymi częstotliwościami próbkowania?
  • Czy planujesz odczytywać dane, gdy aplikacja działa w tle?
  • Czy planujesz pracować z danymi historycznymi zarejestrowanymi, zanim aplikacja uzyskała zgodę użytkownika?

Aby dowiedzieć się, jak to wszystko działa, zapoznaj się z cyklem synchronizacji interfejsu Google Health API. Istnieją 2 wersje tego cyklu życia: standardowa (odczyt i zapis) oraz tylko do odczytu.

Standardowy cykl życia synchronizacji

Cykl życia standardowej synchronizacji w interfejsie Google Health API
Rysunek 1. Standardowy cykl życia synchronizacji w interfejsie Google Health API

Integracja z interfejsem Google Health API oznacza kopiowanie danych do aplikacji lub magazynu danych backendu. W tej dokumentacji dla ułatwienia będziemy nazywać ten magazyn danych magazynem danych dewelopera.

„Kopiowanie” może tu zastąpić dowolne działanie, takie jak odczytywanie z interfejsu Google Health API (kopiowanie do magazynu danych dewelopera) lub zapisywanie w interfejsie Google Health API (kopiowanie do interfejsu Google Health API). Wielokrotne wykonywanie tych czynności w określonej kolejności to cykl życia synchronizacji.

Rysunek 1 przedstawia standardowy cykl życia synchronizacji, który obejmuje operacje odczytu i zapisu, bez uwzględnienia żadnego z wcześniej wymienionych czynników.

Zapis

  1. Przygotowywanie nowych danych do zapisu – przenoszenie danych z urządzenia lub aplikacji zewnętrznej i formatowanie punktów danych do reprezentacji JSON zgodnych z typami danych interfejsu Google Health API. Pamiętaj, że niestandardowe identyfikatory przypisane przez klienta do zapisu nie są obecnie obsługiwane w interfejsie Health API. Takie identyfikatory mogą być podane w POST, ale są ignorowane.
  2. Przesyłanie rekordów – przesyłaj punkty danych do interfejsu Google Health API za pomocą punktów końcowych REST. Użyj POST, aby utworzyć rekordy, i PATCH, aby zaktualizować istniejące rekordy. Identyfikatory potrzebne do operacji PATCH pochodzą z poprzedniej operacji POST (następny krok w poprzednim cyklu).
  3. Przetwarzanie zwróconych identyfikatorów zasobów – jeśli używasz identyfikatorów generowanych przez serwer, wyodrębnij i zapisz zwrócony przez serwer zasób name lub identyfikator w magazynie danych dewelopera, aby umożliwić przyszłe aktualizacje (PATCH) lub usunięcia. Więcej informacji o obu typach znajdziesz w artykule Strategie identyfikacji.

Odczyt

  1. Odczytywanie rekordów – pobieraj nowe dane i zmiany w istniejących danych z interfejsu Google Health API za pomocą punktów końcowych REST (GET z parametrami zapytania filter i paginacją pageToken lub punktami końcowymi agregacji, takimi jak rollUp i dailyRollUp) lub otrzymuj powiadomienia za pomocą subskrypcji webhooków (projects.subscribers). Powiadomienie wskazuje tylko, że dostępne są nowe dane, a nie jakie to dane.
  2. Uzgodnij magazyn danych dewelopera – uzgodnij nowe i zaktualizowane dane z magazynem danych dewelopera. Połączone urządzenia mogą generować nakładające się interwały podczas synchronizacji. Aby dowiedzieć się, jak interfejs Google Health API rozwiązuje te problemy, zapoznaj się z artykułem Sygnatury czasowe interwałów i synchronizacja połączonych urządzeń.

Ten cykl powtarza się w odpowiednich odstępach czasu, zgodnie z potrzebami konkretnych urządzeń lub aplikacji zewnętrznych. Zasadniczo zalecamy taką kolejność synchronizowania danych między własnym magazynem danych a interfejsem Google Health API.

Strategie identyfikacji

Jeśli chcesz zapisywać dane w interfejsie Google Health API, przed utworzeniem integracji z interfejsami Google Health API musisz wybrać strategię identyfikacji zasobów podczas tworzenia punktów danych (podstawowej jednostki danych).

Identyfikatory przypisane przez klienta do zapisu nie są obecnie obsługiwane w interfejsie Health API. Takie identyfikatory mogą być podane w elemencie POST, ale są ignorowane. Szczegóły dotyczące tej opcji podajemy wyłącznie w celach informacyjnych.

  1. Identyfikatory generowane przez serwer (opcja domyślna): klient przesyła dane bez identyfikatora, a backend interfejsu Google Health API generuje i zwraca unikalny identyfikator systemowy.
  2. Identyfikatory niestandardowe przypisane przez klienta (zgodnie z AIP-133, jeszcze nieobsługiwane): aplikacja kliencka generuje unikalny identyfikator (np. UUID lub klucz podstawowy lokalnej bazy danych) i podaje go w ścieżce zasobu podczas tworzenia.

W tabeli poniżej porównujemy obie strategie identyfikacji, aby pomóc Ci wybrać odpowiednie podejście do integracji:

Funkcja Identyfikatory generowane przez serwer Identyfikatory niestandardowe przypisane przez klienta
Generowanie identyfikatorów Serwer generuje losowy identyfikator systemu podczas wykonywania POST. Klient generuje stabilny identyfikator lokalnie (UUID v4 / wewnętrzny klucz podstawowy) przed zapisem.
Ścieżka zasobu .../dataPoints/{server_id} (zwracany w odpowiedzi) .../dataPoints/{custom_id}
Krok lokalny po zapisie Parametr wymagany. Zwrócony obiekt server_id musi być przechowywany w lokalnej bazie danych, aby umożliwić przyszłe aktualizacje i usunięcia. Brak. Aplikacja ma już ten identyfikator.
Tabela mapowania identyfikatorów Parametr wymagany. Klient musi utrzymywać mapowanie dwukierunkowe (local_id ↔ server_id). Nie jest to konieczne. Klient używa bezpośrednio własnego klucza podstawowego.
Zachowanie ponownej próby (słaba sieć) Ryzyko duplikatów. Ponowna próba wykonania operacji POST, która przekroczyła limit czasu, powoduje utworzenie zduplikowanego rekordu z nowym identyfikatorem serwera. Bezpieczne i idempotentne Ponowna próba wykonania POST z tym samym custom_id zapobiega tworzeniu duplikatów (zwraca 409 ALREADY_EXISTS).
Obsługa synchronizacji offline Ograniczone. Przed odwołaniem się do oficjalnych identyfikatorów zasobów musisz poczekać na odpowiedź serwera, aby je uzyskać. Pełny Encje można tworzyć i modyfikować offline za pomocą stabilnych identyfikatorów, a następnie bezproblemowo synchronizować po ponownym połączeniu.
Ograniczenia formatu Obsługiwane w całości przez serwer. Musi być zgodna z ^[a-z0-9-]{4,63}$ (4–63 małe znaki alfanumeryczne i łączniki).
Kiedy wybrać

Wybierz identyfikatory generowane przez serwer, jeśli:

  • Aplikacja jest przeznaczona tylko do zapisu lub dołączania (np. wysyła dane telemetryczne lub liczbę kroków, które nie są później aktualizowane ani usuwane).
  • Aplikacja nie przechowuje lokalnej stałej bazy danych z poszczególnymi punktami danych.
  • Wolisz prostotę bez zarządzania ograniczeniami weryfikacji ciągów znaków (takimi jak 4-63 znaki).

Wybierz identyfikatory niestandardowe, jeśli:

  • Obsługujesz aplikację do synchronizacji dwukierunkowej, która odczytuje, zapisuje i aktualizuje dane o stanie zdrowia na różnych urządzeniach.
  • Twoja aplikacja ma lokalną bazę danych (np. Room lub SQLite), w której są przechowywane rekordy z lokalnymi kluczami podstawowymi.
  • Użytkownicy rejestrują dane offline lub przez przerywane połączenia komórkowe, gdy konieczne są bezpieczne ponowne próby.
  • Chcesz wyeliminować tabele mapowania identyfikatorów między bazą danych backendu a interfejsem API.

Cykl życia synchronizacji tylko do odczytu

Cykl życia synchronizacji tylko do odczytu w interfejsie Google Health API
Rysunek 2. Cykl życia synchronizacji tylko do odczytu w interfejsie Google Health API

Aplikacja, która ma tylko odczytywać dane z interfejsu API Google Health, musi kopiować dane do magazynu danych dewelopera i obsługiwać część cyklu życia związaną z uzgadnianiem.

W tym przypadku obowiązują te same zadania, które opisano w sekcji Odczyt.

Rysunek 2 przedstawia cykl życia tylko do odczytu.

sygnatury czasowe interwałów i synchronizacja połączonych urządzeń,

Dane interwałowe to pomiary zebrane w określonym czasie, np. liczba kroków, tętno czy sesje ćwiczeń. Z kolei pomiary punktowe obejmują wpisy ręczne, takie jak dziennik żywienia czy odczyt z wagi. Dane interwałowe zwykle pochodzą z synchronizacji połączonych urządzeń, takich jak zegarki i trackery aktywności.

Sygnatury czasowe interwałów (startTime i endTime w ładunkach JSON REST lub start_time i end_time w wyrażeniach filtrów i gRPC) wprowadzają unikalne zachowania podczas pracy z danymi interwałów. W tej sekcji wyjaśniamy, dlaczego występują nakładające się interwały, i porównujemy punkty końcowe list i reconcile.

Pokrywające się interwały z połączonych urządzeń

Połączone urządzenia, takie jak trackery Fitbit i zegarki Google Pixel Watch, stale zbierają odczyty biometryczne o wysokiej częstotliwości, gdy są noszone. Gdy urządzenie zsynchronizuje punkty danych z Google Health, nie zmieni wstecznie istniejących rekordów. Zapisane sygnatury czasowe interwałów pozostają bez zmian.

Jednak przed kolejnymi cyklami synchronizacji algorytmy na urządzeniu często ponownie interpretują nieprzetworzone dane telemetryczne z czujników. Urządzenie ponownie grupuje odczyty zebrane w ciągu poprzednich godzin. Gdy urządzenie ponownie się zsynchronizuje, prześle nowe punkty danych. Ich granice początku i końca mogą nakładać się na wcześniej zapisane interwały.

Załóżmy na przykład, że użytkownik nosi zegarek, którego dane o aktywności są synchronizowane w 2 kolejnych partiach:

  1. Podczas pierwszej synchronizacji urządzenie przesyła punkt danych obejmujący okres od 10:00:00Z do 10:14:59Z.
  2. Po ponownym przeliczeniu na urządzeniu druga synchronizacja przesyła kolejny punkt danych obejmujący okres od 10:14:00Z do 10:28:59Z.

Oba rekordy są przechowywane niezależnie w backendzie Google Health. W efekcie oba punkty danych obejmują przedział czasu od 10:14:00Z do 10:14:59Z. Podczas wysyłania zapytań o nieprzetworzone rekordy powoduje to 59-sekundowe nakładanie się.

Porównaj listę i uzgodnij punkty końcowe

Te nakładające się interwały możesz obsłużyć za pomocą punktu końcowego list lub reconcile. Wybierz punkt końcowy, który odpowiada wymaganiom Twojej aplikacji:

Funkcja list punkt końcowy reconcile punkt końcowy
Metoda HTTP GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile
Zachowanie w przypadku nakładania się Zwraca wszystkie zapisane rekordy w postaci, w jakiej zostały przesłane, bez deduplikacji. Jeśli interwały się nakładają, zwracane są oba rekordy. Rozwiązuje konflikty i usuwa duplikaty nakładających się rekordów na urządzeniach i w sesjach synchronizacji, tworząc jeden ciągły strumień.
Zalety Zapewnia pełny, niezmieniony rejestr kontrolny każdego rekordu przesłanego przez każde urządzenie i każdą partię synchronizacji. Upraszcza renderowanie osi czasu i obliczanie czasu trwania dzięki automatycznemu rozwiązywaniu konfliktów związanych z nakładającymi się interwałami i na wiele urządzeń.
Wady Aplikacja odpowiada za wykrywanie i rozwiązywanie problemów z nakładającymi się interwałami, konfliktami między wieloma urządzeniami i okresami, gdy urządzenie nie jest noszone na nadgarstku. Podrzędne nakładające się rekordy są pomijane w odpowiedzi, więc nie można sprawdzać poszczególnych partii synchronizacji urządzeń w izolacji.

Punkt końcowy reconcile jest przeznaczony do rysowania interfejsów użytkownika, renderowania osi czasu aktywności i obliczania sum czasu trwania, które nie nakładają się na siebie. Rozwiązuje problem konfliktów interwałów w sesjach synchronizacji z nowymi przedziałami. Uzgadnia też aktywność zarejestrowaną jednocześnie na wielu urządzeniach, takich jak zegarek i telefon.

Uzgodnienie rozwiązuje konflikt sesji przez wybranie autorytatywnego rekordu, a nie przez utworzenie sztucznego połączenia czasowego. Nie scalają na przykład zakresów 11:00:00Z–11:30:00Z i 11:20:00Z–11:50:00Z w zakres 11:00:00Z–11:50:00Z. Uzgodniona odpowiedź zwraca zwycięski punkt danych z pierwotnie zarejestrowanym interwałem. Dzięki temu zachowasz integralność danych telemetrycznych i wskaźników zmierzonych podczas tej sesji.

Rysunek 3 przedstawia, jak punkt końcowy reconcile obsługuje nakładające się sesje. Wybiera on rekord autorytatywny, zamiast tworzyć sztuczną sumę czasu.

Rozwiązywanie problemu nakładających się interwałów: uzgadnianie deduplikacji punktów końcowych i scalania sztucznych przedziałów czasu
Ilustracja 3. Uzgadnianie konfliktów sesji a scalanie sztucznego przedziału czasu

Przewodnik po punktach końcowych zawiera pełne przykłady żądań i odpowiedzi. Aby porównać nieprzetworzone rekordy list z danymi wyjściowymi reconcile, przeczytaj artykuł Uzyskiwanie uzgodnionego widoku danych interwałowych.

Punkt końcowy list jest przeznaczony do diagnostyki urządzeń i kontroli danych. Używaj go, gdy Twój przepływ pracy wymaga sprawdzania niezmodyfikowanych rekordów przesłanych przez poszczególne urządzenia. Podczas wysyłania zapytań do list logika klienta musi obsługiwać wszystkie nakładające się interwały w nieprzetworzonych danych.

Zmienność sygnatury czasowej i aktualizacje właściciela

Połączone urządzenia nie modyfikują wstecznie zapisanych sygnatur czasowych podczas normalnych cykli synchronizacji. Jednak sygnatury czasowe interwałów (startTime i endTime w ładunkach JSON REST lub start_time i end_time w wyrażeniach filtra i gRPC) nie są powszechnie niezmienne we wszystkich źródłach danych. Tylko pierwotny twórca lub właściciel rekordu może modyfikować jego pola. Inne aplikacje nie mogą edytować punktów danych, których nie utworzyły.

Aplikacja właściciela może używać punktu końcowego patch do aktualizowania istniejących rekordów. Obejmuje to modyfikowanie sygnatur czasowych rozpoczęcia lub zakończenia, co powoduje aktualizację pól czasu UTC (startTime i endTime) oraz czasu cywilnego (civilStartTime i civilEndTime) na serwerze. Przykład aktualizowania sygnatur czasowych za pomocą PATCH znajdziesz w sekcji Aktualizowanie sygnatur czasowych interwałów w przypadku istniejących danych w przewodniku po punktach końcowych.

Podobnie punkty danych zsynchronizowane z platform zewnętrznych, takich jak Health Connect czy aplikacje partnerów, dziedziczą aktualizacje ze źródła. Jeśli Health Connect otrzyma później aktualizację zsynchronizowanego rekordu z oryginalnej aplikacji innej firmy, zmiany zostaną wprowadzone i zastąpią istniejący rekord.