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-Einheit dar, während mit Diensten Google Ads-Einheiten abgerufen und bearbeitet werden.

Objekthierarchie

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

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

• Jeder Kunde hat mindestens eine aktive Kampagne.

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

• Eine Anzeigengruppenanzeige ist eine Anzeige, die Sie in einer Anzeigengruppe schalten. Mit Ausnahme von App-Kampagnen, die pro Anzeigengruppe nur eine Anzeigengruppenanzeige enthalten können, umfasst jede Anzeigengruppe eine oder mehrere Anzeigengruppenanzeigen.

Performance Max-Kampagnen haben eine andere Struktur als andere Kampagnentypen: Anstelle von Anzeigengruppen und Anzeigen in Anzeigengruppen enthalten sie Asset-Gruppen. Sie verknüpfen Creative-Assets mit einer Asset-Gruppe über AssetGroupAsset und fügen Zielgruppen- oder Suchthemensignale über AssetGroupSignal hinzu.

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

Es gibt viele Kriterientypen, z. B. Keywords, Altersgruppen und Standorte. Kriterien, die auf Kampagnenebene definiert werden, wirken sich auf alle anderen Ressourcen innerhalb der Kampagne aus. Sie können auch Budgets sowie Start- und Enddaten und ‑zeiten für Kampagnen oder für einzelne Anzeigen mit AdGroupAd.start_date_time und AdGroupAd.end_date_time angeben.

Außerdem können Sie Assets auf Konto-, Kampagnen-, Anzeigengruppen- oder Asset-Gruppenebene anhängen. Mit Assets können Sie Ihren Anzeigen zusätzliche Informationen wie Telefonnummern, Adressen oder Angebote hinzufügen. Weitere Informationen finden Sie unter Übersicht über Assets.

Ressourcen

Ressourcen stellen die Einheiten 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 weltweit eindeutig für alle Google Ads-Konten, andere nur innerhalb eines bestimmten Bereichs.

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 Feld type, das seinen Inhalt beschreibt. Beispiel: AdGroupAd kann sich auf ein Objekt wie eine responsive Suchanzeige, eine Hotelanzeige oder eine Demand Gen-Anzeige beziehen. Auf diesen Wert kann über das Feld AdGroupAd.ad.type zugegriffen werden. Er gibt einen Wert im Enum AdType zurück. Die Unveränderlichkeit kann je nach Version variieren (z. B. ist VideoResponsiveAdInfo auf Ad in Version 24 und höher veränderbar).

Ressourcennamen

Jede Ressource wird eindeutig durch einen resource_name-String identifiziert, in dem die Ressource und ihre übergeordneten Elemente zu einem Pfad verkettet werden. Ressourcennamen von 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 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 (mutieren)

Ressourcenspezifische Dienste ändern Instanzen eines zugehörigen Ressourcentyps mithilfe einer mutate-Anfrage. Sie können auch GoogleAdsService.Mutate verwenden, um atomare Änderungen für mehrere Ressourcentypen in einer einzelnen Anfrage vorzunehmen, z. B. um ein Kampagnenbudget, eine Kampagne und eine Anzeigengruppe gleichzeitig 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. Für die Methode CampaignService.MutateCampaigns werden beispielsweise eine oder mehrere Instanzen von CampaignOperation erwartet. Eine detaillierte Beschreibung der Vorgänge finden Sie unter Change-Objekte.

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. Das kann passieren, wenn das Objekt aus mehreren Threads in derselben Anwendung oder aus verschiedenen Anwendungen aktualisiert wird, z. B. aus Ihrer App und einer gleichzeitigen Google Ads-Sitzung.

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-Fehler aus.

Asynchrone und synchrone Mutationen

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 die Antwort auf jede Anfrage warten. Dieser Ansatz ist zwar relativ einfach zu programmieren, kann sich aber negativ auf den Lastenausgleich auswirken und Ressourcen verschwenden, wenn Prozesse gezwungen sind, auf den Abschluss von Aufrufen zu warten.

Alternativ können Sie Objekte asynchron mit BatchJobService ändern. Dabei werden Batches von Vorgängen für mehrere Dienste ausgeführt, ohne auf den Abschluss zu warten. Nachdem ein Batchjob gesendet wurde, führen die Google Ads API-Server Vorgänge asynchron aus. So können Prozesse andere Vorgänge ausführen. Sie können den Jobstatus regelmäßig prüfen, um festzustellen, ob der Job abgeschlossen ist.

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

mutate-Validierung

Die meisten Mutate-Anfragen können validiert werden, ohne dass der Aufruf für echte Daten ausgeführt werden muss. Sie können die Anfrage auf fehlende Parameter und falsche Feldwerte testen, ohne den Vorgang tatsächlich auszuführen.

Wenn Sie dieses Feature nutzen möchten, setzen Sie das optionale boolesche Feld validate_only der Anfrage auf true. Die Anfrage wird vollständig validiert, als ob sie ausgeführt würde, die endgültige Ausführung wird jedoch übersprungen. Wenn keine Fehler gefunden werden, wird die Antwort ohne mutierte Ergebnisse zurückgegeben (results ist leer). Wenn die Validierung fehlschlägt, schlägt die Anfrage standardmäßig mit einem GoogleAdsFailure-RPC-Fehler (partial_failure = false) fehl oder gibt eine normale Antwort mit betriebsspezifischen Fehlern in partial_failure_error zurück, 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. bestimmte Wörter, Satzzeichen, Groß- und Kleinschreibung oder Längenangaben enthalten. 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 aufdecken. Ein Beispiel dafür finden Sie im Codebeispiel für die Behandlung von Richtlinienverstoßfehlern.

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, die zum Filtern der Anfrage verwendeten Prädikate und die Segmente angegeben werden, mit denen die Leistungsstatistiken weiter aufgeschlüsselt werden sollen. Weitere Informationen zum Abfrageformat finden Sie im Leitfaden zur Google Ads Query Language.

Metadaten abrufen

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

Dieser Dienst liefert Informationen, die zum Erstellen einer Anfrage an GoogleAdsService erforderlich sind. Die von GoogleAdsFieldService zurückgegebenen Informationen sind auch in der Felder-Referenzdokumentation verfügbar.