Limits und Kontingente der Data API

Für die Data API gelten die folgenden Limits und Kontingente.

Anwendung von Kontingenten

Für alle Anfragen an die Google Analytics Data API v1 ist ein Google Cloud-Projekt erforderlich. Außerdem gelten die auf dieser Seite beschriebenen Kontingente. Kontingente werden unabhängig von der Methode verbraucht, die zur Identifizierung des aufrufenden Projekts verwendet wird, einschließlich:

• Anfragen, die mit OAuth 2.0-Anmeldedaten authentifiziert wurden.
• Anfragen, die nur mit einem API-Schlüssel authentifiziert wurden.

API-Schlüssel werden verwendet, um eine Anfrage zu Kontingent- und Abrechnungszwecken mit einem bestimmten Google Cloud-Projekt zu verknüpfen. Alle API-Aufrufe, die mit Anmeldedaten oder einem API-Schlüssel aus Ihrem Projekt erfolgen, werden auf die entsprechenden Kontingente Ihres Projekts und der Google Analytics-Property angerechnet.

Kontingentkategorien

Die Data API hat vier Kontingentkategorien für Anfragen: Core, Realtime, Funnel und Chat.

API-Anfragen an Core-Methoden werden auf Core-Kontingente angerechnet. API-Anfragen an Echtzeitmethoden werden auf Echtzeitkontingente angerechnet. API-Anfragen an Trichter-Methoden werden auf die Trichter-Kontingente angerechnet. API-Anfragen an Chat-Methoden werden auf Chat-Kontingente angerechnet. Für jede Anfrage wird nur eine Art von Kontingent verbraucht.

Kontingente für Analytics-Properties

Alle Anfragen verbrauchen Property-Kontingente.

• Gleichzeitige Anfragen werden anhand der Anzahl der gleichzeitig ausgeführten Anfragen gemessen. Wenn Sie die Nebenläufigkeit von Anfragen reduzieren möchten, warten Sie, bis vorherige Anfragen abgeschlossen sind, bevor Sie weitere Anfragen senden.
• Serverfehler sind 500- und 503-Codes. Kontingente für Serverfehler werden nur berechnet, wenn eine Anfrage zu einem Serverfehler führt. Wenn die Kontingente für Serverfehler für ein Projekt- und Property-Paar erschöpft sind, werden alle Anfragen des Projekts an die Property blockiert. Eine vollständige Liste der Fehlerantworten finden Sie unter Fehlerantworten.
• Für jede Anfrage wird Kontingent für „Tokens pro Property pro Stunde“ und „Tokens pro Projekt pro Property pro Stunde“ verbraucht. Das bedeutet, dass auf eine Property von mehr als drei Projekten zugegriffen werden muss, damit das Kontingent „Tokens pro Property pro Stunde“ vor dem Kontingent „Tokens pro Projekt pro Property pro Stunde“ erschöpft ist.

Für Properties sind 120 Anfragen pro Stunde zulässig, die möglicherweise begrenzt sind. Für die Dimensionen userAgeBracket, userGender, brandingInterest, audienceId und audienceName können Grenzwerte gelten. Grenzwerte sollen verhindern, dass ein Betrachter eines Berichts Rückschlüsse auf demografische Merkmale oder Interessen eines bestimmten Nutzers ziehen kann.

Kontingent für Property-Tokens

Bei jeder Anfrage an die Google Analytics Data API v1 werden Tokens verbraucht. Die Anzahl der berechneten Tokens hängt von der Komplexität der Anfrage ab. Für die meisten Anfragen werden 10 oder weniger Tokens berechnet. Komplexere Anfragen (z. B. chat-Anfragen an Ask Advisor) verbrauchen mehr.

Faktoren, die den Tokenverbrauch beeinflussen

Die genauen Tokenkosten für eine Anfrage werden zum Zeitpunkt der Ausführung ermittelt, was eine genaue Vorabberechnung erschwert. Die Kosten werden durch eine Kombination von Faktoren beeinflusst, die mit der Anfrage selbst und den zugrunde liegenden Daten in der Google Analytics-Property zusammenhängen. Diese Faktoren können zu höheren Kosten führen:

• Anzahl der Zeilen: Es wird eine größere Anzahl von Zeilen angefordert.
• Anzahl der Dimensionen und Messwerte: Es werden mehr Dimensionen und Messwerte einbezogen.
• Filterkomplexität: Verwendung komplexer Filterausdrücke.
• Länge des Zeitraums: Abfragen über längere Zeiträume.
• Datenkardinalität: Dimensionen mit hoher Kardinalität (viele eindeutige Werte, z. B. pagePath, benutzerdefinierte Dimensionen) können die Tokenkosten erheblich erhöhen.
• Ereignisvolumen der Property: Bei Abfragen für Properties mit einem höheren Ereignisvolumen werden möglicherweise mehr Tokens verbraucht als bei derselben Abfrage für eine Property mit weniger Daten.

Tokennutzung überwachen

Die effektivste Methode, um die Tokenkosten für Ihre spezifischen API-Aufrufe zu ermitteln, besteht darin, den Parameter "returnPropertyQuota": true in den Anfragetext aufzunehmen (unterstützt in runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport und runFunnelReport). Die API-Antwort enthält dann das Objekt PropertyQuota, das die von dieser spezifischen Anfrage verbrauchten Token und das verbleibende Kontingent detailliert aufführt.

Beispielanfrage mit returnPropertyQuota

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}

Beispiel für eine propertyQuota-Antwortnutzlast

Wenn "returnPropertyQuota": true festgelegt ist, enthält die Antwort ein propertyQuota-Objekt, wobei jedes Feld ein QuotaStatus mit den Ganzzahlen consumed und remaining enthält:

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

Jedes Feld in propertyQuota entspricht einem Kontingent in Kontingente für Analytics-Properties. Die Tokengebühr für eine einzelne API-Anfrage wird gleichzeitig von tokensPerDay, tokensPerHour und tokensPerProjectPerHour abgezogen. Wenn ein Kontingent-Bucket 0 erreicht, geben nachfolgende Anfragen an diese Property den Fehler 429 RESOURCE_EXHAUSTED zurück.

Best Practices zur Vermeidung von 429 RESOURCE_EXHAUSTED-Fehlern

• remaining-Guthaben dynamisch überwachen: Prüfen Sie propertyQuota.tokensPerProjectPerHour.remaining und propertyQuota.tokensPerHour.remaining in Antworten und drosseln oder pausieren Sie nicht dringende Hintergrundjobs, wenn die verbleibenden Tokens unter einen Sicherheitsgrenzwert fallen.
• Zusammengehörige Abfragen im Batchmodus ausführen: Verwenden Sie batchRunReports oder batchRunPivotReports, um bis zu 5 Berichte in einem einzigen HTTP-Aufruf zu gruppieren und den HTTP-Roundtrip-Overhead zu reduzieren. Beachten Sie, dass jeder Bericht in einem Batch weiterhin einzeln auf die Token- und concurrentRequests-Kontingente angerechnet wird.
• Abfragekomplexität und Kardinalität reduzieren: Beschränken Sie Anfragen auf die Dimensionen und Messwerte, die Sie benötigen, kürzen Sie dateRanges, wo möglich, und vermeiden Sie es, mehrere Dimensionen mit hoher Kardinalität (z. B. pagePath oder fullPageUrl) in häufigen Abfragen zu kombinieren.
• Gleichzeitigkeit von Anfragen steuern: Stellen Sie Anfragen in die Warteschlange oder begrenzen Sie die Größe des Worker-Pools, damit die Anzahl der laufenden Anfragen unter dem Limit von concurrentRequests bleibt (10 für Standard, 50 für Analytics 360).
• Exponentiellen Backoff mit Wiederholungslimits implementieren: Wenn eine Anfrage mit 429 RESOURCE_EXHAUSTED, 500 INTERNAL oder 503 UNAVAILABLE fehlschlägt, versuchen Sie es mit abgeschnittenem exponentiellem Backoff, wie unter Fehlerantworten beschrieben.

Chat-Token-Verbrauch und -Monitoring

Bei chat-Anfragen an Ask Advisor stehen Tokens für die Kosten für Modellberechnung, Argumentation und Abruf der zugrunde liegenden Daten. Der Verbrauch von Chat-Tokens wird durch Folgendes beeinflusst:

• Abfrage- und Analyseumfang: Komplexität und Breite der angeforderten Analyse.
• Modelleingabe- und -ausgabetokens: Menge der verarbeiteten Kontextdaten und der generierten Antwort.
• Thinking-Tokens: Die Reasoning-Schritte des Modells, die erforderlich sind, um die Ergebnisse zusammenzufassen.
• Ausführungslatenz: Verarbeitungszeit, die für mehrstufige Datenexplorationen erforderlich ist.

Wenn Sie die Nutzung von Chat-Tokens im Blick behalten möchten, legen Sie "returnPropertyQuota": true in Ihrer ChatRequest fest. Die Antwort enthält das Objekt PropertyChatQuota mit den Feldern tokensPerDay und tokensPerHour, die das verbrauchte und das verbleibende Guthaben enthalten.