Przewodnik dla programistów

Z tego dokumentu dowiesz się, jak uzyskiwać dane Google Analytics za pomocą interfejsu API do raportowania w czasie rzeczywistym.

Wstęp

Interfejs Real Time Reporting API umożliwia raportowanie aktywności w usłudze w tej chwili. Aby uzyskać dostęp do danych w czasie rzeczywistym, utwórz zapytanie określające widok (profil) i co najmniej jeden wskaźnik. Możesz też podać dodatkowe parametry zapytania, takie jak wymiary i filtry, aby doprecyzować zapytanie. To zapytanie jest wysyłane do interfejsu Real Time Reporting API, który zwraca dane w postaci tabeli.

Jeśli po raz pierwszy korzystasz z interfejsu API, przeczytaj Omówienie interfejsu Real Time Reporting API, aby zapoznać się z interfejsem Real Time Reporting API i dostarczanymi przez niego danymi.

Warunek wstępny

Zanim użyjesz interfejsu API do raportowania w czasie rzeczywistym w celu pobrania danych Google Analytics:

  • Pełną listę bibliotek klienta dla poszczególnych języków programowania, które obsługują interfejs API, znajdziesz na stronie bibliotek klienta.
  • Z Przewodnika informacyjnego dowiesz się, jak używać samego interfejsu API (bez korzystania z biblioteki klienta) do pobierania danych Google Analytics.

Każda biblioteka klienta udostępnia jeden obiekt usługi analitycznej, który zapewnia dostęp do wszystkich danych interfejsu Real Time Reporting API. Aby utworzyć obiekt usługi:

  1. Zarejestruj aplikację w Konsoli interfejsów API Google.
  2. Autoryzacja dostępu do danych Google Analytics.
  3. Utwórz obiekt usługi Analytics.

Jeśli nie udało Ci się wykonać tych czynności, zatrzymaj się i przeczytaj samouczek Hello Google Analytics API, z którego dowiesz się, jak utworzyć aplikację interfejsu Google Analytics API. Gdy już wiesz, jak pobierać dane Google Analytics za pomocą interfejsu API,

Korzystanie z interfejsu API do raportowania w czasie rzeczywistym

Aby użyć interfejsu Real Time Reporting API, aplikacja:

  1. Wysyła zapytania do interfejsu Real Time Reporting API.
  2. Obsługuje odpowiedź interfejsu API.

Wysyłanie zapytań do interfejsu Real Time Reporting API

Obiekt usługi analitycznej udostępnia metodę tworzenia zapytania do interfejsu API do raportowania w czasie rzeczywistym. Więcej informacji o parametrach zapytania i danych dostępnych dla interfejsu API znajdziesz tutaj:

Po zdefiniowaniu zapytania wywołaj jego metodę execute, aby wysłać je do serwerów Google Analytics.

Obsługa odpowiedzi interfejsu API

Jeśli zapytanie do interfejsu Real Time Reporting API zakończy się powodzeniem, interfejs API zwróci żądane dane jako część zasobu danych w czasie rzeczywistym. Szczegółowe informacje o strukturze i formacie odpowiedzi interfejsu API znajdziesz w dokumentacji API do raportowania w czasie rzeczywistym.

W przypadku wystąpienia błędów interfejs API zwraca określony kod stanu i komunikat z opisem błędu. Wszystkie aplikacje powinny wychwytywać i obsługiwać błędy. Szczegółowa lista błędów i zalecenia dotyczące ponownych prób znajdziesz w odpowiedziach na błędy .

Przykłady kodu

Sekcja Przykłady na stronie Dane w czasie rzeczywistym: get zawiera przykładowy kod w różnych językach programowania, który umożliwia wysyłanie zapytań do interfejsu Real Time Reporting API i obsługę odpowiedzi interfejsu API.

Ograniczenia zapytań

Oto ograniczenia dotyczące zapytań do interfejsu Real Time API:

  • Jeśli dane rt:activeUsers są uwzględnione w zapytaniu z tymi filtrami wymiarów, obsługiwany jest tylko operator AND i typ dopasowania równości (==).
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Dane rt:activeUsers pobierają tylko liczbę użytkowników aktywnych w witrynie, więc nie używaj funkcji rt:minutesAgo w połączeniu z zasadą rt:activeUsers. Oznacza to, że rt:activeUsers zakłada, że rt:minutesAgo ma wartość 0.

  • Filtry wskaźników nie są obsługiwane.
  • Parametr fields nie jest obsługiwany.

Zarządzanie limitami

Zgodnie z opisem w sekcji Limity i limity dla interfejsu Real Time Reporting API obowiązują dzienne limity, które są udostępniane innym interfejsom API Google Analytics. Jeśli odpytujesz interfejs Real Time Reporting API w krótkich odstępach czasu, bardzo szybko osiągasz dzienne limity. W takim przypadku żądania z innych interfejsów API Google Analytics również przestaną działać, dopóki limit nie zostanie odświeżony.

Oto przykładowe implementacje, które mogą bardzo szybko wykorzystywać limit:

  • Masz wiele paneli w czasie rzeczywistym, które codziennie w bardzo krótkich odstępach czasu wysyłają zapytania o dane do pojedynczego widoku danych (profilu) Google Analytics.
  • Masz usługę z wieloma użytkownikami i masz zaimplementowany widżet czasu rzeczywistego. Za każdym razem, gdy widżet jest wyświetlany użytkownikowi, wysyłasz zapytania bezpośrednio do Google Analytics, a nie z pamięci podręcznej.

Aby zminimalizować wykorzystanie limitu i wydajnie nim zarządzać:

  • Zaimplementuj buforowanie po stronie serwera. Gdy wielu użytkowników prosi o te same dane w czasie rzeczywistym, należy zwrócić odpowiedź z pamięci podręcznej, zamiast wysyłać zapytania do interfejsu Real Time Reporting API dla każdego żądania. Następnie okresowo odświeżaj pamięć podręczną, podając najnowsze dane w czasie rzeczywistym z rozsądnymi odstępami między odświeżeniami, aby uniknąć przekroczenia dziennego limitu.
  • Możesz łączyć wiele zapytań, określając dodatkowe wymiary, i analizować odpowiedź po stronie serwera lub klienta.
  • Zwiększ przedział czasu, dla którego wysyłasz żądanie danych w czasie rzeczywistym.

Przykład: obliczanie częstotliwości odświeżania

Jeśli spodziewasz się regularnego wysyłania żądań dotyczących danych w czasie rzeczywistym, wybierz rozsądny odstęp czasu między odświeżeniami, który zależy od oczekiwanego wykorzystania.

Na przykład dla pojedynczego widoku danych (profilu) Google Analytics obowiązuje limit dzienny wynoszący 10 000 żądań. Jeśli w ciągu jednego dnia zamierzasz wysłać 6000 zapytań do interfejsu API podstawowego raportowania dla jednego widoku (profilu), dla tego widoku (profilu) zostanie Ci jeszcze 4000 żądań.

Załóżmy, że chcesz użyć interfejsu Real Time Reporting API w celu zaimplementowania 3 paneli w czasie rzeczywistym, które uruchamiają przez cały dzień zapytania o dane w czasie rzeczywistym z tego samego widoku (profilu). Każdy panel może wykonywać około 1333 zapytań dziennie (4000 zapytań / 3 panele). Każdy dzień ma 86 400 sekund. Z tego względu interwał odświeżania każdego panelu musi być dłuższy niż 65 sekund (86 400 / 1333), aby łączna liczba dziennych żądań dla widoku (profilu) nie przekraczała limitu dziennego wynoszącego 4000.