Kontingent für die Google Analytics Data API verwalten

Minhaz Kazi, Developer Advocate, Google Analytics – Februar 2023

Bei der Entwicklung von Anwendungen mit der Google Analytics Data API müssen Sie sollte verstehen, wie die Kontingente und Limits für die API funktionieren. Wenn Ihr gut konzipiert ist, ist es weniger wahrscheinlich, dass Nutzer Kontingentlimits erreichen. Einige von und die relevanten Best Practices zu leistungsfähigen Abfragen an die API führen. Dies kann Berichte und Dashboards in Ihrer Anwendung beschleunigen User Experience zu schaffen. In diesem Artikel werden das Kontingentsystem Best Practices für die Implementierung der Google Analytics Data API.

Informationen zum Kontingentsystem für die Google Analytics Data API

Da Google Analytics von Millionen von Entwicklern und Nutzern verwendet wird, Anfragen verhindern, dass das System mehr Daten verarbeitet, als es verarbeiten kann, eine gleichmäßige Verteilung der Systemressourcen. Das Daten-API für Google In Analytics 4-Properties wird ein Token-Bucket-System zur Verwaltung von API-Kontingenten verwendet. Bis Konzept verstehen: Stellen Sie sich einen Eimer vor, der ein Maximum an Anzahl der Tokens. Bei jeder API-Anfrage wird zuerst der Bucket geprüft. Wenn keine noch Tokens übrig haben, schlägt die Anfrage fehl. Andernfalls wird die Anfrage ausgeführt und ein oder mehrere Tokens aus dem Bucket verbrauchen, der Anfrage. Die Tokens werden im Bucket zu festen Zeiten bis zum Maximum aufgefüllt. Zeitintervallen.

Je nach Data API-Methode, die Sie verwenden, gibt es drei separate Kontingente, Kategorien:

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

Die Data API-Methoden prüfen mehrere Buckets auf Kontingenttokens:

1. Pro Property und Tag
2. Pro Unterkunft 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 immer überprüft, wenn eine Data API-Anfrage für eine Property. Wenn einer der Buckets leer ist, schlägt die Anfrage sofort fehl. mit dem Fehler 429. Wenn keiner der Buckets nicht leer ist, wird ein einzelner Token wird vom Bucket Gleichzeitige Anfragen pro Property verbraucht und wird die API-Anfrage ausgeführt. Je nach Komplexität der Anfrage Aus jedem der ersten drei Buckets wird eine bestimmte Anzahl von Tokens verbraucht. sobald die Ausführung abgeschlossen ist. Für Gleichzeitige Anfragen pro Property gilt auch um ein Token auffüllen zu lassen.

Mit dem Kontingent Pro Projekt, Property und Stunde wird sichergestellt, dass das Kontingent für hat ein oder mehrere Nutzer keine Auswirkungen auf die anderen Nutzer Ihrer Anwendung. Hier wird project bezieht sich auf das GCP-Projekt Ihrer Anwendung. Das Kontingent Pro Property und Stunde beträgt in der Regel das vierfache des Kontingents Pro Projekt, Property und Stunde. Zum Schluss Nutzer muss eine Property von mindestens vier verschiedenen Projekten Das Kontingent Pro Property und Stunde kann erschöpft sein. Kontingentdurchsetzung für beide Projekt- und Property-Ebene sicher, dass Kontingentprobleme auf einen einzigen und hat keine Auswirkungen auf andere Eigenschaften, auf die Ihre Anwendung zugreift.

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

Das Kontingent für Serverfehler bezieht sich auf API-Antworten mit 500 oder 503-Codes. Wenn Ihre Anwendung zu viele Fehler generiert, Serverfehler pro Projekt Property pro Stunde.

Alle Kontingenttokens werden in den angegebenen Intervallen bis zum Limit aufgefüllt. Weitere Informationen finden Sie unter Google Analytics Data API-Kontingente für aktualisierte Kontingentinformationen. Beispiel: Core-Methoden erhalten 1.250 Kontingenttokens im Bereich Pro Projekt,Property und Stunde. Bucket. Angenommen, eine durchschnittliche Anfrage von Ihrer Anwendung verbraucht 10 Kontingente Tokens verwenden, kann Ihre Anwendung für einen Zeitraum von Standard-Property und das 10-Fache dieses Betrags (1.250 Core-Anfragen) für beliebige Analytics-Properties 360-Property. Das höhere Kontingent-Tokenlimit ist eines der wichtigsten Vorteile von Analytics 360-Properties.

Da die Tokennutzung für die ersten drei Buckets von der Komplexität der Anfrage ist es schwierig, die genaue Tokennutzung vorherzusehen. Ausführung. Folgendes erhöht in der Regel die Komplexität einer Anfrage. Dies führt zur Tokennutzung:

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

Daher kann die gleiche Abfrage für zwei verschiedene Properties zu Tokennutzung komplett unterschiedlich, da die Kardinalität der Dimensionen variieren, oder das Volumen kann unterschiedlich sein. Sie können jedoch mit ähnlichem Traffic und ähnlicher Konfiguration, eine ähnliche Tokennutzung. Mit dieser Annahme können Sie die Nutzung von Kundentokens vorhersagen. in der Planungs- und Anwendungsdesignphase.

Hinweis :Wenn Sie die Reporting API für Universal Analytics verwendet haben, wird das von der Reporting API erzwungene Kontingent im Anwendungs-/API-Projekt angezeigt. Bei der Data API erfolgt die Erzwingung jedoch in der Google Analytics-Property. sowie auf API-Projektebene.

Kontingentnutzung überwachen

Um die Kontingentnutzung zu überwachen und diese Informationen an den Endnutzer zu übermitteln, können Sie "returnPropertyQuota": true zum API-Anfragetext. Daraufhin wird der Wert PropertyQuota-Objekt zusammen mit der API-Antwort. PropertyQuota-Objekt enthält die Verbrauchsmengen und den Status des verbleibenden Kontingents für alle fünf Buckets. Hier 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",
  ...
}

Daher können Sie nach jeder erfolgreichen Data API-Anfrage davon ausgehen, das von der Anfrage verbrauchte Kontingent und das für die Property verbleibende Kontingent. Es ist Sie können dem Nutzer diese Informationen auch über Ihre App zur Verfügung stellen. .

Hinweis: In der aktuellen Phase der Data API müssen Sie erfolgreich eine API-Anfrage zum Abrufen des PropertyQuota-Objekts. Wenn die Property bereits einen Kontingenttoken-Bucket erschöpft ist, schlägt Ihre Anfrage mit dem Fehler 429 fehl und der Antwort das PropertyQuota-Objekt nicht enthält. Wenn Sie von und ich bin der Meinung, dass Ihre Anwendung von einer separaten Möglichkeit profitieren würde, auf Kontingentinformationen zugreifen, +1 dieser Funktionsanfrage in der Problemverfolgung.

Kontingentverwaltung

Wir empfehlen Ihnen, die unten beschriebenen Best Practices für die Kontingentverwaltung zu implementieren, das Beste aus der Data API herauszuholen. Ebenfalls Wenn Sie Ihre Properties auf 360 upgraden, Daten, auf die über die API zugegriffen wird.

Best Practices

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

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

Hier sind die Best Practices, die Sie unter Berücksichtigung dieser beiden Prinzipien umsetzen können:

• Caching: Die Implementierung einer Caching-Ebene verbessert sowohl die Nutzerfreundlichkeit als auch Kontingentverwaltung für Ihre Anwendung. Google Analytics selbst speichert Ihre API-Anfragen, aber bei wiederholten Anfragen fallen weiterhin Kontingenttokens an. Von die API-Antwort im Cache zu speichern, können Sie die Anzahl der wiederholten -Anfragen. Für Standard-Properties können beispielsweise Daten zum Tagesverlauf 4 oder eine höhere Cache-Ablaufzeit haben. Siehe Datenaktualität für Google Analytics:
• Anfragen zusammenführen:Versuchen Sie, mehrere API-Anfragen zu einer einzigen zusammenzufassen. Bei 5 Datenanfragen in einem Zeitraum von 2 Tagen könnten z. B. 3 Mal Die Kontingenttokens im Vergleich zu einer Anfrage in einem Zeitraum von 10 Tagen. Wenn Sie mehrere Anfragen, die sich nur in einer Dimension unterscheiden, sollten Sie eine Zusammenführung in einer einzigen Anfrage zusammenfassen.
• Anfragen vereinfachen:Anfragen auf ein Minimum an Daten beschränken die für Ihre Anwendung und den Nutzer erforderlich sind. Eine große Anzahl von Zeilen/Spalten komplexe Filterkriterien verbrauchen mehr Kontingenttokens. Längere Zeiträume sind in der Regel teurer (z. B. Änderung des Zeitraums von 28 Tagen in 365 Tage). Tage können das Dreifache der Kontingenttokens verbrauchen. Sie können auch erwägen, Dimensionen mit niedrigerer Kardinalität nach Möglichkeit verwenden (z.B. dateHour anfordern) statt dateHourMinute).
• Effektive Nutzung von limit:limit in der API ändern Die Anfrage zum Reduzieren der Anzahl der zurückgegebenen Zeilen hat keinen großen Einfluss Verbrauchte Kontingenttokens. So können z. B. 5 Anfragen mit einem Limit von 10.000 Zeilen im Vergleich zu einer Anfrage mit einem Limit von 50.000 Kontingent-Tokens fünfmal so viele Kontingenttokens verbrauchen.
• Verwendung der richtigen Methodenkategorie: Wie bereits erwähnt, sind Kontingentlimits auf drei Methodenkategorien verteilt. Die richtige Methode für die Anwendungsfall kann ein Kontingent für andere Kategorien eingespart werden. Anstatt beispielsweise anhand von Daten aus Kernmethoden einen eigenen Trichter in Ihrer Anwendung erstellen, Verwenden Sie die Methode runFunnelReport zum Erstellen von Trichtern.
• Standardeinstellungen aktualisieren:Wenn Sie Berichte auf Ihrer kann es sein, dass Nutzer die Standardoptionen Ihrer und nur während der Laufzeit ändern. Wenn Ihre Anwendung über eine Standardzeitraum von 365 Tagen und der Nutzer sieht sich normalerweise den 28-Tage-Bericht an. verbraucht am Ende mehr Kontingente, als regelmäßig erforderlich sind. Sie können die Bereiche und Auswahlmöglichkeiten in den Standardeinstellungen einschränken und Nutzende die optimalen Einstellungen für ihre Anwendungsfälle auswählen. Oder in einigen Fällen Sie können auch einschränken, welche Standardeinstellungen die Nutzer ändern können.
• Anfragen in die Warteschlange stellen und Lazy Loading:Achten Sie auf die gleichzeitigen Tokenlimit für Anfragen pro Property Ihre Anwendung sollte keine zu viele Anfragen gleichzeitig. Wenn es in Ihrer App viele von UI-Elementen, die zu einer beträchtlichen Anzahl von API-Anfragen führen, sollten Sie Paginierung der Benutzeroberfläche, Lazy Loading und das Einstellen von Anfragen mit exponentieller Backoff für Wiederholungsversuche. Verwenden Sie die Methode returnPropertyQuota, um aggressiv vorgehen zu können. Sie können die Tokennutzung Ihrer Anwendung für Gleichzeitige Anfragen pro Property überwachen.

User Experience und Erwartungen verwalten

• Geben Sie Nutzern Feedback, bevor sie Abfragen mit potenziell hoher Tokennutzung ausführen. Das können z. B. Abfragen mit mehreren Dimensionen hoher Kardinalität oder kann eine große Anzahl von Tokens verwendet werden. Wenn Sie eine Warnung und einen zur Bestätigung solcher Anfragen, kann dies verhindern, Änderungen an Berichten vornehmen und den Umfang auf ihre Abfragen.
• Bieten Sie Nutzern für benutzerdefinierte Berichtslösungen die Möglichkeit, der einzelnen Elemente in ihrem Bericht abfragt. Sie können beispielsweise eine Debug-Ansicht, in der die Kontingenttoken-Nutzung für jedes Berichtselement aufgelistet wird.
• Feedback zur spezifischen Art des Kontingentfehlers geben und Nutzer verschreiben Aktion ausführen.
• Google Analytics 360-Properties haben ein 5- bis 10-mal höheres Kontingentlimit im Vergleich zu Standard-Properties bietet Google Analytics 360 Eigenschaften.

API-Kontingenterhöhungen über das Standardlimit hinaus sind für die Data API nicht möglich für Google Analytics 4 Google Analytics 360 bietet höhere Kontingente für Google Analytics 4-Properties. Wenn Ihre Nutzer das Kontingentlimit erreichen, Nach der Umsetzung von Best Practices sollte er sein Upgrade in Betracht ziehen, auf 360 umstellen. Eine weitere Option für die Nutzenden ist die Verwendung der BigQuery Export für Google Analytics Damit können Nutzer Daten auf Ereignisebene exportieren und eine eigene Analyse durchführen.

Bei weiteren Fragen zu den Data API-Kontingenten besuchen Sie Discord in GA oder auf Stack Overflow stellen. Wenn Sie bestimmte Funktionsanfragen in Bezug auf die Daten API erhalten, können Sie in unserem Issue Tracker posten.