Best Practices

In diesem Leitfaden finden Sie einige bewährte Vorgehensweisen, mit denen sich die Effizienz und Leistung Ihrer AdWords API-Anwendungen optimieren lassen.

Laufende Wartung

So vermeiden Sie Unterbrechungen bei der Anzeigenauslieferung:

  • Achten Sie darauf, dass die bei den Kontaktdaten des Entwicklers angegebene E-Mail-Adresse im AdWords-API-Center stets aktuell ist. Unter diesem Alias kontaktieren wir Sie. Falls wir Sie nicht erreichen, um mit Ihnen die Einhaltung der API-Nutzungsbedingungen zu besprechen, kann Ihr API-Zugang ohne Vorankündigung gesperrt werden. Verwenden Sie keine private E-Mail-Adresse, die an ein individuelles Konto geknüpft ist oder nicht überwacht wird.

  • Um Informationen zu Produktneuerungen, Ausfallzeiten wegen Wartungsarbeiten, Einstellungsterminen und sonstigen wichtigen Updates zu erhalten, sollten Sie Folgendes abonnieren:

Das Forum wird regelmäßig vom AdWords API-Team kontrolliert. Hier können Sie alle Ihre Fragen zum Thema APIs posten.

  • Achten Sie darauf, dass Ihre App den Nutzungsbedingungen für die Google AdWords API und den erforderlichen Mindestfunktionen entspricht. Gegebenenfalls wird sich das für die Tokenprüfung und für Compliance zuständige Team per E-Mail bei Ihnen melden. Bei Fragen zu den Nutzungsbedingungen oder erforderlichen Mindestfunktionen können Sie sich an das Prüfteam wenden, indem Sie auf die E-Mail antworten, die Sie bezüglich der Überprüfung Ihres Entwickler-Tokens erhalten haben.

Optimierung

Batch-Vorgänge

Eine Anfrage an die API verursacht bestimmte Fixkosten, z. B. für die Roundtrip-Netzwerklatenz, für die Serialisierung bzw. Deserialisierung und für Anfragen an Back-End-Systeme. Um diese Fixkosten zu reduzieren und die Gesamtleistung zu steigern, sind die meisten mutate()-Methoden in der API so konzipiert, dass mehrere Vorgänge akzeptiert werden. Durch die Verarbeitung mehrerer Vorgänge innerhalb einer Anfrage werden die Anzahl der Anfragen und die damit zusammenhängenden Fixkosten reduziert. Senden Sie also möglichst keine Anfragen mit nur einem Vorgang.

Beispiel: Sie wollen einer Kampagne 50.000 Keywords für mehrere Anzeigengruppen hinzufügen. Anstelle von 50.000 Anfragen mit je einem Keyword können Sie auch 100 Anfragen mit je 500 Keywords oder sogar zehn Anfragen mit je 5.000 Keywords senden. Beachten Sie jedoch, dass pro Anfrage nur eine begrenzte Anzahl von Vorgängen erlaubt ist und Sie die Größe des Batches entsprechend anpassen müssen.

Ein weiterer Vorteil von weniger und dabei größeren Anfragen besteht darin, dass mit geringerer Wahrscheinlichkeit eine Ratenbegrenzung für Anfragen überschritten wird.

Gruppenvorgänge

Vorgänge, die auf dieselbe Anzeigengruppe oder Kampagne abzielen, werden schneller verarbeitet als dieselbe Anzahl von Vorgängen, die auf viele verschiedene Anzeigengruppen oder Kampagnen abzielen. Durch eine Zusammenfassung von Vorgängen für dieselbe Anzeigengruppe oder Kampagne wird die Gesamtzahl der Anzeigengruppen oder Kampagnen pro Anfrage reduziert und damit die Gesamtleistung verbessert.

Bei gleichzeitig gesendeten Anfragen für dieselbe Anzeigengruppe oder Kampagne kann es zu einem CONCURRENT_MODIFICATION-Fehler kommen. Fasst man Vorgänge, bei denen dieselbe Anzeigengruppe oder Kampagne bearbeitet werden soll, in einer einzigen Anfrage zusammen, verringert sich das Risiko für solch einen Konflikt.

Noch einmal zurück zu unserem Beispiel. Sie möchten einer Kampagne 50.000 Keywords für mehrere Anzeigengruppen hinzufügen. Bevor Sie die Vorgänge in Batches aufteilen, ist es empfehlenswert, die Keywords nach der jeweiligen Anzeigengruppe zu sortieren. Dadurch steigt die Wahrscheinlichkeit, dass alle Keywords einer Anzeigengruppe derselben Anfrage zugeordnet werden. Außerdem bezieht sich eine Anfrage somit auf insgesamt weniger Anzeigengruppen. Es gibt noch weitere Möglichkeiten, die Anzahl der Anfragen mit ähnlichen Vorgängen unter Beibehaltung großer Batches zu reduzieren.

Zugriffstokens wiederverwenden

Durch Wiederverwendung desselben OAuth2-Zugriffstokens für verschiedene Threads und Prozesse müssen Tokens nicht mehr so oft aktualisiert werden. Damit nimmt auch die Wahrscheinlichkeit ab, dass Ihre App aufgrund häufiger Tokenaktualisierungen eine Ratenbeschränkung erhält. Weitere Informationen zur Optimierung von OAuth2-Anfragen

Teilobjekte senden

Bei der Übermittlung von Objekten an die API müssen alle Felder deserialisiert, validiert und in der Datenbank gespeichert sein. Wenn Sie zur Aktualisierung weniger Felder die vollständigen Objekte übermitteln, verlängert sich dadurch die Verarbeitungszeit und die Leistung wird reduziert. Die AdWords API unterstützt deshalb eine partielle Aktualisierung, bei der nur die Felder des Objekts gefüllt werden, für die eine Änderung gewünscht bzw. erforderlich ist. Felder ohne Inhalt bzw. mit Nullwerten werden nicht verändert, was sich positiv auf die Leistung Ihrer Anfragen auswirkt.

Beispiel: Bei einer App, die Gebote auf Keyword-Ebene aktualisiert, kann die partielle Aktualisierung vorteilhaft sein, da nur die Felder adGroupID, criterionID und die Felder für Gebote gefüllt werden müssen. Bei einem Test mit 150 Keywords, bei dem keine vollständig gefüllten Objekte übermittelt wurden, sondern stattdessen eine partielle Aktualisierung durchgeführt wurde, konnte eine Leistungssteigerung um 20 % festgestellt werden.

Komprimieren

Die AdWords API unterstützt komprimierte SOAP-Nachrichten im GZIP-Format für Anfragen und Antworten. Nehmen Sie diese beiden HTTP-Header in Ihre Anfrage auf, um eine Antwort mit GZIP-Komprimierung zu erhalten:

  • User-Agent: Enthält den String "gzip".
  • Accept-Encoding: Enthält den Wert "gzip".

Beispiel:

User-Agent: My App (gzip)
Accept-Encoding: gzip

Wenn Sie eine Clientbibliothek verwenden, sollten Sie sich die Dokumentation zum Aktivieren der Komprimierung ansehen.

Fehlerbehandlung

Während der Entwicklung werden Sie mit hoher Wahrscheinlichkeit auf Fehler stoßen. In diesem Abschnitt wird aufgeführt, mit welchen Strategien Sie ein Fehlermanagement in Ihrer App implementieren.

Im Leitfaden zur Fehlerbehebung erhalten Sie weitere Informationen zu diesem Thema.

Anfragequellen unterscheiden

Manche Apps sind hauptsächlich interaktiv. Zu API-Aufrufen kommt es hier direkt nach von Nutzern initiierten Aktionen auf einer Benutzeroberfläche. Andere funktionieren hauptsächlich offline und zu API-Aufrufen kommt es hier im Zuge regelmäßiger Back-End-Prozesse. Bei manchen Apps kommt auch beides vor. Beim Fehlermanagement sollten diese zwei Arten von Anfragen unterschieden werden.

Bei von Nutzern initiierten Anfragen sollten Sie sich auf eine gute Nutzererfahrung konzentrieren. Mithilfe des spezifischen Fehlers können Sie dem Nutzer möglichst viel Kontext auf der Benutzeroberfläche bereitstellen. Bieten Sie ihm, wenn möglich, einfache Schritte zur Fehlerbehebung an (siehe Vorschläge unten).

Bei vom Back-End initiierten Anfragen sollten Sie Handler für die verschiedenen Fehlertypen implementieren, die in Ihrer App auftreten können (siehe Vorschläge unten). Schließen Sie immer einen Standard-Handler mit ein, um seltene oder unvorhergesehene Fehler beheben zu können. Dabei ist es empfehlenswert, den fehlgeschlagenen Vorgang und Fehler einer Warteschlange hinzuzufügen, damit sich dann eine Person um eine passende Lösung kümmern kann.

Fehlertypen unterscheiden

Nachfolgend werden vier grobe Fehlerkategorien aufgeführt, wobei jede anders behoben werden muss. Obwohl diese Kategorien nicht alle möglichen Fehler abdecken und manche von ihnen unter mehrere Kategorien fallen, können sie dennoch zur Strukturierung der Fehlerbehandlung in Ihrer App dienen. Unter Häufige Fehler finden Sie weitere Einzelheiten zu bestimmten Problemen.

  1. Fehler bei der Authentifizierung und Autorisierung

    • Authentifizierung bezieht sich darauf, ob ein Nutzer Ihrer App erlaubt hat, in seinem Namen auf AdWords zuzugreifen. Die Authentifizierung erfolgt anhand von in OAuth2 generierten Anmeldedaten.

    • Autorisierung bezieht sich darauf, ob Ihre App nach der Authentifizierung im Namen des Nutzers bestimmte AdWords-Daten lesen oder schreiben darf.

    Entstehen Authentifizierungsfehler durch Faktoren, die sich Ihrer Kontrolle entziehen, liegt dies häufig daran, dass der authentifizierte Nutzer seine Erlaubnis zurückgezogen hat. Beispiel: Verwaltet Ihre App mehrere AdWords-Konten für unterschiedliche Kunden und authentifiziert sich diese bei der Verwaltung jedes Konto jeweils als der Kunde, könnte dieser Ihrer App jederzeit den Zugriff verweigern. Je nach Zeitpunkt des Widerrufs kann die API direkt den Fehler AuthenticationError.OAUTH_TOKEN_REVOKED zurückgeben. Alternativ könnten die integrierten Objekte zu Anmeldedaten in den Clientbibliotheken eine Ausnahme wegen einer Tokenaufhebung signalisieren. Verfügt Ihre App über eine UI für Kunden, könnte sie diese dazu auffordern, den OAuth2-Prozess erneut zu starten, um die Erlaubnis wiederzuerlangen, in seinem Namen zu handeln.

    Entstehen Autorisierungsfehler durch Faktoren, die sich Ihrer Kontrolle entziehen, liegt dies außerdem häufig an einer geänderten Verwaltungskontohierarchie. Apps mit einer einzelnen Verwaltungskontohierarchie authentifizieren sich normalerweise als Administrator ihres Verwaltungskontos auf oberster Ebene, denn diese Art von Nutzer ist befugt, auf alle Unterkonten in der Hierarchie zuzugreifen. Entfernt ein Nutzer eines Unterkontos die Verknüpfung zum Verwaltungskonto, wird in Ihrer App bei einem versuchten Zugriff auf dieses Konto der Fehler AuthorizationError.USER_PERMISSION_DENIED zurückgegeben. Mithilfe von ManagedCustomerService können Sie überprüfen, ob das Unterkonto aus der Hierarchie entfernt wurde.

    Ein weiterer Autorisierungsfehler kann auftreten, wenn der Nutzer, als der sich Ihre App authentifiziert hat, seine Zugangsrechte bearbeitet. Beispiel: Ein anderer Nutzer mit Administratorrechten am AdWords-Konto ändert die Rechte des authentifizierten Nutzers, sodass dieser nur noch eine Leseberechtigung besitzt. Alle Änderungsanfragen werden in diesem Fall fehlschlagen und zu dem Fehler AuthorizationError.USER_HAS_READONLY_PERMISSION führen.

    In beiden Beispielen könnte Ihre App dem Nutzer Vorgehensweisen aufzeigen oder die Problemlösung an einen Account Manager übertragen.

  2. Temporäre Fehler

    Manche Fehler deuten auf ein temporäres Problem hin, das bei einem erneuten Anfrageversuch nach einer kurzen Pause gelöst sein kann. Hierzu zählen CONCURRENT_MODIFICATION, UNEXPECTED_INTERNAL_API_ERROR und RATE_EXCEEDED.

    Bei von Nutzern initiierten Anfragen können Sie den Fehler sofort in der UI darstellen und dem Nutzer die Möglichkeit eines zweiten Versuchs geben. Alternativ könnte Ihre App die Anfrage zuerst automatisch wiederholen und den Fehler erst nach einer bestimmten Anzahl von Versuchen oder einer gewissen Wartezeit in der UI sichtbar machen.

    Bei vom Back-End initiierten Anfragen sollte Ihre App die Anfrage automatisch bis zu einer maximalen Anzahl von Versuchen wiederholen.

    Gehen Sie bei erneuten Anfragen nach dem Exponential-Backoff-Prinzip vor. Warten Sie vor dem zweiten Versuch beispielsweise fünf Sekunden, vor dem dritten zehn Sekunden und vor dem vierten 20 Sekunden. Dadurch wird die API nicht zu häufig aufgerufen.

    Bei dem Fehler RATE_EXCEEDED sollte die Pause vor einem erneuten Versuch länger als die Zeitangabe im Fehlerfeld retryAfterSeconds sein. Weitere Informationen hierzu finden Sie im Leitfaden zu Ratenbegrenzungen. Bei anderen temporären Fehlern können früher erneute Anfragen gesendet werden, aber auch hier sollten Sie nach dem Exponential-Backoff-Prinzip vorgehen.

  3. Validierungsfehler

    Zu Validierungsfehlern kommt es nach inakzeptablen Eingaben bei einem Vorgang. Beispiele: PolicyViolationError, DateError, DateRangeError, StringLengthError oder UrlError.

    Validierungsfehler treten typischerweise bei von Nutzern initiierten Anfragen auf, wenn diese etwas Ungültiges eingegeben haben. In solchen Fällen sollte der Nutzer eine zum spezifischen API-Fehler passende Fehlermeldung erhalten. Sie können Nutzereingaben vor einem API-Aufruf auch auf typische Fehler überprüfen. So sorgen Sie für eine responsivere App und eine effizientere API-Nutzung.

    Bei vom Back-End initiierten Anfragen könnte Ihre App den fehlgeschlagenen Vorgang einer Warteschlange hinzuzufügen, damit sich eine Person um die Problembehandlung kümmern kann.

  4. Fehlende Synchronität

    Viele AdWords-Apps verfügen über eine lokale Datenbank zur Speicherung von AdWords-Objekten. Ein Problem bei diesem Ansatz besteht darin, dass die lokale Datenbank nicht mit den Objekten in AdWords synchron sein kann. Beispiel: Ein Nutzer löscht eine Anzeigengruppe direkt in AdWords. Die App und die lokale Datenbank registrieren diese Änderung jedoch nicht und initiieren darum API-Aufrufe, so als ob die Anzeigengruppe weiterhin existiert. Beispiele für Synchronitätsfehler: INVALID_ID, DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP oder CANNOT_OPERATE_ON_REMOVED_ADGROUPAD.

    Bei von Nutzern initiierten Anfragen könnte die App Nutzer auf ein eventuelles Synchronitätsproblem hinweisen. Sie starten einen Job, mit dem die relevante Klasse an AdWords-Objekten abgefragt und die lokale Datenbank aktualisiert wird. Anschließend fordern Sie Nutzer dazu auf, die UI zu aktualisieren.

    Bei vom Back-End initiierten Anfragen enthalten manche Fehler genügend Informationen, damit Ihre App die lokale Datenbank automatisch und inkrementell korrigieren kann. Der Fehler CANNOT_OPERATE_ON_REMOVED_ADGROUPAD bedeutet beispielsweise, dass Ihre App die Anzeige in der lokalen Datenbank als "Entfernt" markiert. Fehler, die nicht auf diese Weise behoben werden können, könnten dazu führen, dass Ihre App eine umfassendere Synchronisierung vornimmt oder dass der Fehler einer Warteschlange hinzugefügt wird, damit sich eine Person um die Prüfung kümmert.

Teilweise fehlgeschlagene Vorgänge behandeln

Anfragen an die AdWords API bilden standardmäßig ein Ganzes: Tritt nur bei einem Vorgang innerhalb der Anfrage ein Fehler auf, werden alle Vorgänge abgebrochen. Hierbei handelt es sich um eine Sicherheitsvorkehrung, die in vielen Fällen aber auch Nachteile hat, da es sich um voneinander unabhängige Vorgänge handeln könnte und eventuell nur die gescheiterten Vorgänge geprüft werden müssen. Dieses Standardverhalten kann man unterschiedlich handhaben. Hier gibt es zwei Strategien:

1. Sie überprüfen die Fehler in der Antwort, setzen Sie mit dem Vorgang bzw. den Vorgängen in Beziehung, die die Fehler erzeugt haben, und führen eine erneute Anfrage durch – diesmal nur mit den Vorgängen, die keine Fehler hervorgerufen haben. Nun sollten diese Vorgänge funktionieren. Sie könnten auch die fehlerhaften Vorgänge in Ihren Strategien zur Fehlerbehandlung (siehe oben) berücksichtigen oder sie der Warteschlange für die Überprüfung hinzufügen.

2. Sie aktivieren innerhalb von API-Anfragen das Flag für teilweise fehlgeschlagene Vorgänge. Anschließend wird jeder Vorgang individuell behandelt und ein einzelner Fehler führt nicht mehr dazu, dass alle anderen Vorgänge abgebrochen werden. Fehler bei spezifischen Vorgängen werden weiterhin normal zurückgegeben. Das Flag wird von all unseren Clientbibliotheken unterstützt.

Die Nutzung des Flags für teilweise fehlgeschlagene Vorgänge führt vor allem zu mehr Einfachheit und weniger API-Aufrufen, da gültige Vorgänge automatisch durchgeführt werden. Sie müssen dabei keine erneuten Versuche vornehmen. Bei den meisten Apps bieten sich teilweise fehlgeschlagene Vorgänge an.

Bei einigen Apps ist allerdings mehr Kontrolle bei der Fehlerbehandlung zu empfehlen. Beispiel: Bei einer App sollen Fehler wegen Richtlinienverstößen nicht dazu führen, dass andere Anzeigen nicht bereitgestellt werden können. Vielmehr sollen andere Fehler (zum Beispiel solche bei schwerwiegenderen Problemen) zu einem Abbruch der gesamten Anfrage führen. Hierfür muss die erstgenannte Strategie (siehe oben) angewandt werden.

Beachten Sie in jedem Fall, dass manche Fehler für voneinander abhängige Vorgänge stehen, die auch jeweils einzeln gültig gewesen wären. Beispiele: AdGroupAdError.ENTITY_REFERENCED_IN_MULTIPLE_OPS und AdParamError.AD_PARAM_CANNOT_BE_SPECIFIED_MULTIPLE_TIMES.

Back-Ends synchronisieren

Haben die Nutzer Ihrer App manuellen Zugriff auf AdWords-Konten, nehmen sie eventuell Äderungen vor, die von Ihrer App nicht registriert werden, was zu einer mangelnden Synchronität mit Ihrer lokalen Datenbank führen kann. Wie oben beschrieben können Synchronitätsfehler reaktiv bei Auftreten behandelt oder proaktiv vermieden werden. Beispiel für ein proaktives Vorgehen: Jede Nacht synchronisieren Sie alle Konten, fragen dabei alle AdWords-Objekte in den Konten ab und gleichen sie mit denen in der lokalen Datenbank ab. Mithilfe von Strukturberichten sind effizientere Objektabfragen als mit den regulären API-Diensten möglich.

Fehler protokollieren

Alle Fehler sollten protokolliert werden, damit ihre Behebung und Überwachung vereinfacht wird. Zumindest sollten die Anfrage-ID sowie die Vorgänge, die den Fehler verursacht haben, und der Fehler selbst protokolliert werden. Zusätzlich könnten noch die Kundennummer, der API-Dienst, die Latenzzeit zwischen Anfrage und Antwort, die Anzahl der erneuten Versuche und die Rohdaten zur SOAP-Anfrage und -Antwort protokolliert werden.

Die Clientbibliotheken verfügen über integrierte Möglichkeiten zur SOAP-Protokollierung und zur Abfrage des requestId-Headers.

Behalten Sie gehäuft auftretende API-Fehler im Auge, um Probleme mit Ihrer App erkennen und behandeln zu können. Eventuell ist es empfehlenswert, hierfür eine eigene Lösung zu entwickeln oder eine von vielen auf dem Markt erhältlichen Tools zu verwenden, mit denen anhand Ihrer Protokolle interaktive Übersichten erstellt und automatische Benachrichtigungen gesendet werden.

Sonstiges

Testkonten nutzen

Bei Testkonten handelt es sich um AdWords-Konten, in denen keine Anzeigenauslieferung erfolgt. Mithilfe eines Testkontos können Sie mit der AdWords API experimentieren und die Verknüpfung der App mit AdWords, die Verwaltungslogik für Kampagnen und weitere Prozesse überprüfen. Ihr Entwickler-Token muss nicht genehmigt werden, um damit ein Testkonto nutzen zu können. Daher können Sie direkt nach der Anfrage eines Entwickler-Tokens – und sogar noch vor der Prüfung Ihrer App – anfangen, mit der AdWords API zu arbeiten.

Ausrichtungsideen bündeln

Bei der Generierung von Ausrichtungsideen mithilfe von TargetingIdeaService akzeptiert der TargetingIdeaSelector einen RequestType – entweder mit IDEAS oder STATS. Mit STATS-Anfragen können Statistiken zu bekannten Keywords abgerufen werden. Um Statistiken für mehrere Keywords zu erhalten, fassen Sie sie zu einer einzelnen Anfrage zusammen, indem Sie die Keywords im RelatedToQuerySearchParameter aufführen. Pro Keyword wird eine TargetingIdea ausgegeben. Dies ist effizienter, als für jedes Keyword eine einzelne Anfrage zu senden.

Feedback geben zu...