Zarządzanie limitem interfejsu Google Analytics Data API

Minhaz Kazi, przedstawiciel ds. kontaktu z deweloperami, Google Analytics – luty 2023 r.

Jeśli tworzysz aplikacje za pomocą [Google Analytics Data API], musisz wiedzieć, jak działają limity i ograniczenia tego interfejsu. Jeśli Twoja aplikacja jest dobrze zaprojektowana, użytkownicy rzadziej będą przekraczać limity. Niektóre z tych sprawdzonych metod prowadzą też do wydajnych zapytań do interfejsu API. Może to przyspieszyć działanie raportów i paneli w aplikacji oraz zwiększyć wygodę użytkowników. W tym artykule omówiono system limitów i sprawdzone metody wdrażania interfejsu Google Analytics Data API.

System limitów interfejsu Google Analytics Data API

Z Google Analytics korzystają miliony deweloperów i użytkowników, dlatego limity żądań interfejsu API chronią system przed przetwarzaniem większej ilości danych, niż jest w stanie obsłużyć, a jednocześnie zapewniają sprawiedliwy podział zasobów systemowych. Interfejs Data API dla usług w Google Analytics 4 korzysta z systemu zasobnika tokena do zarządzania limitami interfejsu API. Aby zrozumieć tę koncepcję, wyobraź sobie, że jest koszyk, który może pomieścić maksymalną liczbę tokenów. Każde żądanie do interfejsu API najpierw sprawdzi zasobnik. Jeśli nie ma już tokenów, żądanie się nie powiedzie. W przeciwnym razie żądanie zostanie wykonane i w zależności od jego złożoności zużyje co najmniej 1 token z puli. Tokeny są uzupełniane w zasobniku do maksymalnej liczby w stałych odstępach czasu.

W zależności od używanej metody interfejsu Data API istnieją 3 osobne kategorie limitów:

• W czasie rzeczywistym (w przypadku runRealtimeReport)
• Ścieżka (w przypadku runFunnelReport)
• Podstawowe (w przypadku wszystkich innych metod)

Metody interfejsu Data API będą sprawdzać wiele zasobników [tokenów w ramach limitu][Limity interfejsu Google Analytics Data API]:

1. Na usługę dziennie
2. Na usługę na godzinę
3. Na godzinę projektu w usłudze
4. Równoczesne żądania w przypadku usługi
5. Błędy serwera na projekt na usługę na godzinę

Te 5 grup jest sprawdzanych za każdym razem, gdy do usługi Data API wpłynie żądanie do interfejsu API dotyczące usługi. Jeśli którykolwiek z koszyków jest pusty, żądanie zostanie natychmiast odrzucone z błędem 429. Jeśli żaden z tych przedziałów nie jest pusty, z przedziału Równoczesne żądania dotyczące usługi zostanie wykorzystany 1 token, a następnie zostanie wykonane żądanie do interfejsu API. W zależności od złożoności żądania po zakończeniu wykonania z każdego z 3 pierwszych koszyków zostanie wykorzystana określona liczba tokenów. W tym czasie zostanie też uzupełniony token w przypadku parametru Równoczesne żądania dotyczące usługi.

Limit na projekt na usługę na godzinę zapewnia, że wyczerpanie limitu przez co najmniej jednego użytkownika nie wpłynie na innych użytkowników aplikacji. W tym przypadku projekt odnosi się do projektu GCP aplikacji. Limit Na usługę na godzinę jest zwykle 4 razy większy niż limit Na projekt na usługę na godzinę. Dlatego w przypadku użytkowników końcowych dostęp do usługi musi być uzyskiwany z co najmniej 4 różnych projektów, zanim zostanie wyczerpany limit Na usługę na godzinę. Egzekwowanie limitów na poziomie projektu i usługi zapewnia, że problemy z limitami są ograniczone do jednej usługi i nie wpływają na inne usługi, do których uzyskuje dostęp Twoja aplikacja.

Ostrzeżenie: deweloperom zdecydowanie odradza się dzielenie tokenów limitu na kilka projektów interfejsu API. Stanowi to naruszenie Warunków korzystania z interfejsów API Google.

Limit Błędy serwera odnosi się do odpowiedzi interfejsu API z kodami 500 lub 503. Jeśli aplikacja generuje zbyt wiele błędów podczas uzyskiwania dostępu do usługi, wyczerpie limit błędów serwera na projekt na usługę na godzinę.

Wszystkie tokeny limitu są uzupełniane do limitu w określonych odstępach czasu. Aktualne informacje o limitach znajdziesz w artykule [Limity interfejsu Google Analytics Data API]. Na przykład metody podstawowe otrzymują 1250 tokenów limitu w kategorii Na projekt, na usługę,na godzinę. Zakładając, że średnie żądanie z Twojej aplikacji zużywa 10 tokenów limitu, w przypadku usługi standardowej aplikacja będzie mogła wysyłać 125 żądań podstawowych na godzinę, a w przypadku dowolnej usługi w Analytics 360 – 10 razy więcej (1250 żądań podstawowych). Wyższy limit tokenów to jedna z głównych zalet usług w Analytics 360.

Zużycie tokenów w przypadku pierwszych 3 zasobników zależy od złożoności żądania, dlatego trudno jest przewidzieć dokładne zużycie tokenów przed wykonaniem żądania. Złożoność żądania zwykle zwiększają te czynniki, co powoduje większe zużycie tokenów:

• Prośba o dodatkowe wymiary
• Wysyłanie zapytań dotyczących dłuższego zakresu czasu
• Wymiary o większej mocy zbioru
• Wysyłanie zapytań do usługi o większej liczbie zdarzeń

Dlatego to samo zapytanie dotyczące 2 różnych usług może skutkować zupełnie innym wykorzystaniem tokenów, ponieważ liczność wymiarów może się różnić lub wielkość ruchu może być inna. Możesz jednak oczekiwać, że usługi o podobnym poziomie ruchu i podobnej konfiguracji będą miały podobne zużycie tokenów. Możesz użyć tego założenia do prognozowania wykorzystania tokenów przez klientów na etapach planowania i projektowania aplikacji.

Uwaga: jeśli wcześniej korzystałeś(-aś) z interfejsu Reporting API w Universal Analytics, zauważysz, że interfejs ten wymuszał limity na poziomie projektu aplikacji lub interfejsu API. W przypadku interfejsu Data API egzekwowanie odbywa się na poziomie usługi w Google Analytics i na poziomie projektu API.

Monitorowanie wykorzystania limitu

Aby monitorować wykorzystanie limitu i przekazywać te informacje użytkownikowi, możesz dodać do treści żądania do interfejsu API parametr "returnPropertyQuota": true. Spowoduje to zwrócenie obiektu PropertyQuota wraz z odpowiedzią interfejsu API. Obiekt PropertyQuota będzie zawierać ilości wykorzystania i stan pozostałego limitu dla wszystkich 5 zasobników. Oto przykładowa treść żądania i odpowiedzi:

Żądanie

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Odpowiedź

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

Dlatego po każdym udanym żądaniu do interfejsu Data API możesz sprawdzić, ile limitu zostało wykorzystane i ile limitu pozostało w przypadku usługi. Możesz też wyświetlać te informacje użytkownikowi w interfejsie aplikacji.

Uwaga: na obecnym etapie interfejsu Data API musisz wysłać żądanie do interfejsu API, aby otrzymać obiekt PropertyQuota. Jeśli usługa wykorzystała już wszystkie tokeny z zasobnika tokena limitu, Twoja prośba zakończy się niepowodzeniem i zostanie zwrócony błąd 429, a odpowiedź nie będzie zawierać obiektu PropertyQuota. Jeśli dotyczy Cię ten problem i uważasz, że Twoja aplikacja skorzystałaby na osobnym sposobie dostępu do informacji o limicie, kliknij +1 przy tej prośbie o dodanie funkcji w narzędziu do śledzenia problemów.

Zarządzanie limitami

Aby w pełni wykorzystać interfejs Data API, zalecamy stosowanie opisanych poniżej sprawdzonych metod zarządzania limitami. Przekształcenie usług w usługi w wersji 360 może też zwiększyć ilość danych, do których można uzyskać dostęp za pomocą interfejsu API.

Sprawdzone metody

Istnieją 2 główne sposoby zmniejszenia wykorzystania limitu przez aplikację:

• Wysyłanie mniejszej liczby żądań do interfejsu API
• Wysyłanie mniej złożonych żądań do interfejsu API

Pamiętając o tych 2 zasadach, możesz wdrożyć te praktyki:

• Buforowanie: wdrożenie warstwy buforowania poprawi zarówno łatwość obsługi, jak i zarządzanie limitami w Twojej aplikacji. Google Analytics będzie buforować Twoje żądania do interfejsu API, ale powtarzające się żądania nadal będą zużywać tokeny w ramach limitu korzystania z usługi. Dzięki buforowaniu odpowiedzi interfejsu API możesz znacznie zmniejszyć liczbę powtarzających się żądań. Na przykład dane w ciągu dnia w przypadku usług standardowych mogą mieć czas wygaśnięcia pamięci podręcznej wynoszący 4 godziny lub więcej. Więcej informacji znajdziesz w artykule Częstotliwość aktualizacji danych w Google Analytics.
• Łączenie żądań: spróbuj połączyć kilka żądań do interfejsu API w jedno. Na przykład 5 żądań danych w ciągu 2 dni może wykorzystać 3 razy więcej tokenów przydziału niż 1 żądanie w ciągu 10 dni. Jeśli masz kilka żądań, które różnią się tylko jednym wymiarem, rozważ połączenie ich w jedno żądanie.
• Upraszczanie próśb: ograniczaj prośby do minimalnej ilości danych wymaganych przez aplikację i użytkownika. Duża liczba wierszy lub kolumn albo złożone kryteria filtrowania zużywają więcej tokenów limitu. Dłuższe zakresy dat są zwykle droższe (np. zmiana zakresu dat z 28 dni na 365 dni może zużyć 3 razy więcej tokenów limitu). W miarę możliwości możesz też używać wymiarów o mniejszej mocy zbioru (np. wysyłać żądanie dateHour zamiast dateHourMinute).
• Skuteczne wykorzystanie parametru limit: zmiana parametru limit w żądaniu do interfejsu API w celu zmniejszenia liczby zwracanych wierszy nie ma znaczącego wpływu na liczbę wykorzystanych tokenów limitu. Na przykład 5 żądań z limitami 10 tys. wierszy może zużyć 5 razy więcej tokenów przydziału niż 1 żądanie z limitem 50 tys.
• Korzystanie z odpowiedniej kategorii metod: jak wspomnieliśmy powyżej, limity przydziału są rozdzielone na 3 kategorie metod. Używanie odpowiedniej metody w odpowiednim przypadku może pozwolić zaoszczędzić limit w innych kategoriach. Na przykład zamiast tworzyć własną ścieżkę w aplikacji za pomocą danych z metod podstawowych, użyj metody runFunnelReport.
• Aktualizowanie ustawień domyślnych: podczas tworzenia lub dostosowywania raportów niestandardowych na Twojej platformie użytkownicy mogą nie aktualizować opcji domyślnych prezentowanych przez Twoją aplikację i zmieniać je tylko w czasie działania programu. Jeśli Twoja aplikacja ma domyślny zakres dat wynoszący 365 dni, a użytkownik zwykle przegląda raport z 28 dni, regularnie będziesz wykorzystywać więcej limitu niż jest to konieczne. Ogranicz zakresy i wybory w ustawieniach domyślnych i pozwól użytkownikom wybrać optymalne ustawienia dla ich przypadków użycia. W niektórych przypadkach możesz też ograniczyć, które ustawienia domyślne mogą być zmieniane przez użytkowników.
• Kolejkowanie żądań i leniwe ładowanie: pamiętaj o limicie tokenów Concurrent Requests Per Property (Równoczesne żądania dotyczące usługi). Aplikacja nie powinna wysyłać zbyt wielu żądań jednocześnie. Jeśli Twoja aplikacja ma dużą liczbę elementów interfejsu, co powoduje znaczną liczbę żądań do interfejsu API, rozważ podział interfejsu na strony, leniwe ładowanie i kolejkowanie żądań z wzrastającym czasem do ponowienia w przypadku ponownych prób. Użyj metody returnPropertyQuota, aby aktywnie monitorować wykorzystanie tokenów Równoczesne żądania dotyczące usługi w aplikacji.

Zarządzanie wrażeniami i oczekiwaniami użytkowników

• Przekazuj użytkownikom opinie, zanim uruchomią zapytania, które mogą zużywać dużo tokenów. Na przykład zapytania z wieloma wymiarami o dużej mocy zbioru lub z długim okresem mogą wykorzystywać dużą liczbę tokenów. Wyświetlanie ostrzeżenia i prośby o potwierdzenie w przypadku takich zapytań może zapobiec wprowadzaniu przez użytkowników niepotrzebnych zmian w raportach i pomóc im ograniczyć zakres zapytań.
• W przypadku dostosowanych rozwiązań raportowania zapewnij użytkownikom możliwość zrozumienia wykorzystania zapytań w odniesieniu do każdego elementu raportu. Możesz na przykład udostępnić widok debugowania z listą wykorzystania tokenów limitu dla każdego elementu raportu.
• Przekaż opinię na temat konkretnego typu błędu związanego z limitem i określ działanie, które powinien podjąć użytkownik.
• Usługi w Google Analytics 360 mają 5–10 razy wyższy limit niż usługi standardowe, co zapewnia większą elastyczność w przypadku usług w Google Analytics 360.

Zwiększenie limitów interfejsu Data API powyżej limitów domyślnych nie jest dostępne w przypadku interfejsu Data API w Google Analytics 4. Usługa Google Analytics 360 zapewnia wyższe limity dla usług w Google Analytics 4. Jeśli użytkownicy przekraczają limity nawet po wdrożeniu sprawdzonych metod, powinni rozważyć przejście na wersję 360. Użytkownicy mogą też skorzystać z BigQuery Export z Google Analytics. Umożliwi to użytkownikom eksportowanie danych na poziomie zdarzenia do BigQuery i przeprowadzanie własnych analiz.

Jeśli masz dodatkowe pytania dotyczące limitów interfejsu Data API, odwiedź GA Discord lub zadaj pytanie na Stack Overflow. Jeśli masz konkretne prośby o dodanie funkcji dotyczące interfejsu Data API, możesz je opublikować w naszym narzędziu do śledzenia problemów.