Real Time Reporting API – autoryzacja

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

Autoryzowanie żądań

Aby użytkownicy mogli wyświetlać informacje o swoich kontach w witrynie Google Analytics, muszą najpierw zalogować się na swoje konto Google. Podobnie jest w przypadku, gdy użytkownicy po raz pierwszy uzyskują dostęp do Twojej aplikacji, a jednocześnie 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 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 listę typowych przypadków użycia określonych przepływów OAuth 2.0:

Serwer WWW

Ten proces jest odpowiedni w przypadku automatycznego, offline lub zaplanowanego dostępu do danych Google Analytics użytkownika.

Przykład:

  • Automatyczne aktualizowanie paneli użytkowników o najnowsze dane Google Analytics.

Po stronie klienta

Ten proces jest idealny dla aplikacji, w których użytkownicy wchodzą w interakcje bezpośrednio z aplikacją, aby uzyskać dostęp do danych Google Analytics w przeglądarce. Eliminuje potrzebę korzystania z funkcji po stronie serwera, ale sprawia, że automatyczne, offline lub zaplanowane raportowanie jest niepraktyczne.

Przykład:

Zainstalowane aplikacje

Ten proces dotyczy aplikacji dystrybuowanych jako pakiet i instalowanych przez użytkownika. Ten proces wymaga, aby aplikacja lub użytkownik miał dostęp do przeglądarki w celu dokończenia procesu uwierzytelniania.

Przykłady:

  • Widżet pulpitu 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 wykorzystać jeden projekt Konsoli API. Pozwala to na skonsolidowane raportowanie i upraszcza instalację.

Konta usługi

Konta usługi przydają się w przypadku automatycznego, offline lub zaplanowanego dostępu do danych Google Analytics na Twoim koncie. np. aby utworzyć panel z własnymi danymi Google Analytics i udostępnić go 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 plik JSON, który może być ładowany przez bibliotekę klienta interfejsu API Google.

Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie. To jedyny egzemplarz tego klucza. To Ty odpowiadasz za jego bezpieczne przechowywanie.

Rozwiązywanie problemów

Autoryzacja kończy się niepowodzeniem w tych sytuacjach:

  • Otrzymasz kod stanu 401, jeśli Twoja forma płatności access_token wygasła lub jeśli używasz nieprawidłowego zakresu interfejsu API.

  • Jeśli autoryzowany użytkownik nie ma dostępu do widoku (profilu), otrzymasz kod stanu 403. Sprawdź, czy masz upoważnienie do korzystania z danych właściwego użytkownika, a także sprawdź, czy ma on wybrany widok (profil).

Protokół OAuth 2.0

To narzędzie umożliwia przejście przez cały proces autoryzacji przez interfejs internetowy. Narzędzie wyświetla też wszystkie nagłówki żądań HTTP, które są wymagane do utworzenia autoryzowanego zapytania. Jeśli nie możesz uzyskać autoryzacji do pracy we własnej aplikacji, spróbuj tego użyć, korzystając z protokołu OAuth 2.0. Następnie można porównać nagłówki HTTP i żądanie z narzędzia do wdrożenia z tym, co Twoja aplikacja wysyła do Google Analytics. Dzięki temu będziesz mieć pewność, że żądania są prawidłowo sformatowane.

Nieprawidłowe zezwolenie

Gdy spróbujesz użyć tokena odświeżania, wystąpi błąd invalid_grant:

Aby uzyskać dostęp do pojedynczego konta Google Analytics, aplikacje mogą żądać wielu tokenów odświeżania.

Jeśli np. użytkownik chce zainstalować aplikację na wielu komputerach i uzyskać dostęp do tego samego konta Google Analytics, dla każdego z nich będzie wymagany oddzielny token. 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, zostanie zwrócona 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 będzie nadal żądać tokenów odświeżania tej samej pary klient/konto, po wydaniu 26 tokena pierwszy token odświeżania, który został wcześniej wystawiony, stanie się nieważny. 27 żądany token odświeżania spowoduje unieważnienie drugiego wydanego wcześniej tokena i tak dalej.