API-Struktur

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Video: Sehen Sie sich den Vortrag zu Diensten und Ressourcen vom Workshop 2019 an.

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 oberste Ressource eines Kontos ist der Kunde.

  • Jedes Konto enthält mindestens eine aktive Kampagne.

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

  • Jeder AdGroup enthält eine oder mehrere Anzeigengruppenanzeigen. Ein AdGroupAd steht für eine von Ihnen geschaltete Anzeige.

Sie können eine oder mehrere AdGroupCriterion oder CampaignCriterion an eine Anzeigengruppe oder Kampagne anhängen. Diese stellen Kriterien dar, die festlegen, wie Anzeigen ausgelöst werden.

Es gibt viele Kriteriumstypen wie Keywords, Altersgruppen und Standorte. Kriterien, die auf Kampagnenebene definiert sind, wirken sich auf alle anderen Ressourcen in der Kampagne aus. Sie können auch kampagnenweite Budgets und Zeiträume festlegen.

Schließlich können Sie Erweiterungen auf Konto-, Kampagnen- oder Anzeigengruppenebene anhängen. Mit Erweiterungen können Sie Ihren Anzeigen zusätzliche Informationen wie Telefonnummer, Adresse oder Angebote hinzufügen.

Ressourcen

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

Objekt-IDs

Jedes Objekt in Google Ads wird anhand seiner eigenen ID identifiziert. Einige dieser IDs sind für alle Google Ads-Konten global eindeutig, andere nur innerhalb eines begrenzten Gültigkeitsbereichs.

Objekt-ID Eindeutigkeit Global eindeutig?
Budget-ID Global Ja
Kampagnen-ID Global Ja
Anzeigengruppen-ID Global Ja
Anzeigen-ID Anzeigengruppe Nein, aber (AdGroupId, AdId)-Paar ist global eindeutig
ID des Anzeigengruppenkriteriums Anzeigengruppe Nein, aber (AdGroupId, CriterionId)-Paar ist global eindeutig
ID des Kampagnenkriteriums Kampagne Nein, aber (CampaignId, CriterionId)-Paar ist global eindeutig
Anzeigenerweiterungen Kampagne Nein, aber (CampaignId, AdExtensionId)-Paar ist global eindeutig
Feed-ID Global Ja
ID des Feedelements Global Ja
Feed-Attribut-ID Feed Nein
Feed-Mapping-ID Global Ja
Label-ID Global Ja
UID-ID Global Ja

Diese ID-Regeln können hilfreich sein, wenn Sie lokalen Speicher für Ihre Google Ads-Objekte entwerfen.

Einige Objekte können für mehrere Entitätstypen verwendet werden. In solchen Fällen enthält das Objekt das Feld type, das seinen Inhalt beschreibt. AdGroupAd kann beispielsweise auf eine Textanzeige, eine Hotelanzeige, eine lokale Anzeige usw. verweisen. Auf diesen Wert kann über das Feld AdGroupAd.ad.type zugegriffen werden. Es wird ein Wert in der Aufzählung AdType zurückgegeben.

Ressourcennamen

Jede Ressource wird eindeutig durch einen resource_name-String identifiziert, der die Ressource und ihre übergeordneten Elemente zu einem Pfad verkettet. Die Ressourcennamen der Kampagne 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ürde resource_name so lauten:

customers/1234567/campaigns/987654

Dienste

Mit Diensten können Sie Ihre Google Ads-Entitäten abrufen und ändern. Es gibt drei Arten von Diensten: Änderung, Objekt- und Statistikabruf sowie Dienste zum Metadatenabruf.

Objekte ändern (mutieren)

Diese Dienste ändern Instanzen eines verknüpften Ressourcentyps mit einer mutate-Anfrage. Außerdem stellen sie eine get-Anfrage bereit, mit der eine einzelne Ressourceninstanz abgerufen wird, um die Struktur einer Ressource zu untersuchen.

Beispiele für Dienste:

Jede mutate-Anfrage muss die entsprechenden operation-Objekte enthalten. Für die Methode CampaignService.MutateCampaigns wird beispielsweise eine oder mehrere Instanzen von CampaignOperation erwartet. Ausführliche Informationen zu Vorgängen 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. Dies kann zu Fehlern führen, wenn mehrere Nutzer dasselbe Objekt mit Ihrer App aktualisieren oder wenn Sie Google Ads-Objekte mithilfe von mehreren Threads parallel mutieren. Dazu gehört die Aktualisierung des Objekts über mehrere Threads derselben Anwendung oder unterschiedlicher Anwendungen (z. B. Ihre Anwendung und eine gleichzeitige Google Ads-UI-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 den Fehler DatabaseError.CONCURRENT_MODIFICATION_ERROR aus.

Asynchrone vs. synchrone Mutate

Die Google Ads API-Mutate-Methoden sind synchron. API-Aufrufe geben erst nach dem Ändern von Objekten eine Antwort zurück. Sie müssen daher für jede Anfrage auf die Antwort warten. Dieser Ansatz lässt sich zwar relativ einfach programmieren, er könnte sich aber negativ auf das Load-Balancing und die Verschwendung von Ressourcen auswirken, wenn Prozesse auf den Abschluss von Aufrufen warten müssen.

Ein alternativer Ansatz besteht darin, Objekte asynchron mithilfe von MutateService zu ändern, der Batches von Vorgängen an mehreren Diensten ausführt, ohne auf den Abschluss des Vorgangs zu warten. Sobald ein Batchjob gesendet wurde, führen die Google Ads API-Server asynchrone Vorgänge aus. Dadurch werden Prozesse für andere Vorgänge frei. Sie können den Jobstatus regelmäßig überprüfen, um den Abschluss abzuschließen.

Im Leitfaden zur Batch-Verarbeitung finden Sie weitere Informationen zur asynchronen Verarbeitung.

mutate-Validierung

Die meisten Mutate-Anfragen können validiert werden, ohne den Aufruf tatsächlich mit echten Daten auszuführen. Sie können die Anfrage auf fehlende Parameter und falsche Feldwerte testen, ohne den Vorgang tatsächlich auszuführen.

Wenn Sie dieses Feature 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 würde. 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 hilfreich, um Anzeigen auf häufige Richtlinienverstöße zu testen. Anzeigen werden automatisch abgelehnt, wenn sie gegen Richtlinien wie bestimmte Wörter, Satzzeichen, Großschreibung oder Länge verstoßen. Eine einzelne fehlerhafte Anzeige kann dazu führen, dass ein gesamter Batch fehlschlägt. Wenn Sie eine neue Anzeige innerhalb einer validate_only-Anfrage testen, können Sie entsprechende Verstöße erkennen. Im Codebeispiel zur Behandlung von Fehlern bei Richtlinienverstößen wird dies veranschaulicht.

Objekte und Leistungsstatistiken abrufen

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

Alle Search- und SearchStream-Anfragen für GoogleAdsService erfordern eine Abfrage, die die abzufragende Ressource, die abzurufenden Ressourcenattribute und Leistungsmesswerte, die für das Filtern der Anfrage zu verwendenden Prädikate sowie die Segmente zum weiteren Aufschlüsseln der Leistungsstatistiken angibt. Weitere Informationen zum Abfrageformat finden Sie im Google Ads-Leitfaden zur Abfragesprache.

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 bietet Informationen, die Sie beim Erstellen einer Abfrage an GoogleAdsService benötigen. Der Einfachheit halber sind die von GoogleAdsFieldService zurückgegebenen Informationen auch in der Referenzdokumentation zu Feldern verfügbar.

Zurück
Übersicht
Weiter
Entitätsbeziehungen