Real Time Reporting API – autoryzacja

W tym przewodniku opisano, jak aplikacja autoryzuje żądania wysyłane do interfejsu Real Time Reporting API.

Autoryzacja żądań

Aby użytkownicy mogli wyświetlić informacje o swoim koncie w witrynie Google Analytics, muszą najpierw zalogować się na swoje konta Google. Podobnie gdy użytkownicy po raz pierwszy uzyskują dostęp do Twojej aplikacji, muszą ją autoryzować, aby uzyskać dostęp do swoich danych.

Każde żądanie wysyłane przez aplikację do interfejsu Analytics API musi zawierać token autoryzacji. Token stanowi też dla Google identyfikator aplikacji.

Informacje o protokołach autoryzacji

Twoja aplikacja musi autoryzować żądania za pomocą protokołu OAuth 2.0. Inne protokoły nie są obsługiwane. Jeśli aplikacja używa funkcji Zaloguj się przez Google, niektórymi aspektami autoryzacji nie musisz się zajmować.

Autoryzowanie żądań za pomocą protokołu OAuth 2.0

Wszystkie żądania wysyłane do interfejsu Analytics API muszą być autoryzowane przez uwierzytelnionego użytkownika.

Szczegóły procesu autoryzacji z użyciem protokołu OAuth 2.0 różnią się nieznacznie w zależności od rodzaju projektowanej aplikacji. Do większości typów aplikacji ma zastosowanie ten ogólny proces:

  1. Gdy tworzysz aplikację, rejestrujesz ją, korzystając z konsoli interfejsów API Google. Następnie Google przekazuje informacje, które są potrzebne później, takie jak identyfikator klienta i tajny klucz klienta.
  2. Aktywuj interfejs Analytics API w Konsoli interfejsów API Google. (jeśli interfejsu API nie ma na liście w konsoli, pomijasz ten krok).
  3. Gdy Twoja aplikacja potrzebuje dostępu do danych użytkownika, prosi Google o konkretny zakres dostępu.
  4. Google wyświetla użytkownikowi ekran zgody z prośbą o autoryzowanie dostępu aplikacji do niektórych danych.
  5. Jeśli użytkownik wyrazi zgodę, Google przekazuje Twojej aplikacji ważny przez krótki czas token dostępu.
  6. Aplikacja żąda danych użytkownika i dołącza do żądania token dostępu.
  7. Jeśli Google uzna, że żądanie i token są prawidłowe, przesyła dane, o które prosisz.

Niektóre procesy obejmują dodatkowe kroki, takie jak wykorzystanie tokenów odświeżania do uzyskania nowych tokenów dostępu. Szczegółowe informacje o procesach obowiązujących w przypadku różnych typów aplikacji znajdziesz w dokumencie Google na temat protokołu OAuth 2.0.

Oto informacje o zakresie protokołu OAuth 2.0 dla interfejsu Analytics API:

Zakres Znaczenie
https://www.googleapis.com/auth/analytics.readonly Dostęp tylko do odczytu do interfejsu Analytics API.

Aby poprosić o dostęp przy użyciu protokołu OAuth 2.0, aplikacja potrzebuje danych z zakresu oraz informacji przekazywanych przez Google po zarejestrowaniu aplikacji (takich jak identyfikator klienta i tajny klucz klienta).

Wskazówka: biblioteki klienta interfejsów API Google mogą wykonać niektóre procesy autoryzacji za Ciebie. Są dostępne dla różnych języków programowania. Więcej szczegółów znajdziesz na stronie z bibliotekami i próbkami.

Typowe przepływy OAuth 2.0

Poniżej znajdziesz typowe przypadki użycia konkretnych przepływów OAuth 2.0:

Serwer WWW

Ten przepływ sprawdza się w przypadku zautomatyzowanego, offline lub zaplanowanego dostępu do danych Google Analytics użytkownika.

Przykład:

  • Automatyczne aktualizowanie paneli użytkownika za pomocą najnowszych danych Google Analytics.

Po stronie klienta

Ten proces jest idealny dla aplikacji, w których użytkownicy korzystają bezpośrednio z aplikacji i uzyskują dostęp do danych Google Analytics w przeglądarce. Eliminuje to potrzebę korzystania z funkcji po stronie serwera, ale sprawia, że zautomatyzowane, offline lub zaplanowane raportowanie jest niepraktyczne.

Przykład:

Zainstalowane aplikacje

Ten proces dotyczy aplikacji rozpowszechnianych w postaci pakietów i instalowanych przez użytkownika. Aby zakończyć proces uwierzytelniania, aplikacja lub użytkownik musi mieć dostęp do przeglądarki.

Przykłady:

  • Widżet na komputery na komputerze PC lub Mac.
  • Wtyczka do systemu zarządzania treścią – zaletą tego procesu w porównaniu z serwerem WWW lub po stronie klienta jest to, że na potrzeby aplikacji można używać jednego projektu konsoli API. Pozwala to na skonsolidowane raportowanie i ułatwia użytkownikom instalację.

Konta usługi

Konta usługi ułatwiają uzyskanie zautomatyzowanego, offline lub zaplanowanego dostępu do danych Google Analytics na Twoim koncie. Możesz np. utworzyć panel na żywo z własnymi danymi Google Analytics i udostępnić je innym użytkownikom.

Aby rozpocząć korzystanie z interfejsu Analytics API, musisz najpierw użyć narzędzia do konfiguracji, które przeprowadzi Cię przez proces tworzenia projektu w Konsoli interfejsów API Google, włączania interfejsu API i tworzenia danych logowania.

Aby skonfigurować nowe konto usługi, wykonaj te czynności:

  1. Kliknij Utwórz dane logowania > Klucz konta usługi.
  2. Wybierz, czy chcesz pobrać klucz publiczny/prywatny konta usługi jako standardowy plik P12 czy jako plik JSON, który może zostać wczytany przez bibliotekę klienta interfejsu API Google.

Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie. To jedyny egzemplarz tego klucza. Twoim obowiązkiem jest jego bezpieczne przechowywanie.

Rozwiązywanie problemów

Autoryzacja kończy się niepowodzeniem w tych sytuacjach:

  • Jeśli Twój access_token stracił ważność lub używasz niewłaściwego zakresu interfejsu API, otrzymasz kod stanu 401.

  • Jeśli autoryzowany użytkownik nie ma dostępu do widoku (profilu), zobaczysz kod stanu 403. Upewnij się, że masz upoważnienie odpowiedniego użytkownika oraz że rzeczywiście ma on wybrany widok (profil).

Interfejs API OAuth 2.0

To narzędzie umożliwia przejście przez cały proces autoryzacji w interfejsie internetowym. Narzędzie wyświetla też wszystkie nagłówki żądań HTTP wymagane do utworzenia autoryzowanego zapytania. Jeśli nie możesz uzyskać autoryzacji do działania we własnej aplikacji, spróbuj ją uruchomić na placu zabaw OAuth 2.0. Następnie możesz porównać nagłówki HTTP i żądania z placem zabaw z tym, co Twoja aplikacja wysyła do Google Analytics. To prosty sposób na sprawdzenie, czy żądania zostały prawidłowo sformatowane.

Nieprawidłowe uwierzytelnienie

Gdy spróbujesz użyć tokena odświeżania, wyświetli się błąd invalid_grant:

Aplikacje mogą prosić o wiele tokenów odświeżania w celu uzyskania dostępu do jednego konta Google Analytics.

Jeśli np. użytkownik chce zainstalować aplikację na wielu komputerach i mieć dostęp do tego samego konta Google Analytics, będzie wymagany oddzielny token dla każdego z nich. Gdy liczba tokenów odświeżania przekroczy limit, starsze tokeny stają się nieważne. Jeśli aplikacja spróbuje użyć unieważnionego tokena odświeżania, zwracana jest odpowiedź błędu invalid_grant.

Limit dla każdej unikalnej pary klienta OAuth 2.0 i konta Google Analytics wynosi 25 tokenów odświeżania. Jeśli aplikacja nadal będzie żądać tokenów odświeżania dla tej samej pary klient/konto, po wydaniu 26 tokena pierwszy wydany wcześniej token odświeżania stanie się nieważny. 27. żądany token odświeżania unieważni drugi wystawiony wcześniej token i tak dalej.