API-Limits und ‑Kontingente

In der Google Ads API gelten Limits für API-Vorgänge, z. B. für die Anzahl der Vorgänge, die in einer einzelnen Mutationsanfrage gesendet werden können. In der folgenden Tabelle sind einige der wichtigsten Limits und Kontingente zusammengefasst, die Sie beachten sollten.

Anfragetyp, Einschränkung und Fehlercode
Vorgänge mit der Zugriffsebene „Test“ 15.000 API-Vorgänge pro Tag für Testkonten RESOURCE_EXHAUSTED
Vorgänge mit der Zugriffsebene „Explorer“ 2.880 API-Vorgänge pro Tag für Produktionskonten
15.000 API-Vorgänge pro Tag für Testkonten 		RESOURCE_EXHAUSTED
Vorgänge mit der Zugriffsebene „Basic“ 15.000 API-Vorgänge pro Tag für Test- und Produktionskonten RESOURCE_EXHAUSTED
Vorgänge mit der Zugriffsebene „Standard“ Unbegrenzte Anzahl von API-Vorgängen pro Tag für Test- und Produktionskonten –
Mutationsanfragen 10.000 Mutationsvorgänge pro Anfrage TOO_MANY_MUTATE_OPERATIONS
Anfragen an den Planungsdienst 1 Abfrage pro Sekunde RESOURCE_EXHAUSTED
Anfragen an den Conversion Upload Service 2.000 Conversions pro Anfrage TOO_MANY_CONVERSIONS_IN_REQUEST
Anfragen an den Abrechnungs- und Kontobudgetdienst 1 Vorgang pro Mutationsanfrage TOO_MANY_MUTATE_OPERATIONS

Tägliche Limits für API-Vorgänge

Die täglichen API-Nutzungslimits basieren auf der Anzahl der API-Vorgänge, die von Ihrem Google Cloud-Projekt ausgeführt werden. API-Vorgänge sind die Summe aller Search- und SearchStream-Anfragen, einzelner Änderungsanfragen und anderer Dienstanfragen. Die Limits für tägliche API-Vorgänge hängen von der API-Zugriffsebene Ihres Google Cloud-Projekts ab. Im Leitfaden zu Zugriffsebenen und zulässiger Nutzung werden die spezifischen API-Vorgangslimits für jede Zugriffsebene beschrieben.

Anfragen, die gegen diese Limits verstoßen, werden mit dem Fehler RESOURCE_EXHAUSTED abgelehnt.

gRPC-Einschränkungen

Alle Clientbibliotheken der Google Ads API verwenden gRPC, um Anfragen und Antworten zu generieren. Standardmäßig hat gRPC eine Nachrichtengröße von 4 MB. Unsere Clientbibliotheken legen die maximale Nachrichtengröße jedoch auf 64 MB fest, um die Effizienz zu steigern.

Antworten dürfen dieses Limit nicht überschreiten. Eine Suchanfrage mit vielen Feldern kann beispielsweise eine Antwort generieren, die größer als 64 MB ist. Um dieses Limit zu vermeiden, können Sie die Anzahl der ausgewählten Felder reduzieren oder Streaming verwenden. Senden Sie bei Mutate-Anfragen weniger Vorgänge pro Anfrage.

Anfragen, die gegen diese Einschränkung verstoßen, generieren keine GoogleAdsError, sondern einen RESOURCE_EXHAUSTED-Fehler (gRPC-Code 8 / HTTP 429). Liste der gRPC-Fehlercodes und -Meldungen

Mutationsanfragen

Zusätzlich zur Anrechnung auf das tägliche Vorgangskontingent des Nutzers darf eine Mutationsanfrage nicht mehr als 10.000 Mutationsvorgänge pro Anfrage enthalten. Anfragen, die gegen diese Einschränkung verstoßen, werden mit dem Fehler TOO_MANY_MUTATE_OPERATIONS abgelehnt.

Im Folgenden werden zusätzliche Limits und Überlegungen für bestimmte Dienste und Anfragetypen beschrieben.

Suchanfragen

Eine Search- oder SearchStream-Anfrage wird als ein Vorgang auf das tägliche Vorgangskontingent des Nutzers angerechnet. Eine SearchStream-Anfrage zählt als ein API-Vorgang, unabhängig von der Anzahl der Batches.

Anfragen mit Seitenaufteilung

Seitenweise Anfragen (z. B. Anfragen, die ein gültiges next_page_token enthalten) werden nicht auf das tägliche Vorgangskontingent eines Nutzers angerechnet. Paginierungsanfragen, die ein abgelaufenes oder ungültiges Seitentoken enthalten, generieren jedoch eine Ausnahme und werden auf das tägliche Vorgangskontingent angerechnet.

Weitere Informationen zur Paginierung finden Sie unter In Ergebnissen suchen.

Andere Arten von Anfragen

Eine Anfrage, die keine Mutate-, Search- oder SearchStream-Anfrage ist, wird als ein Vorgang auf das tägliche Vorgangskontingent des Nutzers angerechnet.

Hier einige Beispiele für solche Anfragen:

Anfragen, die API-Ausnahmen zurückgeben

Anfragen, die mit GoogleAdsFailure abgelehnt werden, werden weiterhin auf das tägliche Vorgangskontingent des Nutzers angerechnet.

Anfragen, die fehlschlagen, aber keinen GoogleAdsFailure zurückgeben, z. B. aufgrund eines Fehlers auf Netzwerkebene, werden nicht auf das tägliche Vorgangskontingent des Nutzers angerechnet, da die Anfragen den Dienst nie erreichen. Ein Beispiel hierfür ist ein Netzwerkausfall.

Keyword-Planungsdienst

Aufgrund der Kosten und der Komplexität gelten für die folgenden Methoden des Keyword-Planer-Dienstes andere Limits als für andere Arten von Anfragen.

Beachten Sie diese Limits, wenn Sie einen Keyword-Plan erstellen.

Keyword-Plan-Objekt Maximale Anzahl
KeywordPlan pro Konto 10.000
KeywordPlanAdGroup pro KeywordPlan 200
KeywordPlanAdGroupKeyword pro KeywordPlan 10.000
KeywordPlanCampaignKeyword (auszuschließende Keywords) pro KeywordPlan 1.000
KeywordPlanCampaign pro KeywordPlan 1

Dienst für Zielgruppeninformationen

Die folgenden Methoden in AudienceInsightsService unterliegen bestimmten Kontingentlimits.

Conversion-Upload-Dienst

Dienst zum Hochladen von Conversion-Anpassungen

Regeln für Conversion-Wert

Wenn für das Konto bereits ein ConversionValueRuleSet mit einem attachment_type von CUSTOMER vorhanden ist, müssen Sie alle neuen Conversion-Wert-Regeln diesem Satz hinzufügen, damit sie aktiv werden. Wenn kein solcher Conversion-Wert-Regelsatz vorhanden ist, müssen Sie einen erstellen und Ihre Conversion-Wert-Regeln hinzufügen, wie unter Regelsätze erstellen beschrieben.

Abrechnungs- und Kontobudgetdienste

  • Änderungen können nur für Konten vorgenommen werden, die für die monatliche Rechnungsstellung konfiguriert sind.

    Anfragen, die gegen diese Einschränkung verstoßen, werden mit dem Fehler MUTATE_NOT_ALLOWED abgelehnt.

  • Für Mutationsanfragen ist nur 1 Vorgang zulässig.

    Anfragen, die gegen diese Einschränkung verstoßen, werden mit dem Fehler TOO_MANY_MUTATE_OPERATIONS abgelehnt.

  • Sie sollten mindestens 12 Stunden warten, bevor Sie Änderungen am Kontobudget (AccountBudget oder AccountBudgetProposal) für dasselbe Konto vornehmen. Wenn Sie Änderungen vornehmen, bevor 12 Stunden vergangen sind, kann es zu nicht wiederherstellbaren Fehlern kommen, die nur von Ihrem Google Ads-Konto-Kundenbetreuer behoben werden können.

Einladungen zu Kundenkonten

Neue Nutzer können mit dem CustomerUserAccessInvitationService zu bestehenden Kundenkonten eingeladen werden. Da mit dieser Funktion E‑Mail-Einladungen an andere Nutzer gesendet werden, besteht die Möglichkeit, dass sie missbraucht wird. Daher gelten für ihr Verhalten Einschränkungen:

  • Nutzer können nicht mehr als eine ausstehende Einladung für dasselbe Kundenkonto erhalten. Wenn eine nachfolgende Anfrage zum Senden einer Einladung an einen Nutzer gestellt wird, der bereits eine ausstehende Einladung hat, wird dieser Fehler zurückgegeben: EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • Für Kundenkonten können nicht mehr als 70 Einladungen gleichzeitig ausstehen. Wenn eine Anfrage gesendet wird, die diesen Wert überschreitet, wird der folgende Fehler zurückgegeben: PENDING_INVITATIONS_LIMIT_EXCEEDED.

Nutzerdaten

Nutzerdaten werden mit UserDataService und OfflineUserDataJobService verwaltet.

Jedes UserData-Objekt in einem create- oder remove-Vorgang bezieht sich auf einen einzelnen Endnutzer. Das Feld user_identifiers innerhalb eines einzelnen UserData-Objekts ist auf maximal 20 Kennungen beschränkt. Wenn dieses Limit in einem einzelnen UserData-Objekt überschritten wird, führt dies zu einem OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS- oder UserDataError.TOO_MANY_USER_IDENTIFIERS-Fehler.

Nutzer mit mehr als 20 Kennungen verwalten

Wenn ein einzelner Endnutzer mehr als 20 Kennungen hat, die Sie hochladen müssen, sollten Sie diese Kennungen auf mehrere UserData-Objekte verteilen. Damit Google alle diese Kennungen demselben Endnutzer zuordnen kann, muss jedes UserData-Objekt für diesen Nutzer mindestens eine gemeinsame user_identifier enthalten, z. B. dieselbe hashed_email, hashed_phone_number oder third_party_user_id. Google verwendet diese gemeinsamen Kennungen, um die Informationen aus den separaten UserData-Vorgängen mit dem richtigen Endnutzerprofil zu verknüpfen und zusammenzuführen.

Wenn Sie personenidentifizierbare Informationen wie gehashte E-Mail-Adressen oder Telefonnummern verwenden, müssen diese gemäß den Anforderungen der Google Ads API normalisiert und gehasht werden (SHA-256, Kleinbuchstaben, keine Leerzeichen), um Verknüpfungsfehler zu vermeiden.

Wenn ein Nutzer beispielsweise 30 E-Mail-Adressen hat, können Sie zwei UserData-Objekte mit einer gemeinsamen third_party_user_id senden. Dabei werden thirdPartyUserId und die E-Mail-Adressen 1 bis 19 in das erste Objekt eingefügt, um das Limit von 20 Kennungen nicht zu überschreiten, und thirdPartyUserId und die E-Mail-Adressen 20 bis 30 in das zweite Objekt:

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

Das Gesamtlimit für user_identifiers für alle Vorgänge in einem einzelnen AddOfflineUserDataJobOperationsRequest beträgt 100.000 (ein OfflineUserDataJob kann mehrere AddOfflineUserDataJobOperationsRequest-Aufrufe akzeptieren, bis zu einem empfohlenen Maximum von 1.000.000 Vorgängen pro Job). Bei synchronen Uploads mit UploadUserDataRequest (UserDataService.UploadUserData) ist jede Anfrage auf maximal 10 Vorgänge und 100 user_identifiers für die gesamte Anfrage beschränkt.

Andere Arten von Limits

Ein wiederkehrendes Feld, z. B. eine Liste von Vorgängen, das zu viele Elemente in einer Anfrage enthält, kann den Fehler REQUEST_SIZE_LIMIT_EXCEEDED verursachen. Diese Fehlermeldung kann auch andere Ursachen haben.

Wenn Sie diese Einschränkung erreichen und Anfragen mit einem wiederkehrenden Feld stellen, versuchen Sie, die Anzahl der Elemente im wiederkehrenden Feld zu reduzieren, indem Sie die Liste der Vorgänge auf mehrere Mutationsanfragen aufteilen.

Bei einer GAQL-Abfrage beträgt die maximale Anzahl von Elementen in einer IN-Klausel 20.000. Wenn Sie dieses Limit überschreiten, wird der Fehler FILTER_HAS_TOO_MANY_VALUES zurückgegeben.

Zurück
Übersicht
Weiter
Systemlimits