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 zur Identifizierung des aufrufenden Projekts verbraucht, 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: „Kern-“, „Echtzeit-“, „Trichter-“ und „Chat-“.

Für API-Anfragen an Kernmethoden werden Kernkontingente berechnet. Für API-Anfragen an Echtzeitmethoden werden Echtzeitkontingente berechnet. Für API-Anfragen an Trichtermethoden werden Trichterkontingente berechnet. Für API-Anfragen an Chatmethoden werden Chatkontingente berechnet. Für jede Anfrage wird nur eine Art von Kontingent verbraucht.

Kontingente für Analytics-Properties

Für alle Anfragen werden Property-Kontingente verbraucht.

• Gleichzeitige Anfragen werden anhand der Anzahl der Anfragen gemessen, die gleichzeitig ausgeführt werden. Um die Anzahl gleichzeitiger Anfragen zu reduzieren, warten Sie, bis vorherige Anfragen abgeschlossen sind, bevor Sie weitere Anfragen senden.
• Serverfehler sind die Codes 500 und 503. 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 ausgeschöpft sind, werden alle Anfragen an die Property aus dem Projekt blockiert. Eine vollständige Liste der Fehlerantworten finden Sie unter Error Responses.
• Für jede Anfrage wird das Kontingent sowohl für „Tokens pro Property und Stunde“ als auch für „Tokens pro Projekt, Property und Stunde“ verbraucht. Das bedeutet, dass auf eine Property von mehr als drei Projekten zugegriffen werden muss, bevor das Kontingent „Tokens pro Property und Stunde“ vor dem Kontingent „Tokens pro Projekt, Property und Stunde“ ausgeschöpft sein kann.

Für Properties sind 120 potenziell schwellenwertbezogene Anfragen pro Stunde zulässig. Die Dimensionen userAgeBracket, userGender, brandingInterest, audienceId und audienceName sind potenziell schwellenwertbezogen. 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. Bei den meisten Anfragen werden 10 oder weniger Tokens berechnet, bei komplexeren Anfragen (z. B. „Ask Advisor“ chat -Abfragen) 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 sich auf die Anfrage selbst und die zugrunde liegenden Daten in der Google Analytics-Property beziehen. Diese Faktoren können zu höheren Kosten führen:

• Anzahl der Zeilen:Anfordern einer größeren Anzahl von Zeilen.
• Anzahl der Dimensionen und Messwerte:Einbeziehen einer größeren Anzahl von Dimensionen und Messwerten.
• Komplexität des Filters:Verwenden komplexer Filterausdrücke.
• Länge des Zeitraums:Abfragen über längere Zeiträume.
• Kardinalität der Daten: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 von 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 (wird in runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport und runFunnelReport unterstützt). Die API-Antwort enthält dann das PropertyQuota-Objekt, in dem die für diese spezifische Anfrage verbrauchten Tokens und die verbleibenden Kontingentsalden aufgeführt sind.

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
}

Beispielnutzlast der propertyQuota-Antwort

Wenn "returnPropertyQuota": true festgelegt ist, enthält die Antwort ein propertyQuota-Objekt, in dem jedes Feld einen QuotaStatus mit consumed und remaining Ganzzahlen 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 unter Kontingente für Analytics-Properties. Die Tokengebühr für eine einzelne API-Anfrage wird gleichzeitig von tokensPerDay, tokensPerHour und tokensPerProjectPerHour abgezogen. Wenn ein Kontingentbehälter 0 erreicht, wird bei nachfolgenden Anfragen an diese Property der Fehler 429 RESOURCE_EXHAUSTED zurückgegeben.

Best Practices zur Vermeidung von 429 RESOURCE_EXHAUSTED-Fehlern

• Dynamisches Überwachen von remaining Salden: Prüfen Sie propertyQuota.tokensPerProjectPerHour.remaining und propertyQuota.tokensPerHour.remaining in den Antworten und drosseln oder pausieren Sie nicht dringende Hintergrundjobs, wenn die verbleibenden Tokens unter einen Sicherheitsschwellenwert fallen.
• Batchanfragen:Verwenden Sie batchRunReports oder batchRunPivotReports um bis zu fünf Berichte in einem einzigen HTTP-Aufruf zu gruppieren und den HTTP-Round-Trip Overhead zu reduzieren. Jeder Bericht in einem Batch wird jedoch weiterhin einzeln auf die Kontingente für Tokens und concurrentRequests angerechnet.
• Komplexität und Kardinalität von Abfragen reduzieren:Beschränken Sie Anfragen auf die Dimensionen und Messwerte, die Sie benötigen, verkürzen Sie dateRanges nach Möglichkeit und vermeiden Sie die Kombination mehrerer Dimensionen mit hoher Kardinalität (z. B. pagePath oder fullPageUrl) in häufigen Abfragen.
• Anzahl gleichzeitiger Anfragen steuern:Stellen Sie Anfragen in die Warteschlange oder beschränken Sie die Größe des Worker-Pools, damit die Anzahl der Anfragen unter dem Limit für concurrentRequests bleibt (10 für Standard-Properties, 50 für Analytics 360-Properties).
• Exponentiellen Backoff mit Wiederholungslimits implementieren: Wenn eine Anfrage mit 429 RESOURCE_EXHAUSTED, 500 INTERNAL, oder 503 UNAVAILABLE fehlschlägt, versuchen Sie es mit abgeschnittenem exponentiellen Backoff noch einmal, wie unter Fehlerantworten beschrieben.

Chat-Tokenverbrauch und -überwachung

Bei chat Anfragen von „Ask Advisor“ stehen Tokens für die Kosten für Modellberechnungen, Schlussfolgerungen und den Abruf zugrunde liegender Daten. Der Verbrauch von Chat-Tokens wird durch Folgendes beeinflusst:

• Abfrage- und Analysebereich:Komplexität und Umfang der angeforderten Analyse.
• Tokens für Modell-Ein- und -Ausgabe:Umfang der verarbeiteten Kontextdaten und der generierten Antwort.
• Thinking-Token:Schritte zur Schlussfolgerung des Modells, die zum Zusammenfassen der Ergebnisse erforderlich sind.
• Ausführungslatenz:Verarbeitungszeit, die für mehrstufige Datenanalysen erforderlich ist.

Wenn Sie die Nutzung von Chat-Tokens überwachen möchten, legen Sie "returnPropertyQuota": true in Ihrer ChatRequest fest. Die Antwort enthält das PropertyChatQuota Objekt mit den Feldern tokensPerDay und tokensPerHour mit den verbrauchten und verbleibenden Salden.