API-Struktur

In diesem Leitfaden werden die Hauptkomponenten der Google Ads API vorgestellt. Die Google Ads API besteht aus Ressourcen und Diensten. Eine Ressource stellt eine Google Ads-Entität dar, während Dienste Google Ads-Entitäten abrufen und bearbeiten.

Objekthierarchie

Ein Google Ads-Konto kann als Hierarchie von Objekten betrachtet werden.

• Die Ressource der obersten Ebene eines Kontos ist der Kunde.

• Jeder Kunde enthält eine oder mehrere aktive Kampagnen.

• Jede Kampagne enthält eine oder mehrere Anzeigengruppen, mit denen Sie Ihre Anzeigen in logischen Sammlungen gruppieren können.

• Eine Anzeigengruppenanzeige stellt eine Anzeige dar, die Sie in einer Anzeigengruppe schalten. Mit Ausnahme von App-Kampagnen, die nur eine Anzeigengruppenanzeige pro Anzeigengruppe haben können, enthält jede Anzeigengruppe eine oder mehrere Anzeigengruppenanzeigen.

Performance Max-Kampagnen haben eine andere Struktur als andere Kampagnentypen: Anstelle von Anzeigengruppen und Anzeigengruppenanzeigen enthält eine Performance Max-Kampagne Asset-Gruppen. Sie verknüpfen Creative-Assets mit einer Asset-Gruppe über AssetGroupAsset und fügen Zielgruppen- oder Such themensignale mit AssetGroupSignal hinzu.

Sie können einer Anzeigengruppe oder Kampagne eine oder mehrere AdGroupCriterion oder CampaignCriterion-Ressourcen hinzufügen. Diese stellen Kriterien dar, die definieren, wie Anzeigen ausgelöst werden.

Es gibt viele Kriterientypen, z. B. Keywords, Altersgruppen und Standorte. Auf Kampagnenebene definierte Kriterien wirken sich auf alle anderen Ressourcen in der Kampagne aus. Sie können auch Budgets sowie Start- und Enddatum und -zeit für Kampagnen oder für Einzelanzeigen mit AdGroupAd.start_date_time und AdGroupAd.end_date_time angeben.

Schließlich können Sie Assets auf Konto-, Kampagnen-, Anzeigengruppen- oder Asset-Gruppenebene hinzufügen. Mit Assets können Sie Ihren Anzeigen zusätzliche Informationen wie Telefonnummern, Adressen oder Angebote hinzufügen. Weitere Informationen finden Sie in der Übersicht zu Assets overview.

Ressourcen

Ressourcen stellen die Entitäten in Ihrem Google Ads-Konto dar. Campaign und AdGroup sind zwei Beispiele für Ressourcen.

Objekt-IDs

Jedes Objekt in Google Ads wird durch eine eigene ID identifiziert. Einige dieser IDs sind global eindeutig für alle Google Ads-Konten, während andere nur innerhalb eines begrenzten Bereichs eindeutig sind.

Diese ID-Regeln können beim Entwerfen des lokalen Speichers für Ihre Google Ads-Objekte hilfreich sein.

Einige Objekte können für mehrere Entitätstypen verwendet werden. In solchen Fällen enthält das Objekt ein type-Feld, das den Inhalt beschreibt. For example, AdGroupAd kann sich beispielsweise auf ein Objekt wie eine responsive Suchanzeige, eine Hotelanzeige oder eine Demand Gen-Anzeige beziehen. Auf diesen Wert kann über das AdGroupAd.ad.type-Feld zugegriffen werden. Er gibt einen Wert in der AdType-Enumeration zurück. Beachten Sie, dass die Änderbarkeit je nach Version variieren kann (z. B. ist VideoResponsiveAdInfo für Ad in Version 24 und höher änderbar).

Ressourcennamen

Jede Ressource wird eindeutig durch einen resource_name-String identifiziert, der die Ressource und ihre übergeordneten Elemente zu einem Pfad zusammenfügt. Ressourcennamen für Kampagnen haben beispielsweise das folgende Format:

customers/customer_id/campaigns/campaign_id

Für eine Kampagne mit der ID 987654 im Google Ads-Konto mit der Kundennummer 1234567 wäre der resource_name also:

customers/1234567/campaigns/987654

Dienste

Mit Diensten können Sie Ihre Google Ads-Entitäten abrufen und ändern. Es gibt drei Arten von Diensten: Dienste zum Ändern, zum Abrufen von Objekten und Statistiken sowie zum Abrufen von Metadaten.

Objekte ändern (mutate)

Ressourcenspezifische Dienste ändern Instanzen eines zugehörigen Ressourcentyps mit einer mutate-Anfrage. Sie können auch GoogleAdsService.Mutate verwenden, um atomare Änderungen für mehrere Ressourcentypen in einer einzigen Anfrage vorzunehmen (z. B. um ein Kampagnenbudget, eine Kampagne und eine Anzeigengruppe zusammen zu erstellen).

Beispiele für ressourcenspezifische Dienste:

• CustomerService zum Ändern von Kunden.

• CampaignService zum Ändern von Kampagnen.

• AdGroupService zum Ändern von Anzeigengruppen.

Jede mutate-Anfrage muss entsprechende operation-Objekte enthalten. Beispielsweise erwartet die Methode CampaignService.MutateCampaigns eine oder mehrere Instanzen von CampaignOperation. Eine detaillierte Erläuterung der Vorgänge finden Sie unter Objekte ändern.

Gleichzeitige Änderungen

Ein Google Ads-Objekt kann nicht gleichzeitig von mehr als einer Quelle geändert werden. Dies kann zu Fehlern führen, wenn mehrere Nutzer dasselbe Objekt mit Ihrer App aktualisieren oder wenn Sie Google Ads-Objekte parallel mit mehreren Threads ändern. Dazu gehört auch das Aktualisieren des Objekts über mehrere Threads in derselben Anwendung oder über verschiedene Anwendungen (z. B. Ihre App und eine gleichzeitige Google Ads-Oberflächensitzung).

Die API bietet keine Möglichkeit, ein Objekt vor der Aktualisierung zu sperren. Wenn zwei Quellen versuchen, ein Objekt gleichzeitig zu ändern, gibt die API einen DatabaseError.CONCURRENT_MODIFICATION_ERROR aus.

Asynchrone und synchrone Änderungen

Die mutate-Methoden der Google Ads API sind synchron. API-Aufrufe geben erst dann eine Antwort zurück, wenn die Objekte geändert wurden. Sie müssen also auf eine Antwort auf jede Anfrage warten. Dieser Ansatz ist zwar relativ einfach zu programmieren, kann sich aber negativ auf das Load Balancing auswirken und Ressourcen verschwenden, wenn Prozesse auf den Abschluss von Aufrufen warten müssen.

Alternativ können Sie Objekte asynchron mit BatchJobService ändern. Dabei werden Batchvorgänge für mehrere Dienste ausgeführt, ohne auf deren Abschluss zu warten. Nachdem ein Batchvorgang gesendet wurde, führen die Google Ads API-Server Vorgänge asynchron aus, sodass Prozesse andere Vorgänge ausführen können. Sie können den Jobstatus regelmäßig auf Abschluss prüfen.

Weitere Informationen zur asynchronen Verarbeitung finden Sie im Leitfaden zur Batchverarbeitung.

mutate-Validierung

Die meisten Mutationsanfragen können validiert werden, ohne den Aufruf tatsächlich für echte Daten auszuführen. Sie können die Anfrage auf fehlende Parameter und falsche Feldwerte testen, ohne den Vorgang tatsächlich auszuführen.

Wenn Sie diese Funktion verwenden möchten, legen Sie das optionale boolesche Feld validate_only der Anfrage auf true fest. Die Anfrage wird vollständig validiert, als ob sie ausgeführt werden sollte, die endgültige Ausführung wird jedoch übersprungen. Wenn keine Fehler gefunden werden, wird die Antwort zurückgegeben, ohne dass geänderte Ergebnisse ausgefüllt werden (results ist leer). Wenn die Validierung fehlschlägt, schlägt die Anfrage standardmäßig mit einem GoogleAdsFailure-RPC Fehler fehl (partial_failure = false). Alternativ wird eine normale Antwort mit vorgangsspezifischen Fehlern in partial_failure_error zurückgegeben, wenn partial_failure = true.

validate_only ist besonders nützlich, um Anzeigen auf häufige Richtlinienverstöße zu testen. Anzeigen werden automatisch abgelehnt, wenn sie gegen Richtlinien verstoßen, z. B. wenn sie bestimmte Wörter, Satzzeichen, Groß- und Kleinschreibung oder eine bestimmte Länge haben. Eine einzelne fehlerhafte Anzeige kann dazu führen, dass ein ganzer Batch fehlschlägt. Wenn Sie eine neue Anzeige in einer validate_only-Anfrage testen, können Sie solche Verstöße erkennen. Im Codebeispiel zum Behandeln von Fehlern aufgrund von Richtlinienverstößen sehen Sie, wie das funktioniert.

Objekte und Leistungsstatistiken abrufen

GoogleAdsService ist der einzige einheitliche Dienst zum Abrufen von Objekten und Leistungsstatistiken.

Für alle Search und SearchStream-Anfragen für GoogleAdsService ist eine Abfrage erforderlich, in der die abzufragende Ressource, die abzurufenden Ressourcenattribute und Leistungsmesswerte angegeben werden, die für das Filtern der Anfrage zu verwendenden Prädikate und die Segmente mit denen die Leistungsstatistiken weiter aufgeschlüsselt werden sollen. Weitere Informationen zum Abfrageformat finden Sie im Leitfaden zur Google Ads Query Language.

Metadaten abrufen

GoogleAdsFieldService ruft Metadaten zu Ressourcen in der Google Ads API ab, z. B. die verfügbaren Attribute für eine Ressource und ihren Datentyp. Weitere Informationen zum Abfragen dieses Dienstes finden Sie im Leitfaden zu Ressourcenmetadaten.

Dieser Dienst liefert Informationen, die zum Erstellen einer Abfrage für GoogleAdsService erforderlich sind. Der Komfort halber sind die GoogleAdsFieldService zurückgegebenen Informationen auch in der Referenzdokumentation zu den Feldern verfügbar.