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 mit der Funktionsweise der Kontingente und Limits für die API vertraut sein. Wenn Ihre Anwendung gut konzipiert ist, ist es weniger wahrscheinlich, dass Nutzer Kontingentlimits erreichen. Einige der relevanten Best Practices führen auch zu leistungsstarken Abfragen an die API. Dies kann Berichte und Dashboards in Ihrer Anwendung beschleunigen und die Nutzerfreundlichkeit verbessern. In diesem Artikel werden das Kontingentsystem und Best Practices für die Implementierung der Google Analytics Data API beschrieben.

Informationen zum Kontingentsystem für die Google Analytics Data API

Da Google Analytics von Millionen von Entwicklern und Nutzern verwendet wird, verhindern Kontingente für API-Anfragen das System, dass mehr Daten verarbeitet werden, als es verarbeiten kann. Gleichzeitig sorgt es für eine gleichmäßige Verteilung der Systemressourcen. Bei Data API for Google Analytics 4-Properties wird ein Token-Bucket-System zur Verwaltung von API-Kontingenten verwendet. Zum Verständnis: Stellen Sie sich vor, es gibt einen Bucket, der eine maximale Anzahl von Tokens enthalten kann. Zuerst wird der Bucket bei einer API-Anfrage geprüft. Wenn keine Tokens mehr übrig sind, schlägt die Anfrage fehl. Andernfalls wird die Anfrage ausgeführt und verbraucht je nach Komplexität der Anfrage ein oder mehrere Tokens aus dem Bucket. Die Tokens werden im Bucket in festen Zeitintervallen bis zum Maximum aufgefüllt.

Abhängig von der verwendeten Data API-Methode gibt es drei verschiedene Kontingentkategorien:

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

Außerdem prüfen die Data API-Methoden mehrere Buckets auf Kontingenttokens:

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 Buckets 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 fehl und der Fehler 429 wird angezeigt. Wenn keiner der Buckets leer ist, wird ein einzelnes Token aus dem Bucket Gleichzeitige Anfragen pro Attribut konsumiert und die API-Anfrage wird dann ausgeführt. Je nach Komplexität der Anfrage wird nach Abschluss der Ausführung eine bestimmte Anzahl an Tokens aus jedem der ersten drei Buckets verbraucht. Für Gleichzeitige Anfragen pro Attribut wird zu diesem Zeitpunkt außerdem ein Token aufgefüllt.

Das Kontingent Pro Projekt, Attribut und Stunde sorgt dafür, dass sich eine Erschöpfung des Kontingents für einen oder mehrere Nutzer nicht auf andere Nutzer Ihrer Anwendung auswirkt. Hier bezieht sich Projekt auf das GCP-Projekt Ihrer Anwendung. Das Kontingent Pro Attribut und Stunde beträgt in der Regel das Vierfache des Kontingents Pro Projekt, Attribut und Stunde. Für Endnutzer muss ein Attribut also von mindestens vier verschiedenen Projekten aufgerufen werden, bevor das Kontingent Pro Property und Stunde erschöpft ist. Durch die Erzwingung von Kontingenten auf Projekt- und Property-Ebene wird sichergestellt, dass Kontingentprobleme auf eine einzelne Property beschränkt sind und keine Auswirkungen auf andere Properties haben, auf die Ihre Anwendung zugreift.

Warnung: Entwicklern wird dringend davon abgeraten, Kontingenttokens über mehrere API-Projekte zu fragmentieren. Dies stellt einen Verstoß gegen die Nutzungsbedingungen für Google APIs dar.

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, ist das Kontingent Serverfehler pro Projekt, Attribut und Stunde ausgeschöpft.

Alle Kontingenttokens werden in festgelegten Intervallen bis zum Limit aufgefüllt. Aktualisierte Kontingentinformationen finden Sie unter Kontingente für die Google Analytics Data API. Beispielsweise erhalten Core-Methoden 1.250 Kontingenttokens im Bucket Pro Projekt, Attribut und Stunde. Bei einer durchschnittlichen Anfrage von 10 Kontingenttokens können über Ihre Anwendung für eine Standard-Property 125 Kernanfragen pro Stunde und für jede Analytics 360-Property das 10-Fache dieser Menge (1.250 Core-Anfragen) ausgeführt werden. Das höhere Kontingenttokenlimit ist einer der größten Vorteile von Analytics 360-Properties.

Da die Tokennutzung für die ersten drei Buckets von der Komplexität der Anfrage abhängt, ist es schwierig, die genaue Tokennutzung vor der Ausführung der Anfrage vorherzusagen. Folgendes erhöht in der Regel die Komplexität einer Anfrage, was zur Verwendung von Tokens führt:

• Weitere Dimensionen anfordern
• Längerer Zeitraum abfragen
• Dimensionen mit höherer Kardinalität einschließen
• Property mit höherer Ereignisanzahl abfragen

Daher kann die gleiche Abfrage für zwei verschiedene Attribute zu einer völlig unterschiedlichen Tokennutzung führen, da die Kardinalität der Dimensionen oder das Trafficvolumen unterschiedlich sein kann. Sie können jedoch davon ausgehen, dass Attribute mit ähnlichem Traffic-Volumen und ähnlicher Konfiguration eine ähnliche Tokennutzung haben. Anhand dieser Annahme können Sie die Nutzung von Kundentokens während der Planungs- und Anwendungsentwicklungsphase vorhersagen.

Hinweis :Wenn Sie zuvor die Reporting API für Universal Analytics verwendet haben, werden Sie feststellen, dass die Reporting API das Kontingent auf Anwendungs-/API-Projektebene erzwungen hat. Bei der Data API erfolgt die Erzwingung jedoch auf Ebene der Google Analytics-Property sowie auf API-Projektebene.

Kontingentnutzung überwachen

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

Anfrage

{
  "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 können Sie also sehen, wie viel Kontingent die Anfrage verbraucht hat und wie viel Kontingent für die Property noch übrig ist. Sie können dem Nutzer diese Informationen auch über Ihre Anwendungsoberfläche bereitstellen.

Hinweis: In der aktuellen Phase der Data API müssen Sie eine API-Anfrage ausführen, um das PropertyQuota-Objekt zurückzugeben. Wenn das Attribut bereits einen Kontingenttoken-Bucket erschöpft hat, schlägt Ihre Anfrage mit dem Fehler 429 fehl und die Antwort enthält nicht das Objekt PropertyQuota. Wenn Sie davon betroffen sind und der Meinung sind, dass eine separate Möglichkeit für den Zugriff auf die Kontingentinformationen für Ihre Anwendung von Vorteil wäre, geben Sie dieser Funktionsanfrage in der Issue Tracker +1.

Kontingentverwaltung

Wir empfehlen, die unten aufgeführten Best Practices für die Kontingentverwaltung zu implementieren, um die Data API optimal zu nutzen. Wenn Sie für Ihre Properties außerdem ein Upgrade auf 360 durchführen, kann dadurch die Datenmenge erhöht werden, auf die über die API zugegriffen wird.

Best Practices

Es gibt grundsätzlich zwei Möglichkeiten, die Kontingentnutzung für Ihre Anwendung zu reduzieren:

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

Unter Berücksichtigung dieser beiden Prinzipien können Sie folgende Vorgehensweisen anwenden:

• Caching: Die Implementierung einer Caching-Ebene wirkt sich sowohl auf die Nutzerfreundlichkeit als auch auf die Kontingentverwaltung für Ihre Anwendung aus. Google Analytics selbst speichert Ihre API-Anfragen im Cache, wiederholte Anfragen verursachen jedoch weiterhin Kontingenttokens. Wenn Sie die API-Antwort im Cache speichern, können Sie die Anzahl wiederholter Anfragen drastisch reduzieren. Beispielsweise können Daten zum Tagesverlauf für Standardattribute eine Cache-Ablaufzeit von mindestens 4 Stunden haben. Siehe Datenaktualität für Google Analytics.
• Anfragen zusammenführen:Versuchen Sie, mehrere API-Anfragen zu einer einzigen Anfrage zusammenzuführen. Beispielsweise können 5 Datenanfragen innerhalb eines Zeitraums von 2 Tagen dreimal so viele Kontingenttokens verwenden wie bei einer Anfrage in einem Zeitraum von 10 Tagen. Wenn Sie mehrere Anfragen haben, die sich nur in einer einzigen Dimension unterscheiden, sollten Sie sie in einer einzigen Anfrage zusammenführen.
• Anfragen vereinfachen:Begrenzen Sie Ihre Anfragen auf die für Ihre Anwendung und den Nutzer erforderliche Mindestmenge an Daten. Eine große Anzahl von Zeilen/Spalten oder komplexe Filterkriterien verbrauchen mehr Kontingenttokens. Längere Zeiträume sind in der Regel teurer (z.B. kann eine Änderung des Zeitraums von 28 Tagen auf 365 Tage die Dreifache der Kontingenttokens erfordern). Sie können auch Dimensionen mit geringerer Kardinalität verwenden (z.B. dateHour statt dateHourMinute anfordern).
• Effektive Nutzung von limit:Wenn Sie limit in der API-Anfrage ändern, um die Anzahl der zurückgegebenen Zeilen zu reduzieren, wirkt sich das nicht wesentlich auf die verbrauchten Kontingenttokens aus. So können beispielsweise 5 Anfragen mit einem Limit von 10.000 Zeilen fünfmal so viele Kontingenttokens verbraucht werden wie eine Anfrage mit einem Limit von 50.000.
• Richtige Methodenkategorie verwenden: Wie bereits erwähnt, werden Kontingentlimits auf drei Methodenkategorien verteilt. Mit der richtigen Methode für den richtigen Anwendungsfall können Sie Kontingente für andere Kategorien sparen. Anstatt beispielsweise einen eigenen Trichter in Ihrer Anwendung mit Daten aus Core-Methoden zu erstellen, verwenden Sie die Methode runFunnelReport zum Erstellen von Trichtern.
• Standardeinstellungen aktualisieren:Wenn Nutzer Berichte auf Ihrer Plattform erstellen oder anpassen, aktualisieren sie die Standardoptionen Ihrer Anwendung möglicherweise nicht und ändern sie nur zur Laufzeit. Wenn Ihre Anwendung einen Standardzeitraum von 365 Tagen hat und sich der Nutzer normalerweise einen 28-Tage-Bericht ansieht, wird dadurch am Ende mehr Kontingent verbraucht als regelmäßig erforderlich. Sie können die Bereiche und die Auswahl in den Standardeinstellungen einschränken und Nutzern die Möglichkeit geben, die optimalen Einstellungen für ihre Anwendungsfälle auszuwählen. In einigen Fällen können Sie auch einschränken, welche Standardeinstellungen die Nutzer ändern können.
• Anfragen in Wiedergabeliste und Lazy Loading:Beachten Sie 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 großen Anzahl von API-Anfragen führt, sollten Sie die Seitennummerierung, das Lazy Loading und die Bereitstellung von Anfragen mit exponentiellem Backoff für Wiederholungsversuche in Betracht ziehen. Verwenden Sie die Methode returnPropertyQuota, um die Tokennutzung der Tokens für gleichzeitige Anfragen pro Attribut in Ihrer Anwendung aggressiv zu überwachen.

Umgang mit der User Experience und den Erwartungen

• Geben Sie Nutzern Feedback, bevor sie Abfragen mit potenziell hoher Tokennutzung ausführen. Beispielsweise können Abfragen mit mehreren Dimensionen mit hoher Kardinalität oder mit einem langen Zeitraum eine große Anzahl von Tokens verwenden. Wenn Sie für solche Abfragen eine Warnung und eine Bestätigungsaufforderung angeben, können Nutzer keine unnötigen Änderungen an Berichten vornehmen und den Umfang auf ihre Abfragen beschränken.
• Bieten Sie Nutzern bei benutzerdefinierten Berichtslösungen die Möglichkeit, die Abfragenutzung der einzelnen Elemente in ihrem Bericht nachzuvollziehen. Sie können beispielsweise eine Debug-Ansicht bereitstellen, in der die Kontingenttokennutzung für jedes Berichtselement aufgeführt ist.
• Geben Sie Feedback zu der jeweiligen Art des Kontingentfehlers und schreiben Sie dem Nutzer entsprechende Maßnahmen vor.
• Da für Google Analytics 360-Properties im Vergleich zu Standard-Properties das Kontingentlimit fünf- bis zehnmal überschritten wird, sind Sie mit Google Analytics 360-Properties flexibler.

Für die Data API für Google Analytics 4 ist keine Erhöhung des API-Kontingents über die Standardlimits möglich. In Google Analytics 360 gelten höhere Kontingente für Google Analytics 4-Properties. Wenn Ihre Nutzer trotz Anwendung der Best Practices die Kontingentlimits erreichen, sollten sie ein Upgrade ihrer Properties auf 360 in Betracht ziehen. Eine weitere Option für die Nutzer ist der BigQuery Export von Google Analytics. Damit können Nutzer Daten auf Ereignisebene nach BigQuery exportieren und ihre eigene Analyse ausführen.

Weitere Informationen zu den Data API-Kontingenten finden Sie auf GA Discord oder auf Stack Overflow. Wenn Sie bestimmte Funktionsanfragen zur Data API haben, können Sie diese in unserem Issue Tracker posten.