Dostęp do interfejsu Google Health API jest zapewniany przez Google Cloud. Aby włączyć interfejs API i autoryzować konto Google, musisz mieć projekt w chmurze Google.
Niezależnie od tego, czy jesteś obecnym deweloperem interfejsu Fitbit API, czy dopiero zaczynasz korzystać z interfejsu Google Health API, musisz wykonać ten krok, aby wywoływać interfejs API.
Tworzenie projektu i klienta OAuth
Kliknij przycisk Włącz interfejs API i uzyskaj identyfikator klienta OAuth 2.0, aby włączyć interfejs Google Health API i uzyskać identyfikator klienta OAuth 2.0:
- Jeśli masz istniejący projekt w chmurze Google Cloud, którego chcesz używać w interfejsie Google Health API, najpierw zaloguj się na konto administratora tego projektu. Następnie wybierz istniejący projekt z listy dostępnych projektów po kliknięciu przycisku. W przeciwnym razie utwórz nowy projekt.
- Gdy pojawi się pytanie „Skąd dzwonisz?”, wybierz Serwer internetowy.
- Wpisz https://www.google.com jako wartość pola Autoryzowane identyfikatory URI przekierowania. Aby uzyskać kod autoryzacji za pomocą protokołu OAuth 2.0, musisz podać identyfikator URI przekierowania.
- Po zakończeniu konfiguracji skopiuj wartości identyfikatora klienta i tajnego klucza klienta OAuth 2.0 oraz pobierz plik JSON z danymi logowania na komputer lokalny.
Jeśli chcesz ręcznie skonfigurować projekt Google Cloud lub sprawdzić konfigurację i ponownie pobrać dane logowania:
- Włącz Google Health API na stronie Włączanie interfejsu API.
- Uzyskaj identyfikator klienta OAuth 2.0 na stronie Dane logowania.
Więcej informacji o konfigurowaniu OAuth 2.0 za pomocą konsoli Google znajdziesz w artykule Używanie protokołu OAuth 2.0 na potrzeby dostępu do interfejsów API Google.
Używanie osobnych projektów na potrzeby środowisk testowego i produkcyjnego
Interfejs Google Health API nie udostępnia osobnego środowiska piaskownicy ani środowiska testowego. Wszystkie środowiska wywołują produkcyjny interfejs Google Health API, więc separację środowisk zarządzasz na poziomie projektu Google Cloud.
Podczas konfigurowania środowisk dla aplikacji postępuj zgodnie z tymi sprawdzonymi metodami:
- Utwórz osobne projekty Google Cloud dla środowisk deweloperskiego, testowego i produkcyjnego. Każdy projekt zarządza własnym klientem OAuth 2.0, ekranem zgody i subskrybentami webhooków.
- Do testowania nie używaj produkcyjnego projektu Google Cloud ani jego klienta OAuth 2.0, ponieważ zmiany w tym projekcie mają bezpośredni wpływ na aplikację produkcyjną.
- Najpierw opracuj i przetestuj projekt w środowisku nieprodukcyjnym, a potem, gdy wszystko będzie gotowe, zastosuj zmiany w projekcie produkcyjnym.
- Używaj tagów w konsoli Google Cloud, aby wizualnie odróżniać projekty według środowiska. Instrukcje znajdziesz w artykule Oznaczanie środowisk projektu za pomocą tagów.
Dodawanie użytkowników testowych
Domyślnie nowo utworzeni klienci OAuth są w stanie niezweryfikowanym i mają limit 100 użytkowników zarówno na potrzeby testów, jak i wersji produkcyjnej. Aby w tym okresie włączyć autoryzację, musisz ręcznie dodać adres e-mail każdego użytkownika do listy użytkowników testowych w konfiguracji projektu.
Zaktualizuj listę użytkowników testowych na stronie Odbiorcy:
- Na tej stronie powinny być widoczne te ustawienia: „Stan publikacji” – Testowanie i „Typ użytkownika” – Zewnętrzny.
- W sekcji „Użytkownicy testowi” kliknij + Dodaj użytkowników. Wpisz adres e-mail użytkowników testowych, którzy powinni mieć możliwość przyznania aplikacji uprawnień dostępu do danych dotyczących zdrowia.
- Kliknij Zapisz.
Obsługa ponad 100 użytkowników za pomocą interfejsu Google Health API wymaga przeprowadzenia oceny bezpieczeństwa przez firmę zewnętrzną. Więcej informacji znajdziesz w Centrum pomocy dotyczącym weryfikacji aplikacji OAuth.
Dodawanie zakresów
Na stronie Dostęp do danych musisz określić zakresy, do których klient ma prawo się odwoływać:
- Na tej stronie kliknij Dodaj lub usuń zakresy.
- W kolumnie API (Interfejs API) wyszukaj „Google Health API”. Wybierz zakresy, których potrzebujesz w swojej aplikacji.
- Po wybraniu wszystkich potrzebnych zakresów kliknij Aktualizuj, aby wrócić na stronę Dostęp do danych.
- Kliknij Zapisz.
Przed wybraniem zakresów zapoznaj się z implementacją zakresów.
Konfigurowanie identyfikatora klienta zostało zakończone. Teraz możesz wykonywać wywołania interfejsu Google Health API.
Zaktualizuj zakresy
Możesz poprosić użytkownika o ponowne autoryzowanie aplikacji, ustawiając w żądaniu uwierzytelniania parametr prompt na wartość consent. Jeśli uwzględniono parametr prompt=consent, ekran zgody będzie wyświetlany za każdym razem, gdy aplikacja poprosi o autoryzację zakresów dostępu, nawet jeśli wszystkie zakresy zostały wcześniej przyznane projektowi interfejsów API Google.
Aby dodać lub zmienić zakresy za pomocą parametru prompt=consent, wykonaj te czynności:
Określ pełną listę zakresów, których potrzebuje Twoja aplikacja. Powinny one obejmować zarówno dotychczasowe zakresy, jak i wszystkie nowe, które chcesz dodać.
Zmodyfikuj parametr scope w adresie URL autoryzacji, aby zawierał zaktualizowaną listę wartości zakresu rozdzielonych spacjami.
Do parametrów identyfikatora URI uwierzytelniania dodaj znak
prompt=consent. Wymusza to wyświetlenie przez serwer autoryzacji prośby o zgodę użytkownika przed zwróceniem informacji do klienta.Poniższy przykład pokazuje żądanie HTTPS GET do punktu końcowego autoryzacji OAuth 2.0 od Google, które żąda wielu zakresów z dodanym parametrem
prompt=consent:https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent
Gdy użytkownik kliknie zaktualizowany link, wyświetli się strona zgody z listą wszystkich żądanych zakresów. Gdy użytkownik kliknie „Dalej” lub „Zezwól”, otrzymasz nowy kod autoryzacji, który można wymienić na tokeny obejmujące pełny zestaw zakresów.
prompt=consentnależy uwzględniać tylko w razie potrzeby, np. gdy trzeba uzyskać nowy token odświeżania lub gdy zmieniły się żądane zakresy.
Biblioteki klienta OAuth2
Listę dostępnych bibliotek klienta OAuth2 używanych do integracji z popularnymi platformami znajdziesz w artykule Używanie OAuth 2.0 na potrzeby dostępu do interfejsów API Google.
Podczas wdrażania Google OAuth w aplikacjach mobilnych lub na komputery zawsze używaj przeglądarek systemowych (takich jak karty niestandardowe Chrome na Androidzie lub ASWebAuthenticationSession na iOS) i nigdy nie używaj osadzonych komponentów WebView, które blokują klucze dostępu i przerywają procesy Google OAuth. Zapoznaj się ze sprawdzonymi metodami dotyczącymi logowania się za pomocą Google.
Łączenie Google Health przed uzyskaniem zgody OAuth
Zanim użytkownik przejdzie w aplikacji proces uzyskiwania zgody w ramach Google OAuth 2.0, musi zalogować się w aplikacji mobilnej Google Health, aby połączyć Google Health ze swoim kontem Google. Google OAuth 2.0 uwierzytelnia każde prawidłowe konto Google i nie może sprawdzić, czy konto ma aktywny profil Google Health na ekranie zgody.
Poproś użytkowników, aby przed rozpoczęciem procesu uzyskiwania zgody OAuth w Twojej aplikacji wykonali te czynności w aplikacji mobilnej Google Health:
- Pobierz i otwórz aplikację mobilną Google Health ze Sklepu Google Play lub Apple App Store.
- Kliknij Zaloguj się przez Google i wybierz konto Google, które chcesz połączyć z aplikacją.
- Postępuj zgodnie z instrukcjami wyświetlanymi w aplikacji, aby utworzyć nowy profil Google Health, lub wykonaj kroki przenoszenia konta Fitbit, aby przenieść dotychczasowe konto Fitbit na konto Google.
Po wymianie kodu autoryzacji na tokeny OAuth wywołaj punkt końcowy users.getIdentity (GET
https://health.googleapis.com/v4/users/me/identity), aby sprawdzić, czy konto Google użytkownika jest połączone z Google Health, zanim oznaczysz konto jako połączone w swojej aplikacji. Szczegółowe informacje o obsłudze niepołączonych kont (400
ACCOUNT_NOT_LINKED) znajdziesz w artykule Obsługa niepołączonych kont Google.
Tokeny odświeżania
Aby zachować długoterminowy dostęp do interfejsów API Google bez konieczności ciągłego ponownego uwierzytelniania użytkownika, aplikacja musi używać tokena odświeżania. Szczegółowe informacje o wdrażaniu, w tym konkretne żądania HTTP i wymagane parametry, znajdziesz w dokumentacji platformy tożsamości Google.
Aby wymienić token odświeżania na token dostępu, wyślij wywołanie HTTPS POST do punktu końcowego tokena Google OAuth 2.0. Poniższy fragment kodu pokazuje przykładowe żądanie i odpowiedź:
Żądanie
curl -L -X POST 'https://oauth2.googleapis.com/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'
Odpowiedź
{
"access_token": "access-token",
"expires_in": 3599,
"scope": "scope-list",
"token_type": "Bearer",
"refresh_token": "refresh-token",
"refresh_token_expires_in": 112154
}Kiedy odświeżyć token
Odświeżaj tokeny dostępu na żądanie w ramach naturalnego przebiegu aktywnej sesji użytkownika, gdy tokeny dostępu wygasną lub zbliżają się do wygaśnięcia. Unikaj odświeżania tokenów w partiach (np. za pomocą zaplanowanego zadania lub usługi cron, które odświeżają tokeny wszystkich użytkowników o określonej godzinie).
Odświeżanie tokenów w partiach nie jest zalecane z tych powodów:
- Odświeżanie wsadowe uniemożliwia dopasowywanie aktualizacji tokenów do wzorców synchronizacji aktywnych użytkowników. Aby sprawdzić czas ostatniej synchronizacji użytkownika, możesz użyć wywołania Get Devices, ale wymaga to dodatkowego zakresu OAuth, którego użytkownicy nie muszą zatwierdzać.
- Przetwarzanie wsadowe aktualizuje tokeny, które nie wymagają odświeżenia, co powoduje zbędne obciążenie przetwarzaniem zarówno w Twoich systemach, jak i na serwerach Google.
- Jeśli podczas odświeżania wsadowego wystąpi problem z siecią lub awaria serwera, wpłynie to na wszystkie tokeny użytkowników. Odświeżanie tokenów pojedynczo podczas naturalnego przebiegu synchronizacji użytkowników ogranicza wpływ przejściowych awarii do jednego użytkownika.
- W przypadku zadań wsadowych diagnozowanie problemów jest trudniejsze. Ponieważ żądania wsadowe są wysyłane rzadziej i generują wiele wpisów w logu naraz, trudniej jest określić początek incydentu.
- Wysokie skoki współbieżności w żądaniach tokenów podczas uruchamiania pakietowego zwiększają prawdopodobieństwo osiągnięcia limitów szybkości lub wystąpienia sporadycznych błędów uwierzytelniania.
Działanie tokena podczas testowania
Pamiętaj, jak działają tokeny odświeżania w zależności od stanu publikacji projektu Google Cloud:
- Tryb testowania: jeśli ekran zgody OAuth jest skonfigurowany ze stanem publikacji „Testowanie”, wydane tokeny odświeżania są oparte na czasie i wygasają po 7 dniach. W tym okresie otrzymasz jeden token odświeżania, który pozostanie ważny i będzie można go używać do uzyskiwania nowych tokenów dostępu do daty wygaśnięcia.
- Tryb opublikowany: gdy aplikacja zostanie przeniesiona do stanu „W produkcji”, tokeny odświeżania zwykle nie wygasają, chyba że zostaną unieważnione lub pozostaną nieużywane przez dłuższy czas (zwykle 6 miesięcy).
Aby zapewnić użytkownikom bezproblemową obsługę, opublikuj aplikację przed przeniesieniem jej do środowiska produkcyjnego, aby uniknąć wygaśnięcia tokena po 7 dniach.
Generowanie przykładowych danych
Google nie udostępnia wstępnie wypełnionych przykładowych ani testowych danych dotyczących zdrowia. Aby przetestować integrację, musisz wygenerować własne dane testowe. Aby wygenerować dane próbne dla użytkowników testowych, użyj jednej z tych metod:
- Noszenie trackera: noś tracker Fitbit, zegarek Pixel Watch lub inny smartwatch zgodny z aplikacją Google Health i chodź, aby generować dane dotyczące kroków, tętna i treningów.
- Włącz śledzenie na urządzeniu mobilnym: włącz funkcję MobileTrack w aplikacji Google Health i chodź z urządzeniem mobilnym.
- Ręczne rejestrowanie danych: ręczne wprowadzanie wskaźników zdrowia (takich jak sen, waga, spożycie wody lub jedzenia) w aplikacji Google Health.
- Zapisywanie danych za pomocą interfejsu API: wysyłaj żądania zapisu (np.
POSTlubPATCH) bezpośrednio do punktów końcowych interfejsu REST API, aby programowo wypełniać dane. Więcej informacji o tworzeniu i aktualizowaniu punktów danych znajdziesz w dokumentacji interfejsu REST.
Ochrona wszystkich kont (interfejs RISC API)
Włącz udostępnianie i koordynowanie informacji o ryzyku i incydentach (RISC), jeśli chcesz otrzymywać powiadomienia o zmianach w tokenach zdarzeń lub połączeniach kont, np. o odłączonych kontach lub odwołanych tokenach, aby zwalniać miejsce zajmowane przez zapisane tokeny i aktualizować stan połączenia w interfejsie. Włączenie interfejsu RISC API jest opcjonalne.
Aby włączyć interfejs RISC API w projekcie Google Cloud:
- Otwórz stronę RISC API w konsoli Google Cloud. Upewnij się, że wybrany jest projekt, którego używasz w przypadku interfejsu Google Health API.
- Przeczytaj Warunki RISC i upewnij się, że rozumiesz wymagania.
- Jeśli akceptujesz warunki, kliknij Włącz.
Po włączeniu interfejsu API musisz utworzyć i zarejestrować punkt końcowy HTTPS, aby otrzymywać i weryfikować tokeny zdarzeń wysyłane przez Google.
Więcej informacji o Ochronie wszystkich kont i RISC znajdziesz w artykule Ochrona kont użytkowników za pomocą Ochrony wszystkich kont.