API-Struktur

Video: Der Vortrag zu Diensten und Ressourcen aus dem Workshop 2019

In diesem Leitfaden werden die wichtigsten Komponenten 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 hat eine oder mehrere aktive Kampagnen.

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

  • Eine Anzeigengruppe ist eine Anzeige, die Sie schalten. Mit Ausnahme von App-Kampagnen, die nur eine Anzeigengruppe pro Anzeigengruppe haben können, enthält jede Anzeigengruppe mindestens eine Anzeigengruppe.

Sie können einer Anzeigengruppe oder Kampagne eine oder mehrere AdGroupCriterion oder CampaignCriterion hinzufügen. Das sind Kriterien, die festlegen, wie Anzeigen ausgelöst werden.

Es gibt viele Kriterienstypen, z. B. Keywords, Altersgruppen und Standorte. Kriterien, die auf Kampagnenebene definiert sind, wirken sich auf alle anderen Ressourcen innerhalb der Kampagne aus. Sie können auch kampagnenweite Budgets und Zeiträume angeben.

Außerdem können Sie Erweiterungen auf Konto-, Kampagnen- oder Anzeigengruppenebene anhängen. Mithilfe von Erweiterungen können Sie Ihre Anzeigen um zusätzliche Informationen wie Telefonnummer, Adresse oder Angebote ergänzen.

Ressourcen

Ressourcen repräsentieren 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 einer eigenen ID identifiziert. Einige dieser IDs sind weltweit in allen Google Ads-Konten eindeutig, andere nur in einem begrenzten Umfang.

Objekt-ID Eindeutigkeit Weltweit 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.
Anzeigenerweiterungen Kampagne Nein, aber das Paar (CampaignId, AdExtensionId) 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
UserList-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 das Feld type, das den Inhalt beschreibt. AdGroupAd kann sich beispielsweise auf ein Objekt wie eine Textanzeige, eine Hotelanzeige oder eine lokale Anzeige beziehen. Auf diesen Wert kann über das Feld AdGroupAd.ad.type zugegriffen werden. Es wird ein Wert aus dem Enum AdType zurückgegeben.

Ressourcennamen

Jede Ressource wird durch einen eindeutigen resource_name-String identifiziert, der die Ressource und ihre übergeordneten Elemente zu einem Pfad zusammenfasst. Namen von Kampagnenressourcen haben beispielsweise das Format:

customers/customer_id/campaigns/campaign_id

Bei einer Kampagne mit der ID 987654 im Google Ads-Konto mit der Kundennummer 1234567 würde resource_name so aussehen:

customers/1234567/campaigns/987654

Dienste

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

Objekte ändern (mutieren)

Diese Dienste ändern Instanzen eines verknüpften Ressourcentyps mithilfe einer mutate-Anfrage. Außerdem wird eine get-Anfrage bereitgestellt, mit der eine einzelne Ressourceninstanz abgerufen wird. Das kann hilfreich sein, um die Struktur einer Ressource zu untersuchen.

Beispiele für Dienste:

Jede mutate-Anfrage muss entsprechende operation-Objekte enthalten. Für die Methode CampaignService.MutateCampaigns werden beispielsweise eine oder mehrere Instanzen von CampaignOperation erwartet. Eine ausführliche Beschreibung 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. 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 mutieren. 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-UI-Sitzung).

Die API bietet keine Möglichkeit, ein Objekt vor dem Aktualisieren zu sperren. Wenn zwei Quellen versuchen, ein Objekt gleichzeitig zu mutieren, löst die API eine DatabaseError.CONCURRENT_MODIFICATION_ERROR aus.

Asynchrone und synchrone Mutationen

Die Mutatmethoden der Google Ads API sind synchron. API-Aufrufe geben erst dann eine Antwort zurück, nachdem die Objekte mutiert 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 warten müssen, bis Aufrufe abgeschlossen sind.

Ein alternativer Ansatz besteht darin, Objekte asynchron mit BatchJobService zu mutieren. Dabei werden Batches von Vorgängen auf mehreren Diensten ausgeführt, ohne auf ihren Abschluss zu warten. Sobald ein Batchjob gesendet wurde, führen die Google Ads API-Server die Vorgänge asynchron aus und stellen Prozesse für andere Vorgänge frei. 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 Änderungsanfragen können validiert werden, ohne dass der Aufruf tatsächlich mit echten Daten ausgeführt wird. Sie können die Anfrage auf fehlende Parameter und falsche Feldwerte prüfen, ohne den Vorgang 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 würde sie ausgeführt, aber die endgültige Ausführung wird übersprungen. Wenn keine Fehler gefunden werden, wird eine leere Antwort zurückgegeben. Wenn die Validierung fehlschlägt, werden die Fehlerstellen in der Antwort in Fehlermeldungen angegeben.

validate_only ist besonders nützlich, um Anzeigen auf häufige Richtlinienverstöße zu prüfen. Anzeigen, die gegen Richtlinien verstoßen, z. B. durch bestimmte Wörter, Satzzeichen, Großschreibung oder Länge, werden automatisch abgelehnt. Eine einzige 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 solche Verstöße aufgedeckt werden. Im Codebeispiel zum Umgang mit Fehlern bei Richtlinienverstößen wird dies veranschaulicht.

Objekte und Leistungsstatistiken abrufen

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

Alle Search- und SearchStream-Anfragen für GoogleAdsService erfordern eine Abfrage, in der die abzufragende Ressource, die abzurufenden Ressourcenattribute und Leistungsmesswerte, die zum Filtern der Anfrage verwendeten Prädikate und die Segmente für eine weitere Aufschlüsselung der Leistungsstatistiken angegeben werden. 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 deren Datentyp.

Dieser Dienst liefert Informationen, die für die Erstellung einer Abfrage an GoogleAdsService erforderlich sind. Die von GoogleAdsFieldService zurückgegebenen Informationen sind auch in der Referenzdokumentation zu Feldern verfügbar.

Zurück
Übersicht
Weiter
Versionsverwaltung