In diesem Leitfaden werden die Hauptkomponenten der Google Ads API vorgestellt. Die Google Ads API besteht aus Ressourcen und Diensten. Eine Ressource stellt ein Google Ads-Element dar, während Dienste Google Ads-Elemente 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 Ihre Anzeigen in logische Sammlungen gruppiert werden.
Eine Anzeigengruppenanzeige ist eine Anzeige, die Sie in einer Anzeigengruppe schalten. Mit Ausnahme von App-Kampagnen, die nur eine Anzeige pro Anzeigengruppe enthalten können, umfasst jede Anzeigengruppe eine oder mehrere Anzeigen.
Performance Max-Kampagnen haben eine andere Struktur als andere Kampagnentypen: Anstelle von Anzeigengruppen und Anzeigengruppenanzeigen enthalten Performance Max-Kampagnen Asset-Gruppen. Sie verknüpfen Creative-Assets mit einer Asset-Gruppe über AssetGroupAsset und hängen Zielgruppen- oder Suchthemensignale über AssetGroupSignal an.
Sie können einer Anzeigengruppe oder Kampagne eine oder mehrere AdGroupCriterion- oder CampaignCriterion-Ressourcen hinzufügen. Diese stellen Kriterien dar, die festlegen, 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 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.
Assets können auf Konto-, Kampagnen-, Anzeigengruppen- oder Asset-Gruppenebene angehängt werden. Mit Assets können Sie Ihren Anzeigen zusätzliche Informationen hinzufügen, z. B. Telefonnummern, Adressen oder Angebote. Weitere Informationen finden Sie unter Assets – Übersicht.
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 für alle Google Ads-Konten global eindeutig, andere nur innerhalb eines begrenzten Bereichs.
| Objekt-ID | Gültigkeitsbereich der Eindeutigkeit | Global eindeutig? |
|---|---|---|
| Budget-ID | Global | Ja |
| Kampagnen-ID | Global | Ja |
| Anzeigengruppen-ID | Global | Ja |
| Anzeigen-ID | Anzeigengruppe | Nein, aber das Paar aus AdGroupId und AdId ist global eindeutig. Die gemeinsame Nutzung von AdId in mehreren Anzeigengruppen ist nicht zulässig. |
| ID des Anzeigengruppenkriteriums | Anzeigengruppe | Nein, aber das Paar (AdGroupId, CriterionId) ist global eindeutig |
| ID des Kampagnenkriteriums | Kampagne | Nein, aber das Paar (CampaignId, CriterionId) ist global eindeutig |
| Label-ID | Kunde | Nein, aber das Paar (CustomerId, LabelId) ist global eindeutig |
| UserList ID | Global | Ja |
| Asset-ID | Global | Ja |
Diese ID-Regeln können beim Entwerfen des lokalen Speichers für Ihre Google Ads-Objekte nützlich 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. 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 Feld AdGroupAd.ad.type zugegriffen werden. Er gibt einen Wert im Enum AdType zurück. Beachten Sie, dass die Veränderbarkeit je nach Version variieren kann. Beispielsweise ist VideoResponsiveAdInfo in Ad in v24 und höher veränderbar.
Ressourcennamen
Jede Ressource wird eindeutig durch einen resource_name-String identifiziert, der die Ressource und ihre übergeordneten Elemente zu einem Pfad verkettet. Beispiel: Ressourcennamen von Kampagnen haben das Format:
customers/customer_id/campaigns/campaign_id
Für eine Kampagne mit der ID 987654 im Google Ads-Konto mit der Kundennummer 1234567 lautet 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: Änderungs-, Objekt- und Statistikabruf- sowie Metadatenabrufdienste.
Objekte ändern (mutieren)
Ressourcenspezifische Dienste ändern Instanzen eines zugehörigen Ressourcentyps mithilfe einer mutate-Anfrage. Sie können auch GoogleAdsService.Mutate verwenden, um atomare Mutationen für mehrere Ressourcentypen in einer einzigen Anfrage auszuführen (z. B. um ein Kampagnenbudget, eine Kampagne und eine Anzeigengruppe zusammen zu erstellen).
Beispiele für ressourcenspezifische Dienste:
CustomerServicezum Ändern von Kunden.CampaignServicezum Ändern von Kampagnen.AdGroupServicezum Ändern von Anzeigengruppen.
Jede mutate-Anfrage muss entsprechende operation-Objekte enthalten. Die Methode CampaignService.MutateCampaigns erwartet beispielsweise eine oder mehrere Instanzen von CampaignOperation. Eine ausführliche 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 Anwendung und eine gleichzeitige Google Ads-UI-Sitzung).
Die API bietet keine Möglichkeit, ein Objekt vor dem Aktualisieren zu sperren. Wenn zwei Quellen versuchen, ein Objekt gleichzeitig zu mutieren, gibt die API einen DatabaseError.CONCURRENT_MODIFICATION_ERROR 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 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.
Ein alternativer Ansatz besteht darin, Objekte asynchron mit BatchJobService zu mutieren. Dadurch werden Batches von Vorgängen für mehrere Dienste ausgeführt, ohne auf deren Abschluss zu warten. Nachdem ein Batchjob gesendet wurde, führen die Google Ads API-Server Vorgänge asynchron aus, sodass Prozesse für andere Vorgänge freigegeben werden. Sie können den Jobstatus regelmäßig auf Fertigstellung prüfen.
Weitere Informationen zur asynchronen Verarbeitung finden Sie im Leitfaden zur Batchverarbeitung.
mutate-Validierung
Die meisten Mutationsanfragen können validiert werden, ohne dass der Aufruf tatsächlich für echte Daten ausgeführt wird. 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, setzen Sie das optionale boolesche Feld validate_only der Anfrage auf true. Die Anfrage wird vollständig validiert, als ob sie ausgeführt werden würde, aber die endgültige Ausführung wird übersprungen. Wenn keine Fehler gefunden werden, wird die Antwort ohne geänderte Ergebnisse zurückgegeben (results ist leer). Wenn die Validierung fehlschlägt, schlägt die Anfrage standardmäßig mit einem RPC-Fehler GoogleAdsFailure (partial_failure = false) fehl oder gibt eine normale Antwort mit vorgangsspezifischen 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. wenn sie bestimmte Wörter, Satzzeichen, Großschreibung oder eine bestimmte Länge enthalten. Eine einzige unzulässige 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. Ein Beispiel hierzu finden Sie im Codebeispiel zum Umgang mit Richtlinienverstößen.
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 Prädikate zum Filtern der Anfrage und die Segmente zum weiteren Aufschlüsseln der Leistungsstatistiken angegeben sind. 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 stellt Informationen bereit, die zum Erstellen einer Abfrage für GoogleAdsService erforderlich sind. Die von GoogleAdsFieldService zurückgegebenen Informationen sind auch in der Referenzdokumentation zu Feldern verfügbar.