Zarządzanie danymi w interfejsie Google Health API

Praca z danymi w interfejsie Google Health API to przede wszystkim cykl synchronizowania danych między magazynem danych interfejsu Google Health API w chmurze a własną aplikacją lub magazynem danych backendu. Ten cykl może jednak przyjmować różne formy w zależności od wielu czynników:

• Czy zapisujesz dane w interfejsie Google Health API? Czy tylko je odczytujesz? Czy robisz obie te rzeczy?
• Czy Twój magazyn danych jest lokalny w aplikacji lub na urządzeniu? Czy znajduje się w Twojej chmurze?
• Czy musisz synchronizować dane interfejsu Google Health API między aplikacją użytkownika a urządzeniem do noszenia? Jak często synchronizujesz urządzenia?
• Jakie typy danych przetwarzasz? Podstawowe liczby? Jednostki miary? Serie 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 przed uzyskaniem przez aplikację uprawnień użytkownika?

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

Standardowy cykl życia synchronizacji

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. Aby ułatwić korzystanie z tej dokumentacji, będziemy nazywać ten magazyn danych magazynem danych dewelopera.

„Kopiowanie” może tu zastępować dowolną dyskretną czynność, np. odczytywanie z interfejsu Google Health API (kopiowanie do magazynu danych dewelopera) lub zapisywanie w interfejsie Google Health API (kopiowanie do interfejsu Google Health API). Powtarzanie 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 względu na wcześniej wspomniane czynniki.

Zapis

1. Przygotuj nowe dane do zapisu – przenieś dane z urządzenia zewnętrznego lub aplikacji i sformatuj punkty danych w reprezentacjach JSON zgodnych z typami danych interfejsu Google Health API. Pamiętaj, że w interfejsie Health API nie są obecnie obsługiwane niestandardowe identyfikatory przypisane przez klienta do zapisu. Takie identyfikatory mogą być podane w żądaniu POST, ale są ignorowane.
2. Wstaw lub zaktualizuj rekordy – prześlij punkty danych do interfejsu Google Health API za pomocą punktów końcowych REST. Użyj żądania POST, aby utworzyć rekordy, a żądania PATCH, aby wstawić i zaktualizować istniejące rekordy. Identyfikatory potrzebne do operacji PATCH będą pochodzić z poprzedniej operacji POST (następny krok w poprzednim cyklu).
3. Przetwarzaj zwrócone identyfikatory zasobów – jeśli używasz identyfikatorów generowanych przez serwer, wyodrębnij i zapisz zwróconą przez serwer name lub identyfikator zasobu w magazynie danych dewelopera, aby umożliwić przyszłe aktualizacje (PATCH) lub usunięcia (DELETE). Więcej informacji o tych 2 typach znajdziesz w sekcji Strategie identyfikacji.

Przeczytane

1. Odczytuj rekordy – pobieraj nowe dane i zmiany w istniejących danych w interfejsie Google Health API za pomocą punktów końcowych REST (GET z parametrami zapytania filter i paginacją pageToken lub punktów końcowych agregacji, takich jak rollUp i dailyRollUp) albo otrzymuj powiadomienia w czasie rzeczywistym za pomocą subskrypcji webhooka (projects.subscribers). Powiadomienie wskazuje tylko, że dostępne są nowe dane, a nie jakie to dane.
2. Synchronizuj magazyn danych dewelopera – synchronizuj nowe i zaktualizowane dane z magazynem danych dewelopera.

Ten cykl powtarza się w odpowiednich odstępach czasu w zależności od konkretnych potrzeb urządzeń zewnętrznych lub aplikacji. Zalecamy, aby synchronizować dane między własnym magazynem danych a interfejsem Google Health API w tej kolejności.

Strategie identyfikacji

Jeśli zamierzasz 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).

W interfejsie Health API nie są obecnie obsługiwane identyfikatory przypisane przez klienta do zapisu. Takie identyfikatory mogą być podane w żądaniu POST, ale są ignorowane. Szczegóły tej opcji są podane tutaj 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 systemu.
2. Niestandardowe identyfikatory przypisane przez klienta (zgodnie z AIP-133, obecnie nie są obsł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ównaliśmy obie strategie identyfikacji, aby pomóc Ci wybrać odpowiednie podejście do integracji:

Funkcja	Identyfikatory generowane przez serwer	Niestandardowe identyfikatory przypisane przez klienta
Generowanie identyfikatorów	Serwer generuje losowy identyfikator systemu podczas POST wykonywania.	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}
Lokalny krok po zapisie	Wymagany. Aby umożliwić przyszłe aktualizacje lub usunięcia, musisz zapisać zwrócony server_id w lokalnej bazie danych.	Brak. Aplikacja jest już właścicielem identyfikatora.
Tabela mapowania identyfikatorów	Wymagana. Klient musi utrzymywać dwukierunkowe mapowanie (local_id ↔ server_id).	Nie jest potrzebna. Klient używa bezpośrednio własnego klucza podstawowego.
Zachowanie podczas ponawiania (słaba sieć)	Ryzyko duplikatów. Ponowienie żądania, które przekroczyło limit czasu POST , spowoduje utworzenie zduplikowanego rekordu z nowym identyfikatorem serwera.	Bezpieczne i idempotentne. Ponowienie żądania POST z tym samym custom_id zapobiega tworzeniu duplikatów (zwraca 409 ALREADY_EXISTS).
Obsługa synchronizacji offline	Ograniczona. Przed odwołaniem się do oficjalnych identyfikatorów zasobów musisz poczekać na odpowiedź serwera.	Pełna. 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ć zgodny z wyrażeniem ^[a-z0-9-]{4,63}$ (4–63 małe litery alfanumeryczne i łączniki).
Kiedy wybrać	Wybierz identyfikatory generowane przez serwer, jeśli: Twoja aplikacja jest tylko do zapisu lub tylko do dołączania (np. wysyłanie danych telemetrycznych lub liczby kroków, które nigdy nie są aktualizowane ani usuwane). Twoja aplikacja nie utrzymuje lokalnej trwałej bazy danych poszczególnych punktów danych. Wolisz prostotę bez zarządzania ograniczeniami dotyczącymi sprawdzania poprawności ciągów znaków ograniczeniami (np. 4-63 znaki).	Wybierz niestandardowe identyfikatory, jeśli: Używasz aplikacji do synchronizacji dwukierunkowej, która odczytuje, zapisuje i aktualizuje dane o zdrowiu 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 za pomocą przerywanych połączeń mobilnych w których konieczne jest bezpieczne ponawianie. Chcesz wyeliminować tabele mapowania identyfikatorów między bazą danych backendu a interfejsem API.

Cykl życia synchronizacji tylko do odczytu

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

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

Obowiązują tu te same zadania, które zostały opisane w sekcji Odczyt.

Rysunek 2 przedstawia cykl życia tylko do odczytu.