Zarządzanie limitem interfejsu Google Analytics Data API

Minhaz Kazi, Developer Advocate, Google Analytics – luty 2023 r.

Jeśli tworzysz aplikacje, korzystając z interfejsu Google Analytics Data API, zapoznaj się z informacjami o limitach dla tego interfejsu API. Jeśli Twoja aplikacja jest dobrze zaprojektowana, prawdopodobieństwo osiągnięcia limitów dotyczących użytkowników jest mniejsze. Niektóre z odpowiednich sprawdzonych metod prowadzą też do wydajnych zapytań do interfejsu API. Może to przyspieszyć działanie raportów i paneli informacyjnych w aplikacji oraz poprawić komfort użytkowników. W tym artykule omówiono system limitów i sprawdzone metody wdrażania interfejsu Google Analytics Data API.

System limitów dla interfejsu Google Analytics Data API

Z Google Analytics korzystają miliony deweloperów i użytkowników, dlatego limity żądań do interfejsu API chronią system przed przetwarzaniem większej ilości danych, niż jest w stanie obsłużyć, przy jednoczesnym zapewnieniu sprawiedliwej dystrybucji zasobów systemowych. Interfejs Data API dla usług Google Analytics 4 korzysta z systemu zasobników tokenów do zarządzania limitami interfejsu API. Aby zrozumieć tę koncepcję: wyobraźmy sobie, że istnieje zasobnik, w którym może się znajdować maksymalna liczba tokenów. Każde żądanie API najpierw sprawdza zasobnik. Jeśli nie ma już tokenów, żądanie zakończy się niepowodzeniem. W przeciwnym razie żądanie zostanie wykonane i wykorzysta co najmniej 1 token z zasobnika w zależności od złożoności żądania. Tokeny są uzupełniane w zasobniku do maksymalnej wartości w stałych odstępach czasu.

W zależności od używanej metody interfejsu Data API obowiązują 3 osobne kategorie:

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

Metody interfejsu Data API sprawdzą też wiele zasobników pod kątem tokenów limitów:

1. Na usługę na dzień
2. Za usługę na godzinę
3. Na projekt na usługę na godzinę
4. Liczba równoczesnych żądań na usługę
5. Liczba błędów serwera na projekt na usługę na godzinę

Te 5 zasobników jest sprawdzanych za każdym razem, gdy do usługi dociera żądanie do interfejsu Data API. Jeśli którykolwiek z zasobników jest pusty, żądanie natychmiast kończy się niepowodzeniem i zwraca błąd 429. Jeśli żaden z zasobników nie jest pusty, z zasobnika Żądania równoczesne na usługę zostanie wykorzystany pojedynczy token, a następnie zostanie wykonane żądanie do interfejsu API. W zależności od złożoności żądania po zakończeniu wykonywania zostanie zużywana pewna liczba tokenów z każdego z 3 pierwszych zasobników. W tym momencie zostanie też uzupełniony token równoczesnych żądań na usługę.

Limit Na projekt na usługę na godzinę zapewnia, że wyczerpanie limitu w przypadku co najmniej jednego użytkownika nie będzie miało wpływu na innych użytkowników aplikacji. W tym przypadku projekt odnosi się do projektu GCP aplikacji. Limit Na usługę na godzinę wynosi zwykle 4 razy więcej niż limit Na projekt na usługę na godzinę. Oznacza to, że w przypadku użytkowników końcowych dostęp do usługi muszą mieć co najmniej 4 różne projekty, zanim wyczerpie się limit Na usługę na godzinę. Egzekwowanie limitu na poziomie projektu i usługi zapewnia, że problemy z limitem są ograniczone do 1 usługi i nie mają wpływu na inne usługi, do których aplikacja ma dostęp.

Ostrzeżenie: zdecydowanie odradzamy programistom fragmentowanie tokenów limitów w wielu projektach 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 wygeneruje 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. Zaktualizowane informacje o limitach znajdziesz w artykule Limity interfejsu Google Analytics Data API. Na przykład metody podstawowe otrzymują 1250 tokenów limitu w zasobniku Na projekt na usługę na godzinę. Zakładając, że średnie żądanie z aplikacji wykorzystuje 10 tokenów limitu, aplikacja będzie w stanie wysłać 125 żądań podstawowych na godzinę w przypadku usługi standardowej i 10 razy więcej (1250 żądań podstawowych) w przypadku dowolnej usługi w Analytics 360. Wyższy limit tokenów to jedna z głównych zalet usług Analytics 360.

Ponieważ wykorzystanie tokenów w pierwszych 3 zasobnikach zależy od złożoności żądania, trudno jest przewidzieć dokładne wykorzystanie tokena przed wykonaniem żądania. Zwykle zwiększa to złożoność żądania, co skutkuje użyciem tokena:

• Prośba o więcej wymiarów
• Zapytanie o wyższy zakres czasowy
• Uwzględnia wymiary o większej mocy zbioru
• Wysyłanie zapytania do usługi z większą liczbą zdarzeń

Dlatego to samo zapytanie dotyczące 2 różnych usług może spowodować zupełnie inne wykorzystanie tokena, ponieważ moc zbioru wymiarów może się zmieniać lub natężenie ruchu. Możesz się jednak spodziewać, że usługi o podobnym poziomie ruchu i podobnej konfiguracji będą korzystać z podobnego wykorzystania tokenów. Możesz używać tego założenia do prognozowania wykorzystania tokenów klienta na etapie planowania i projektowania aplikacji.

Uwaga: jeśli wcześniej zdarzyło Ci się korzystać z interfejsu Reporting API w Universal Analytics, zauważysz, że limit interfejsu Reporting API wymusza limit na poziomie projektu aplikacji/API. W przypadku interfejsu Data API egzekwowanie zasad odbywa się na poziomie usługi w Google Analytics i projektu interfejsu API.

Monitorowanie wykorzystania limitu

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

Wyślij prośbę

{
  "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",
  ...
}

Dzięki temu po każdym udanym żądaniu do interfejsu Data API możesz się spodziewać, że dane zostały użyte i ile limitu zostało dla danej usługi. Możesz też przekazać te informacje użytkownikowi za pomocą interfejsu aplikacji.

Uwaga: na obecnym etapie interfejsu Data API musisz wykonać żądanie do interfejsu API, aby odzyskać obiekt PropertyQuota. Jeśli usługa wyczerpała już zasobnik tokenów limitu, żądanie zakończy się niepowodzeniem i wyświetli się błąd 429, a odpowiedź nie będzie zawierać obiektu PropertyQuota. Jeśli Cię to dotyczy i uważasz, że w Twojej aplikacji przydałby się osobny sposób dostępu do informacji o limicie, daj +1 tej prośbie o funkcję w narzędziu do śledzenia problemów.

Zarządzanie limitami

Aby w pełni wykorzystać możliwości interfejsu Data API, zalecamy wdrożenie sprawdzonych metod zarządzania limitami opisanych poniżej. Pamiętaj też, że uaktualnienie usług do wersji 360 może zwiększyć ilość danych, do których uzyskujesz dostęp za pomocą interfejsu API.

sprawdzone metody

Istnieją 2 sposoby na zmniejszenie wykorzystania limitu przez aplikację:

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

Mając na uwadze te dwie zasady, możesz zastosować poniższe metody:

• Pamięć podręczna: wdrożenie warstwy buforowania poprawi zarówno użyteczność aplikacji, jak i zarządzanie jej limitem. Google Analytics będzie zapisywać żądania do interfejsu API w pamięci podręcznej, ale powtarzające się żądania nadal będą generować tokeny limitów. Zachowując odpowiedź interfejsu API w pamięci podręcznej, możesz znacznie zmniejszyć liczbę powtarzających się żądań. Na przykład dane częściowe dotyczące usług standardowych mogą mieć okres ważności pamięci podręcznej wynoszący co najmniej 4 godziny. Więcej informacji znajdziesz w artykule Częstotliwość aktualizacji danych w Google Analytics.
• Scalanie żądań: spróbuj scalić wiele żądań do interfejsu API w jedno. Na przykład 5 żądań danych w ciągu 2 dni może spowodować użycie 3 razy więcej tokenów przydziału w porównaniu z 1 żądaniem w okresie 10 dni. Jeśli masz wiele żądań, które różnią się tylko 1 wymiarem, rozważ ich scalenie w jedno żądanie.
• Upraszczanie żądań: ogranicz żądania do minimalnej ilości danych wymaganej przez aplikację i użytkownika. Duża liczba wierszy lub kolumn albo złożone kryteria filtrowania będą zajmować więcej tokenów limitów. Dłuższe zakresy dat są zwykle droższe (np. zmiana zakresu dat z 28 do 365 dni może spowodować 3-krotnie większe wykorzystanie tokenów limitów). W miarę możliwości możesz też używać wymiarów o mniejszej mocy zbioru (np. żądania dateHour zamiast dateHourMinute).
• Efektywne wykorzystanie limit: zmiana parametru limit w żądaniu do interfejsu API w celu zmniejszenia liczby zwracanych wierszy nie ma znaczącego wpływu na wykorzystywane tokeny limitów. Na przykład 5 żądań z limitem 10 tys. wierszy może wykorzystać 5 razy więcej tokenów limitu niż 1 żądanie z limitem 50 tys.
• Użycie właściwej kategorii metod: jak wspomnieliśmy powyżej, limity są podzielone na 3 kategorie metod. W zależności od konkretnego przypadku użycia dane można zaoszczędzić spokojnie w innych kategoriach. Na przykład zamiast tworzyć własną ścieżkę w aplikacji za pomocą danych z metod podstawowych, do tworzenia ścieżek używaj metody runFunnelReport.
• Zaktualizuj ustawienia domyślne: podczas tworzenia lub dostosowywania raportów na swojej platformie użytkownicy mogą nie zmieniać domyślnych opcji przedstawianych przez aplikację, a jedynie w czasie działania. Jeśli dla Twojej aplikacji domyślny zakres dat to 365 dni, a użytkownik zwykle przegląda raport obejmujący 28 dni, spowoduje to zużycie limitu w sposób regularnie wymagany. Rozważ ograniczenie zakresów i wyborów w ustawieniach domyślnych, tak aby użytkownicy mogli wybrać optymalne ustawienia do swoich potrzeb. W niektórych przypadkach możesz też ograniczyć zakres wartości domyślnych, które mogą zmieniać użytkownicy.
• Żądania kolejki i leniwe ładowanie: pamiętaj o limicie żądań równoczesnych na usługę. Aplikacja nie powinna wysyłać zbyt wielu żądań w tym samym czasie. Jeśli Twoja aplikacja zawiera dużą liczbę elementów interfejsu, która powoduje znaczną liczbę żądań do interfejsu API, rozważ podzielenie interfejsu na strony, leniwe ładowanie i kolejkowanie żądań ze wzrastającym czasem ponowienia w przypadku ponownych prób. Metoda returnPropertyQuota umożliwia agresywne monitorowanie wykorzystania tokena równoczesnych żądań na usługę w aplikacji.

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

• Przekazuj użytkownikom opinie, zanim wykonają zapytania z potencjalnym dużym wykorzystaniem tokenów. Na przykład zapytania z wieloma wymiarami o dużej mocy zbioru lub długimi przedziałami czasu mogą używać dużej liczby tokenów. Podanie ostrzeżenia i prośby o potwierdzenie w przypadku takich zapytań może uniemożliwić użytkownikom wprowadzanie niepotrzebnych zmian w raportach i ograniczyć zakres do zapytań.
• W przypadku niestandardowych rozwiązań w zakresie raportowania musisz umożliwić użytkownikom zrozumienie wykorzystania zapytań przez poszczególne elementy w raporcie. Możesz na przykład udostępnić widok debugowania z listą wykorzystania tokenów limitu dla każdego elementu raportu.
• Prześlij opinię na temat konkretnego typu błędu limitu i zaleć działanie użytkownika.
• Usługi w Google Analytics 360 mają 5–10 razy większy limit niż usługi standardowe, dlatego usługi Google Analytics 360 zapewniają większą elastyczność.

Zwiększenie limitów interfejsu API powyżej limitów domyślnych nie jest możliwe w przypadku interfejsu Data API w Google Analytics 4. Google Analytics 360 zapewnia wyższe limity w usługach w Google Analytics 4. Jeśli po wdrożeniu sprawdzonych metod użytkownicy przekraczają limity, powinni rozważyć uaktualnienie usług do wersji 360. Użytkownicy mogą też skorzystać z eksportu Google Analytics do BigQuery. Dzięki temu użytkownicy będą mogli eksportować dane na poziomie zdarzenia do BigQuery i przeprowadzać własne analizy.

Jeśli masz więcej pytań na temat limitów interfejsu Data API, odwiedź GA Discord lub zadaj pytanie na Stack Overflow. Jeśli masz konkretne prośby o dodanie funkcji związane z interfejsem Data API, możesz opublikować je w naszym narzędziu do śledzenia problemów.