API-Struktur

Video: Check out the Services and Resources talk from the 2019 workshop

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.

Kampagnenmodell

  • 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 schalten. Mit Ausnahme von App-Kampagnen, die nur eine Anzeigengruppenanzeige pro Anzeigengruppe haben können, enthält jede Anzeigengruppe eine oder mehrere Anzeigengruppenanzeigen.

Sie können einer Anzeigengruppe oder Kampagne ein oder mehrere AdGroupCriterion oder CampaignCriterion zuordnen. 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 kampagnenweite Budgets und Zeiträume angeben.

Schließlich können Sie Assets auf Konto-, Kampagnen- oder Anzeigengruppenebene zuordnen. Mit Assets können Sie Ihren Anzeigen zusätzliche Informationen wie Telefonnummern, Adressen oder Angebote hinzufügen. Siehe Übersicht über Assets.

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, andere sind nur innerhalb eines begrenzten Bereichs eindeutig.

Objekt-ID Bereich der Eindeutigkeit Global eindeutig?
Budget-ID Global Ja
Kampagnen-ID Global Ja
Anzeigengruppen-ID Global Ja
Anzeigen-ID Anzeigengruppe Nein, aber das Paar (AdGroupId, AdId) ist global eindeutig
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
Nutzerlisten-ID Global Ja
Asset-ID Global Ja

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 den Inhalt beschreibt. Beispielsweise kann sich AdGroupAd auf ein Objekt wie eine Textanzeige, eine Hotelanzeige oder eine lokale Anzeige beziehen. Auf diesen Wert kann über das AdGroupAd.ad.type Feld zugegriffen werden. Er gibt einen Wert in der AdType Aufzählung zurück.

Ressourcennamen

Jede Ressource wird eindeutig durch einen String resource_name 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)

Mit diesen Diensten werden Instanzen eines zugehörigen Ressourcentyps mithilfe einer mutate-Anfrage geändert. Sie stellen auch eine get-Anfrage bereit, mit der eine einzelne Ressourceninstanz abgerufen werden kann. Das kann nützlich sein, um die Struktur einer Ressource zu untersuchen.

Beispiele für Dienste:

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 und prüfen.

Gleichzeitige Änderungen

Ein Google Ads-Objekt kann nicht gleichzeitig von mehr als einer Quelle geändert werden. Das 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 Google Ads API-Methoden zum Ändern 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 den Lastenausgleich auswirken und Ressourcen verschwenden, wenn Prozesse auf den Abschluss von Aufrufen warten müssen.

Eine alternative Methode besteht darin, Objekte asynchron mit BatchJobService zu ändern. Dabei werden Batchvorgänge für mehrere Dienste ausgeführt, ohne auf deren Abschluss zu warten. Sobald ein Batchjob 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 mutate-Anfragen 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 dann vollständig validiert, als ob sie ausgeführt werden sollte. Die endgültige Ausführung wird jedoch übersprungen. Wenn keine Fehler gefunden werden, wird eine leere Antwort zurückgegeben. Wenn die Validierung fehlschlägt, geben Fehlermeldungen in der Antwort die Fehlerpunkte an.

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 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 aufdecken. Im Codebeispiel zur Behandlung 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, die Prädikate zum Filtern der Anfrage und die Segmente zum weiteren Aufschlüsseln der Leistungsstatistiken angegeben werden. Weitere Informationen zum Abfrageformat, siehe den 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.

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.

Zurück
Übersicht
Weiter
Versionsverwaltung