Ratenbegrenzungen

Um Nutzern der AdWords API weltweit zuverlässige Dienste anzubieten, verwenden wir einen Token Bucket-Algorithmus, um die Anzahl der Anfragen zu messen und die Rate der Anfragen pro Sekunde (Queries per Second, QPS) zu bestimmen. This is intended to prevent malicious or out‒of-control software from overwhelming the AdWords API servers and affecting other users.

Wenn beispielsweise ein Client unkontrolliert tausende Threads für gleichzeitige AdWords API-Aufrufe erstellt, geben die AdWords API-Server einen RateExceededError-Fehler zurück und fordern die Software auf, Anfragen mit größerem zeitlichem Abstand zu senden.

Aufgrund unterschiedlicher Variablen wie etwa der Serverlast schwanken Ratenbegrenzungen. Daher sollten keine festen QPS-Begrenzungen definiert werden. Sie müssen genau wissen, wie Sie mit dem Fehler RateExceededError umgehen und die Ratenbegrenzungen bei der Entwicklung Ihrer Software berücksichtigen.

In diesem Leitfaden erhalten Sie detaillierte Informationen zum RateExceededError-Fehler sowie zur Vermeidung von Überschreitungen der Ratenbegrenzung.

Vorversionen

In früheren Versionen der AdWords API wurden Anfragen, die die Begrenzung überschritten, bis zur Bearbeitung auf dem API-Server in eine Warteschlange gestellt. Dadurch konnte die Verarbeitung einiger Anfragen scheinbar sehr lange dauern. Die aktuelle API blockiert den Client nicht mehr, sondern gibt stattdessen einen RateExceededError-Fehler zurück. Durch diesen wichtigen Feedback-Mechanismus werden Sie über das Problem informiert und können Ihre Anwendungen entsprechend anpassen.

Arten von Ratenbegrenzungen

Wir wissen, dass AdWords API-Client-Anwendungen gelegentlich aufgrund unvorhergesehener Faktoren die Begrenzung überschreiten und einen RateExceededError-Fehler zurückgeben. Dies hat für Sie keine negativen Konsequenzen. Ein RateExceededError-Fehler wird in der Regel innerhalb von 30 Sekunden Inaktivität automatisch behoben.

Es gibt eine Reihe unterschiedlicher Ratenbegrenzungen, die vom Server durchgesetzt werden. Client-Anwendungen überschreiten möglicherweise diese Ratenbegrenzung innerhalb des Entwickler-Token-Bereichs eines Verwaltungskontos oder des AdWords-Kontobereichs. In beiden Fällen wird die Ratenbegrenzung nicht strikt anhand der Anfragen pro Sekunde, sondern anhand der Anfragen pro Minute, Vorgänge pro Minute bzw. anderer Begrenzungen gemessen. Dies ermöglicht der AdWords API sowohl gleichmäßige Zugriffe als auch kurzzeitige Spitzen. Sowohl der Bereich als auch der Name der Ratenbegrenzung werden im RateExceededError-Fehler zurückgegeben.

Vorgangsbegrenzung nach Zugriffsebene

Es gibt nur eine stabile Ratenbegrenzung: die Vorgangsbegrenzung, die auf der Zugriffsebene des Entwickler-Tokens basiert. Es gibt zwei Zugriffsebenen: Grundlegend und Standard. Ein Konto mit der Zugriffsebene Grundlegend ist auf 10.000 Vorgänge pro Tag und 1.000 Downloads von Berichten pro Tag begrenzt. Einem neu genehmigten Entwickler-Token wird standardmäßig die Zugriffsebene Grundlegend zugewiesen. Wenn Sie mehr als 10.000 Vorgänge pro Tag ausführen oder mehr als 1.000 Berichte pro Tag herunterladen möchten, füllen Sie das AdWords API-Standardzugriffsformular aus, um die Zugriffsebene Standard zu beantragen. Für keine der beiden Zugriffsebenen fallen Kosten an. Wie Vorgänge gezählt werden, erfahren Sie auf der Seite Gebührenliste.

Alle anderen Ratenbegrenzungen unterliegen Schwankungen. Daher müssen Sie den RateExceededError-Fehler in Ihrer Anwendung abfangen.

Elemente von RateExceededError

Der RateExceededError-Fehler enthält drei äußerst wichtige Felder:

  • rateScope: Bereich der überschrittenen Rate (ACCOUNT oder DEVELOPER)
  • rateName: Dieses Feld enthält den Namen der überschrittenen Ratenbegrenzung. Ein möglicher Wert ist hier RequestsPerMinute.
  • retryAfterSeconds: Dieses Feld enthält die Dauer in Sekunden, die vor der nächsten Anfrage der Anwendung mindestens gewartet werden muss. Wir empfehlen die Anwendung eines zufälligen Multiplikators (z. B. eine Gleitkommazahl zwischen 1 und 2 (je einschließlich)) auf retryAfterSeconds, wenn die Anzahl der zu wartenden Sekunden festgelegt wird. Wenn Ihre Programme Anfragen parallel senden (z. B. bei Multi-Threading), dürfen neue Anfragen nach der Wartezeit nicht gleichzeitig gesendet werden.

Wenn Ihre Anwendung ständig die Ratenbegrenzung überschreitet, müssen Sie sich eingehend über rateScope und rateName informieren, um in Ihrer Anwendung eine dauerhaftere Drosselungsstrategie zu implementieren.

Konto- und Entwicklerbereich

Das Feld "rateScope" kann folgende Werte haben: ACCOUNT oder DEVELOPER. Dieser Wert gibt an, ob die Ratenbegrenzung auf AdWords-Kontoebene oder auf Entwickler-Token-Ebene überschritten wurde.

Entwickler-Token-Bereich

Jedes AdWords-Verwaltungskonto, das für die Verwendung der AdWords API angemeldet ist, hat ein einziges Entwickler-Token. In der Regel werden alle Anfragen diesem Entwickler-Token zugewiesen. Wenn die kombinierten QPS für alle Clientanfragen mit demselben Entwickler-Token eine bestimmte Ratenbegrenzung überschreiten, kann ein RateExceededError-Fehler für das Entwickler-Token zurückgegeben werden.

Wenn beispielsweise von einem Verwaltungskonto 100 AdWords-Konten verwaltet werden und es mehrere Clientsoftwareinstanzen gibt, die dasselbe Entwickler-Token verwenden, um insgesamt 100 Anfragen pro Sekunde in mehreren Vorgängen auszuführen, wird an die Clientsoftware möglicherweise für den Entwickler-Token-Bereich ein RateExceededError-Fehler zurückgegeben.

Kontobereich

Wenn dieselbe Anwendung eine große Anzahl von Anfragen pro Sekunde für ein einzelnes AdWords-Konto ausführt, das von einem Verwaltungskonto verwaltet wird, gibt der AdWords API-Server möglicherweise einen RateExceededError-Fehler zurück, weil die Ratenbegrenzung innerhalb des Kontobereichs überschritten wurde. Dies kann beispielsweise der Fall sein, wenn Ihre Client-Anwendung mehrere Threads erstellt, um für ein einzelnes AdWords-Konto übermäßig viele mutate()-Vorgänge auszuführen.

Diese Ratenbegrenzung für den Kontobereich wird für alle Anfragen eines einzigen AdWords-Kontos gemessen. Das für die Anfragen verwendete Entwickler-Token ist hierbei irrelevant.

Wenn beispielsweise ein einzelnes AdWords-Konto von fünf verschiedenen Verwaltungskonten verwaltet wird, kann es durchaus vorkommen, dass alle fünf Verwaltungskonten gleichzeitig Anfragen beim selben AdWords-Konto ausführen. Überschreitet die kombinierte QPS aller Verwaltungskonten die Begrenzung, wird an die Clients im Kontobereich der RateExceededError-Fehler zurückgegeben.

Bedeutung des Ratennamens

Neben dem Ratenbereich müssen Sie den Typ der überschrittenen Ratenbegrenzung kennen. Der Typ der Ratenbegrenzung wird im Feld rateName zurückgegeben. Die häufigsten Bezeichnungen für Ratenbegrenzungen sind:

  • RequestsPerMinute
  • OperationsPerMinute
Unterschied zwischen Anfrage und Vorgang

Was ist denn nun der Unterschied zwischen RequestsPerMinute und OperationsPerMinute? Jeder SOAP-Dienstaufruf wird als Anfrage gezählt. Jeder Aufruf von CampaignService.mutate() zählt als Anfrage. Innerhalb dieser mutate-Anfrage könnten Sie jedoch 100 CampaignOperation übergeben haben. Diese werden als 100 Vorgänge gezählt.

Im obigen Beispiel umgehen Sie durch die Bündelung mehrerer Vorgänge in einer Anfrage zwar die Ratenbegrenzung für RequestPerMinute, die Ratenbegrenzung für OperationsPerMinute wird jedoch möglicherweise dennoch überschritten.

Weitere Beispiele für die Zählung von Vorgängen finden Sie auf der Seite Gebührenliste.

Grenzfälle

Die oben genannten Ratennamen sind besonders häufig. Allerdings kann es andere Arten von Ratenbegrenzungen geben, die überschritten werden können. Falls bei Ihnen solche Probleme auftreten, informieren Sie uns bitte im AdWords API-Forum darüber.

Anfragehäufigkeit senken

Wenn Ihre Anwendung einen RateExceededError-Fehler erhält, sollten Sie die Anfragehäufigkeit senken. Andernfalls kann es noch länger dauern, bis die Anwendung diesen Fehlerzustand verlässt. Die einfachste Möglichkeit, dieses Problem zu beheben, besteht darin, beim erneuten Senden dieser Anfrage bzw. anderer Anfragen den Wert RateExceededError.retryAfterSeconds zu berücksichtigen.

Verwenden Sie in Java beispielsweise die Funktion Thread.sleep(), um den Thread vor der nächsten Anfrage zu unterbrechen.

try {
  ...
} catch (ApiException e) {
  for (ApiError error : e.getErrors()) {
    if (error instanceof RateExceededError) {
      RateExceededError rateExceeded = (RateExceededError) error;
      Thread.sleep(rateExceeded.getRetryAfterSeconds() * 1000);
    }
  }
  ...
}

Diese Methode ist zwar einfach und direkt, erzielt aber nicht unbedingt einen besseren Durchsatz. Sie sollte daher nur als letzte Maßnahme verwendet werden.

Es gibt mehrere Möglichkeiten, die Überschreitung einer Ratenbegrenzung zu vermeiden. Machen Sie sich mit den Enterprise Integration Patterns-Konzepten (EIP) wie Benachrichtigungen, erneuter Zustellung und Drosselung vertraut, um eine stabilere Client-Anwendung zu erstellen.

Im nächsten Abschnitt erfahren Sie mehr zu diesen empfohlenen Vorgehensweisen. Auch wenn Sie diese Maßnahmen zur Minimierung von Ratenüberschreitungen umsetzen, muss eine Fehlerbehandlungsroutine für RateExceededError vorhanden sein.

Ablaufsteuerung

Sie können die Abläufe in der Anwendung so steuern, dass RateExceededError-Fehler so weit wie möglich vermieden werden. Hierzu reduzieren Sie aktiv die Anzahl der Anfragen und drosseln die QPS-Rate des Clients.

Hier sehen Sie eine kleine Auswahl empfohlener Vorgehensweisen von einfacher Strategie bis zu stabilen, komplexen Architekturen:

  • Anzahl gleichzeitiger Threads begrenzen
  • Batch-Anfragen
  • BatchJobService verwenden
  • Drosselung/Ratenbegrenzungen
  • Anfragen versetzt an mehrere Konten senden
  • Warteschlange
  • Unterscheidung zwischen neuen und bestehenden Konten

Anzahl gleichzeitiger Threads begrenzen

Die Ursache für einen RateExceededError-Fehler liegt häufig darin, dass die Client-Anwendung übermäßig viele Threads erstellt, die alle gleichzeitig die AdWords API aufrufen. Zwar ist die Anzahl gleichzeitiger Threads, die für eine Client-Anwendung möglich sind, unbegrenzt, doch kann das gleichzeitige Senden von Anfragen über eine unbegrenzte Anzahl von Threads leicht die QPS-Begrenzung auf Ebene des Entwickler-Tokens überschreiten.

Wir empfehlen, die Gesamtzahl der gleichzeitigen Threads für das Senden von Anfragen für alle Prozesse und Systeme zu begrenzen und diesen Wert dann solange anzuheben, bis Sie einen optimalen Durchsatz erreichen, ohne die Begrenzungen zu überschreiten.

Außerdem können Sie die QPS-Rate des Clients für alle Threads drosseln (siehe Drosselung/Ratenbegrenzungen).

Batch-Anfragen

Sofern dies möglich ist, sollten Sie mehrere Anfragen in einer Anfrage zusammenfassen. Dies gilt in erster Linie für mutate()-Aufrufe. Ein Beispiel: Sie möchten den Status mehrerer Instanzen von AdGroupAd aktualisieren. Statt mutate() einmal für jede AdGroupAd aufzurufen, könnten Sie mutate() auch einmal aufrufen und der Funktion in einer einzigen Anfrage mehrere AdGroupAdOperation übergeben. In unseren Best Practices finden Sie weitere Beispiele sowie die besten Möglichkeiten zur Gruppierung von Vorgängen.

Berücksichtigen Sie beim Zusammenfassen mehrerer Vorgänge in einer einzelnen Anfrage den geringen Umfang einer einzelnen Anfrage. Wenn ein Vorgang fehlschlägt, schlägt die gesamte Anfrage fehl und es werden keine Werte aktualisiert. Verwenden Sie die Funktion für teilweise fehlgeschlagene Vorgänge, um dieses Problem zu entschärfen.

Wenn Sie Anfragen in einem Batch-Vorgang senden, sinkt die Gesamtzahl der Anfragen und somit die Wahrscheinlichkeit, dass die Ratenbegrenzung für Anfragen pro Minute überschritten wird. Allerdings kann dies dazu führen, dass die Ratenbegrenzung für Vorgänge pro Minute überschritten wird, wenn Sie für ein einzelnes Konto viele Vorgänge ausführen.

BatchJobService verwenden

Verwenden Sie BatchJobService für längere Aufgaben, zur Verarbeitung einer größeren Anzahl von Vorgängen oder für eine größere Anzahl von Vorgängen für mehrere Dienste. Mit BatchJobService können Sie tausende Vorgänge in der Google Cloud asynchron planen und ausführen. Sie müssen nur das Ergebnis abrufen, um den Status zu prüfen.

Weitere Informationen finden Sie im Leitfaden zur Batch-Verarbeitung.

Drosselung/Ratenbegrenzungen

Neben der Begrenzung der Gesamtzahl von Threads in Ihrer Client-Anwendung können Sie auch Ratenbegrenzungen für den Client implementieren. Dadurch können Sie sicherstellen, dass der Client die QPS-Begrenzung für alle Threads Ihrer Prozesse bzw. Cluster verwaltet.

Verwenden Sie beispielsweise Guava Rate Limiter oder implementieren Sie einen eigenen Token Bucket-basierten Algorithmus für eine Cluster-Umgebung. Sie können beispielsweise Token erstellen und in einem freigegebenen transaktionalen Speicher wie einer Datenbank speichern. Jeder Client muss ein Token abrufen und verbrauchen, bevor er die Anfrage verarbeiten kann. Wenn die Token verbraucht sind, muss der Client warten, bis neue Token erstellt wurden.

In den meisten Fällen können Sie durch Drosselung Überschreitungen der Ratenbegrenzung auf Entwickler-Token-Ebene vermeiden.

Anfragen versetzt an mehrere Konten senden

Wenn Sie die Ratenbegrenzung im Kontobereich überschreiten, können Sie die QPS für das Konto auf dem Client beschränken. Dies ist aber eventuell nicht ganz einfach, wenn Sie tausende von Konten verwalten. Eine einfachere Möglichkeit besteht darin, Anfragen versetzt an mehrere Konten zu senden.

Wenn Sie beispielsweise 5.000 mutate()-Vorgänge für zehn Konten ausführen, können Sie die Vorgänge im Batch-Verfahren nacheinander an die einzelnen Konten senden:

  1. 500 mutate-Vorgänge für Konto 1 senden (und für 5.000 Vorgänge zehnmal wiederholen)
  2. 500 mutate-Vorgänge für Konto 2 senden (ebenfalls zehnmal wiederholen)
  3. ... (bis alle zehn Konten abgearbeitet sind)

Dieser Ansatz ist sehr direkt, kann aufgrund der Vorgänge pro Minute jedoch trotzdem zu einer Überschreitung der Ratenbegrenzung auf Kontoebene führen.

Versetzt an Konten gesendete Anfragen sehen wie folgt aus:

  1. 500 mutate-Vorgänge für Konto 1 senden
  2. 500 mutate-Vorgänge für Konto 2 senden
  3. 500 mutate-Vorgänge für Konto 3 senden
  4. ... (bis alle zehn Konten abgearbeitet sind)
  5. 500 mutate-Vorgänge für Konto 1 senden
  6. 500 mutate-Vorgänge für Konto 2 senden
  7. ...(bis alle 5.000 Vorgänge für alle Konten abgearbeitet sind)

Dieses Beispiel zeigt, wie Sie Anfragen versetzt an Konten senden. Sie sollten jedoch prüfen, ob BatchJobService nicht doch Ihre Anforderungen erfüllt. Weitere Informationen finden Sie im Leitfaden zur Batch-Verarbeitung.

Warteschlange

Warteschlangen sind die beste Lösung, um Vorgänge gleichmäßig zu verteilen und gleichzeitig die Anfrage- und Empfängerraten zu steuern. Es gibt mehrere Optionen für Warteschlangen, sowohl Open Source- als auch proprietäre Software in unterschiedlichen Programmiersprachen.

Wenn Sie eine Warteschlange verwenden, können mehrere Sender Nachrichten in die Warteschlange stellen und mehrere Empfänger können diese Nachrichten verarbeiten. Sie können die Anzahl gleichzeitiger Empfänger drosseln oder Ratenbegrenzungen/Drosselungen für Sender oder Empfänger erstellen.

Wenn beispielsweise auf dem Empfänger einer Nachricht ein RateExceededError-Fehler auftritt, kann der Empfänger die Anfrage in die Warteschlange zurücksenden, damit ein neuer Versuch gestartet werden kann. Gleichzeitig kann der Empfänger alle Empfänger informieren, einige Sekunden mit der Verarbeitung auszusetzen, bis der Fehler behoben ist.

Unterscheidung zwischen Warteschlange und Ratenbegrenzung für neue und bestehende Konten

Wenn Sie Strategien für Warteschlangen oder Ratenbegrenzungen implementieren, muss beachtet werden, dass ein neues AdWords-Konto erheblich mehr Ratenbegrenzungen (d. h. niedrigere QPS-Rate) als schon länger bestehende Konten hat. Verwenden Sie daher eventuell unterschiedliche Ratenbegrenzungen oder Drosselungen für neue und bestehende Konten, wenn Sie in Ihrem Unternehmen sowohl häufig neue Konten erstellen als auch viele ältere Konten verwalten.

So können Sie den Durchsatz beider Kontotypen optimieren, ohne durch das Konto mit der niedrigsten QPS-Rate eingeschränkt zu sein.

Normalerweise wird die restriktivere Ratenbegrenzung für neue AdWords-Konten aufgehoben, sobald über das Konto Anzeigen ausgeliefert wurden.

Feedback geben zu...