API-Struktur

Video: Das Gespräch zu Diensten und Ressourcen aus dem Workshop 2019

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 eine Hierarchie von Objekten betrachtet werden.

Kampagnenmodell

  • Die oberste Ressource eines Kontos ist der Kunde.

  • Jeder Kunde enthält mindestens eine aktive Kampagne.

  • Jede Kampagne enthält eine oder mehrere Anzeigengruppen, in denen Ihre Anzeigen in logischen Sammlungen zusammengefasst sind.

  • Eine Anzeige in einer Anzeigengruppe steht für eine Anzeige, die Sie schalten. Mit Ausnahme von App-Kampagnen, die nur eine Anzeige pro Anzeigengruppe enthalten können, enthält jede Anzeigengruppe eine oder mehrere Anzeigengruppenanzeigen.

Sie können einer Anzeigengruppe oder Kampagne ein oder mehrere AdGroupCriterion oder CampaignCriterion hinzufügen. Diese stellen Kriterien dar, die bestimmen, 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 kampagnenweite Budgets und Zeiträume festlegen.

Außerdem können Erweiterungen auf Konto-, Kampagnen- oder Anzeigengruppenebene hinzugefügt werden. Mit Erweiterungen können Sie Ihren Anzeigen zusätzliche Informationen wie Telefonnummer, Adresse oder Angebote hinzufügen.

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 seiner eigenen ID identifiziert. Einige dieser IDs sind global in allen Google Ads-Konten eindeutig, während andere nur innerhalb eines begrenzten Geltungsbereichs eindeutig sind.

Objekt-ID Umfang der Eindeutigkeit Global einzigartig?
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
ID des Anzeigengruppenkriteriums Anzeigengruppe Nein, aber das Paar aus AdGroupId und CriterionId ist global eindeutig
ID des Kampagnenkriteriums Kampagne Nein, aber das Paar aus CampaignId und CriterionId ist global eindeutig
Anzeigenerweiterungen Kampagne Nein, aber das Paar aus CampaignId und 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
Nutzerlisten-ID Global Ja

Diese ID-Regeln sind beim Entwerfen eines lokalen Speichers für Ihre Google Ads-Objekte hilfreich.

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

Ressourcennamen

Jede Ressource ist eindeutig durch einen resource_name-String gekennzeichnet, der die Ressource und ihre übergeordneten Ressourcen zu einem Pfad verkettet. Kampagnenressourcennamen 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 also der 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: Änderungs-, Objekt- und Statistikabruf sowie Metadaten-Abruf.

Objekte ändern (mutate)

Diese Dienste ändern Instanzen eines verknüpften Ressourcentyps mithilfe einer mutate-Anfrage. Sie stellen auch eine get-Anfrage bereit, mit der eine einzelne Ressourceninstanz abgerufen wird. Dies kann hilfreich 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. 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 Anwendung aktualisieren oder wenn Sie Google Ads-Objekte gleichzeitig mithilfe mehrerer Threads ändern. Dazu gehört auch das Aktualisieren des Objekts über mehrere Threads in derselben Anwendung oder in verschiedenen 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“-Vorgänge

Die mutate-Methoden der Google Ads API sind synchron. API-Aufrufe geben erst nach dem Ändern der Objekte 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 kann sich aber negativ auf das Load-Balancing und die Verschwendung von Ressourcen auswirken, wenn Prozesse auf den Abschluss von Aufrufen warten müssen.

Alternativ können Sie Objekte asynchron mit BatchJobService ändern. Dabei werden Vorgänge für mehrere Dienste in Batches ausgeführt, ohne auf den Abschluss warten zu müssen. Nachdem ein Batch-Auftrag gesendet wurde, werden die Vorgänge von den Google Ads API-Servern asynchron ausgeführt. Dadurch bleiben Prozesse für andere Vorgänge verfügbar. Sie können den Jobstatus regelmäßig für den Abschluss prüfen.

Weitere Informationen zur asynchronen Verarbeitung finden Sie im Leitfaden zur Batch-Verarbeitung.

mutate-Validierung

Die meisten mutate-Anfragen 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, 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, aber die endgültige Ausführung wird übersprungen. Wenn keine Fehler gefunden werden, wird eine leere Antwort zurückgegeben. Wenn die Validierung fehlschlägt, weisen Fehlermeldungen in der Antwort die Fehler auf.

validate_only ist besonders hilfreich, 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 Länge enthalten. Eine einzelne unerwünschte Anzeige kann dazu führen, dass ein ganzes Batch fehlschlägt. Wenn Sie bei einer validate_only-Anfrage eine neue Anzeige testen, können Sie solche Verstöße ermitteln. Im Codebeispiel zur Behandlung von Fehlern bei Richtlinienverstößen können Sie dies in Aktion sehen.

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, in der die abzufragende Ressource, die abzurufenden Ressourcenattribute und Leistungsmesswerte, die Prädikate zum Filtern der Anfrage und die Segmente angegeben sind, die zur weiteren Aufschlüsselung von Leistungsstatistiken verwendet 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 ihren Datentyp.

Dieser Dienst stellt Informationen bereit, die zum Erstellen einer Abfrage an GoogleAdsService erforderlich sind. Der Einfachheit halber finden Sie die von GoogleAdsFieldService zurückgegebenen Informationen auch in der Referenzdokumentation für Felder.

Zurück
Überblick
Weiter
Entitätsbeziehungen