Kontingent für die Google Analytics Data API verwalten

Minhaz Kazi, Developer Advocate, Google Analytics – Februar 2023

Wenn Sie Anwendungen mit der [Google Analytics Data API] entwickeln, sollten Sie sich mit den Kontingenten und Limits der API vertraut machen. Wenn Ihre Anwendung gut konzipiert ist, ist es weniger wahrscheinlich, dass Nutzer Kontingentlimits erreichen. Einige der relevanten Best Practices führen auch zu leistungsstarken API-Abfragen. Dadurch können Berichte und Dashboards in Ihrer Anwendung beschleunigt und die Nutzerfreundlichkeit verbessert werden. In diesem Artikel werden das Kontingentsystem und Best Practices für die Implementierung der Google Analytics Data API beschrieben.

Kontingentsystem für die Google Analytics Data API

Da Google Analytics von Millionen von Entwicklern und Nutzern verwendet wird, schützen Kontingente für API-Anfragen das System davor, mehr Daten zu verarbeiten, als es bewältigen kann. Gleichzeitig wird so eine gerechte Verteilung der Systemressourcen gewährleistet. Für die Data API für Google Analytics 4-Properties wird ein Token-Bucket-System zur Verwaltung von API-Kontingenten verwendet. Stellen Sie sich das so vor: Es gibt einen Bucket, der eine maximale Anzahl von Tokens aufnehmen kann. Bei jeder API-Anfrage wird zuerst der Bucket geprüft. Wenn keine Tokens mehr vorhanden sind, schlägt die Anfrage fehl. Andernfalls wird die Anfrage ausgeführt und je nach Komplexität der Anfrage werden ein oder mehrere Tokens aus dem Bucket verbraucht. Die Tokens werden in festen Zeitintervallen im Bucket bis zum Maximum aufgefüllt.

Je nachdem, welche Data API-Methode Sie verwenden, gibt es drei separate Kontingentkategorien:

• Echtzeit (für runRealtimeReport)
• Trichter (für runFunnelReport)
• Core (für alle anderen Methoden)

Bei den Data API-Methoden werden mehrere Kontingent-Tokens geprüft:[Google Analytics Data API-Kontingente][quota tokens]:

1. Pro Property und Tag
2. Pro Property und Stunde
3. Pro Projekt, Property und Stunde
4. Gleichzeitige Anfragen pro Property
5. Serverfehler pro Projekt, Property und Stunde

Diese fünf Kategorien werden jedes Mal geprüft, wenn eine Data API-Anfrage für eine Property eingeht. Wenn einer der Buckets leer ist, schlägt die Anfrage sofort mit einem 429-Fehler fehl. Wenn keiner der Buckets leer ist, wird ein einzelnes Token aus dem Bucket Gleichzeitige Anfragen pro Property verwendet und die API-Anfrage wird ausgeführt. Je nach Komplexität der Anfrage wird nach Abschluss der Ausführung eine bestimmte Anzahl von Tokens aus den ersten drei Buckets verbraucht. Das Token für Gleichzeitige Anfragen pro Property wird zu diesem Zeitpunkt ebenfalls wieder aufgefüllt.

Das Kontingent Pro Projekt, pro Property, pro Stunde sorgt dafür, dass die Kontingentüberschreitung für einen oder mehrere Nutzer keine Auswirkungen auf andere Nutzer Ihrer Anwendung hat. Dabei bezieht sich project auf das GCP-Projekt Ihrer Anwendung. Das Kontingent Pro Property und Stunde ist in der Regel viermal so hoch wie das Kontingent Pro Projekt, Property und Stunde. Für Endnutzer muss also mindestens über vier verschiedene Projekte auf eine Property zugegriffen werden, bevor das Kontingent Pro Property und Stunde ausgeschöpft werden kann. Die Kontingentdurchsetzung auf Projekt- und Property-Ebene sorgt dafür, dass Kontingentprobleme auf eine einzelne Property beschränkt sind und sich nicht auf andere Properties auswirken, auf die Ihre Anwendung zugreift.

Warnung :Entwickler sollten Kontingent-Tokens nicht auf mehrere API-Projekte aufteilen. Dies verstößt gegen die Nutzungsbedingungen für Google APIs.

Das Kontingent für Serverfehler bezieht sich auf API-Antworten mit den Codes 500 oder 503. Wenn Ihre Anwendung beim Zugriff auf ein Attribut zu viele Fehler generiert, wird das Kontingent Serverfehler pro Projekt, Attribut und Stunde ausgeschöpft.

Alle Kontingent-Tokens werden in den angegebenen Intervallen auf das Limit aufgefüllt. Aktuelle Kontingentinformationen finden Sie unter [Google Analytics Data API-Kontingente]. Core-Methoden erhalten beispielsweise 1.250 Kontingent-Tokens im Bucket Pro Projekt, pro Property,pro Stunde. Angenommen, für eine durchschnittliche Anfrage Ihrer Anwendung werden 10 Kontingent-Tokens verbraucht. Dann kann Ihre Anwendung für eine Standard-Property 125 Core-Anfragen pro Stunde und für eine Analytics 360-Property das Zehnfache (1.250 Core-Anfragen) stellen. Das höhere Kontingentlimit für Tokens ist einer der Hauptvorteile von Analytics 360-Properties.

Da der Tokenverbrauch für die ersten drei Gruppen von der Komplexität der Anfrage abhängt, ist es schwierig, die genaue Tokennutzung vor der Ausführung der Anfrage vorherzusagen. Die folgenden Faktoren erhöhen in der Regel die Komplexität einer Anfrage und führen daher zu einer höheren Token-Nutzung:

• Weitere Dimensionen anfordern
• Abfragen eines längeren Zeitbereichs
• Dimensionen mit höherer Kardinalität einbeziehen
• Abfragen für eine Property mit einer höheren Anzahl von Ereignissen

Daher kann dieselbe Anfrage für zwei verschiedene Properties zu einer völlig unterschiedlichen Tokennutzung führen, da die Kardinalität der Dimensionen oder das Trafficvolumen unterschiedlich sein können. Bei Properties mit ähnlichem Traffic und ähnlicher Konfiguration ist jedoch mit einer ähnlichen Token-Nutzung zu rechnen. Sie können diese Annahme verwenden, um die Nutzung von Kundentokens während der Planungs- und Anwendungsdesignphasen vorherzusagen.

Hinweis :Wenn Sie die Reporting API für Universal Analytics bereits verwendet haben, werden Sie feststellen, dass das Kontingent auf Anwendungs-/API-Projektebene erzwungen wurde. Bei der Data API erfolgt die Erzwingung jedoch sowohl auf Google Analytics-Property- als auch auf API-Projektebene.

Kontingentnutzung überwachen

Wenn Sie die Kontingentnutzung im Blick behalten und diese Informationen an Ihre Endnutzer weitergeben möchten, können Sie "returnPropertyQuota": true in den API-Anfragetext einfügen. Dadurch wird das PropertyQuota-Objekt zusammen mit der API-Antwort zurückgegeben. Das PropertyQuota-Objekt enthält Verbrauchsbeträge und den Status des verbleibenden Kontingents für alle fünf Buckets. Hier sehen Sie ein Beispiel für einen Anfragetext und eine Antwort:

Ersuchen

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

Antwort

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

Nach jeder erfolgreichen Data API-Anfrage sehen Sie, wie viel Kontingent durch die Anfrage verbraucht wurde und wie viel Kontingent für die Property noch verfügbar ist. Sie können diese Informationen auch über die Benutzeroberfläche Ihrer Anwendung anzeigen.

Hinweis :In der aktuellen Phase der Data API müssen Sie eine API-Anfrage erfolgreich ausführen, um das PropertyQuota-Objekt zu erhalten. Wenn für die Property bereits ein Kontingent-Token-Bucket aufgebraucht ist, schlägt Ihre Anfrage mit einem 429-Fehler fehl und die Antwort enthält nicht das PropertyQuota-Objekt. Wenn Sie davon betroffen sind und der Meinung sind, dass Ihre Anwendung von einer separaten Möglichkeit zum Zugriff auf die Kontingentinformationen profitieren würde, geben Sie diesem Feature Request im Issue Tracker ein „+1“.

Kontingentverwaltung

Wir empfehlen, die unten beschriebenen Best Practices für die Kontingentverwaltung zu implementieren, um die Data API optimal zu nutzen. Wenn Sie ein Upgrade Ihrer Properties auf 360 durchführen, kann sich auch die Menge der über die API abgerufenen Daten erhöhen.

Best Practices

Es gibt im Wesentlichen zwei Möglichkeiten, die Kontingentnutzung für Ihre Anwendung zu reduzieren:

• Weniger API-Anfragen senden
• Weniger komplexe API-Anfragen senden

Hier sind einige Methoden, die Sie umsetzen können, wenn Sie diese beiden Grundsätze berücksichtigen:

• Caching:Die Implementierung einer Caching-Ebene wirkt sich positiv auf die Nutzerfreundlichkeit und die Kontingentverwaltung Ihrer Anwendung aus. Google Analytics speichert Ihre API-Anfragen im Cache. Bei wiederholten Anfragen werden jedoch weiterhin Kontingent-Tokens verbraucht. Durch das Zwischenspeichern der API-Antwort können Sie die Anzahl der wiederholten Anfragen drastisch reduzieren. So kann die Cache-Ablaufzeit für Daten zum Tagesverlauf für Standard-Properties beispielsweise vier Stunden oder mehr betragen. Datenaktualität für Google Analytics
• Anfragen zusammenführen:Versuchen Sie, mehrere API-Anfragen in einer einzigen zusammenzufassen. Wenn Sie beispielsweise innerhalb von zwei Tagen fünf Datenanfragen stellen, werden möglicherweise dreimal so viele Kontingent-Tokens verwendet wie bei einer Anfrage für einen Zeitraum von zehn Tagen. Wenn Sie mehrere Anfragen haben, die sich nur durch eine Dimension unterscheiden, sollten Sie sie in einer einzigen Anfrage zusammenführen.
• Anfragen vereinfachen:Beschränken Sie Ihre Anfragen auf die Mindestmenge an Daten, die für Ihre Anwendung und den Nutzer erforderlich sind. Eine große Anzahl von Zeilen/Spalten oder komplexe Filterkriterien verbrauchen mehr Kontingent-Tokens. Längere Zeiträume sind in der Regel teurer. Wenn Sie beispielsweise den Zeitraum von 28 Tagen auf 365 Tage ändern, kann das dreimal so viele Kontingent-Tokens kosten. Verwenden Sie nach Möglichkeit Dimensionen mit niedrigerer Kardinalität, z.B. dateHour anstelle von dateHourMinute.
• Effektive Nutzung von limit:Wenn Sie limit in der API-Anfrage ändern, um die Anzahl der zurückgegebenen Zeilen zu reduzieren, hat das keine wesentlichen Auswirkungen auf die Anzahl der verbrauchten Kontingent-Tokens. Wenn Sie beispielsweise fünf Anfragen mit einem Limit von 10.000 Zeilen senden, werden fünfmal so viele Kontingent-Tokens verbraucht wie bei einer Anfrage mit einem Limit von 50.000 Zeilen.
• Die richtige Methodenkategorie verwenden:Wie oben erwähnt, sind die Kontingentlimits auf drei Methodenkategorien verteilt. Wenn Sie die richtige Methode für den richtigen Anwendungsfall verwenden, können Sie Kontingent für weitere Kategorien sparen. Anstatt beispielsweise einen eigenen Trichter in Ihrer Anwendung mit Daten aus Core-Methoden zu erstellen, verwenden Sie die Methode runFunnelReport.
• Standardeinstellungen aktualisieren:Wenn Nutzer benutzerdefinierte Berichte auf Ihrer Plattform erstellen oder anpassen, aktualisieren sie möglicherweise nicht die Standardoptionen, die von Ihrer Anwendung präsentiert werden, sondern ändern sie nur zur Laufzeit. Wenn Ihre Anwendung einen Standardzeitraum von 365 Tagen hat und der Nutzer sich normalerweise Berichte für 28 Tage ansieht, wird regelmäßig mehr Kontingent verbraucht als erforderlich. Beschränken Sie die Bereiche und Auswahlmöglichkeiten in den Standardeinstellungen und lassen Sie die Nutzer die optimalen Einstellungen für ihre Anwendungsfälle auswählen. In einigen Fällen können Sie auch einschränken, welche Standardeinstellungen die Nutzer ändern können.
• Anfragen in die Warteschlange stellen und Lazy Loading verwenden:Achten Sie auf das Tokenlimit für gleichzeitige Anfragen pro Property. Ihre Anwendung sollte nicht zu viele Anfragen gleichzeitig senden. Wenn Ihre Anwendung eine große Anzahl von UI-Elementen hat, die zu einer erheblichen Anzahl von API-Anfragen führen, sollten Sie die Benutzeroberfläche paginieren, Lazy Loading verwenden und Anfragen mit exponentiellem Backoff für Wiederholungsversuche in die Warteschlange stellen. Verwenden Sie die returnPropertyQuota-Methode, um die Tokennutzung Ihrer Anwendung für Gleichzeitige Anfragen pro Property genau zu überwachen.

Nutzerfreundlichkeit und Erwartungen verwalten

• Geben Sie Nutzern Feedback, bevor sie Abfragen mit potenziell hohem Tokenverbrauch ausführen. Für Abfragen mit mehreren Dimensionen mit hoher Kardinalität oder mit einem großen Zeitraum kann beispielsweise eine große Anzahl von Tokens erforderlich sein. Wenn Nutzer bei solchen Anfragen eine Warnung und eine Bestätigungsaufforderung erhalten, können sie unnötige Änderungen an Berichten vermeiden und den Umfang ihrer Anfragen eingrenzen.
• Bei benutzerdefinierten Berichtslösungen müssen Sie Nutzern die Möglichkeit geben, die Abfragenutzung der einzelnen Elemente in ihrem Bericht nachzuvollziehen. Sie können beispielsweise eine Debug-Ansicht bereitstellen, in der die Verwendung von Kontingent-Tokens für jedes Berichtselement aufgeführt ist.
• Geben Sie Feedback zum jeweiligen Kontingentfehler und weisen Sie den Nutzer auf die erforderlichen Maßnahmen hin.
• Da für Google Analytics 360-Properties das 5- bis 10-Fache des Kontingentlimits im Vergleich zu Standard-Properties gilt, haben Sie mit Google Analytics 360-Properties mehr Flexibilität.

API-Kontingenterhöhungen über die Standardlimits hinaus sind für die Data API für Google Analytics 4 nicht verfügbar. Für Google Analytics 360 gelten höhere Kontingente für Google Analytics 4-Properties. Wenn Ihre Nutzer die Kontingentlimits auch nach der Implementierung von Best Practices erreichen, sollten sie ein Upgrade ihrer Properties auf 360 in Betracht ziehen. Eine weitere Option für Nutzer ist der Google Analytics BigQuery Export. So können Nutzer Daten auf Ereignisebene nach BigQuery exportieren und eigene Analysen durchführen.

Wenn Sie weitere Fragen zu den Kontingenten der Data API haben, wenden Sie sich an GA Discord oder stellen Sie Ihre Frage auf Stack Overflow. Wenn Sie bestimmte Feature Requests zur Data API haben, können Sie diese in unserem Issue Tracker posten.