API-Struktur

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

In diesem Leitfaden werden die primären Komponenten der Google Ads API vorgestellt. Die Google Ads API besteht aus Ressourcen und Diensten. Eine Ressource stellt eine Google Ads-Einheit dar, während mit Diensten Google Ads-Einheiten abgerufen und bearbeitet werden.

Objekthierarchie

Ein Google Ads-Konto kann als Hierarchie von Objekten betrachtet werden.

Kampagnenmodell

  • Die Ressource der obersten Ebene eines Kontos ist customer.

  • Jeder Kunde hat mindestens eine aktive Kampagne.

  • Jede Kampagne enthält eine oder mehrere Anzeigengruppen, mit denen Sie Ihre Anzeigen in logischen Gruppen zusammenfassen können.

  • Eine Anzeigengruppenanzeige ist eine Anzeige, die Sie schalten. Mit Ausnahme von App-Kampagnen, die nur eine Anzeigengruppenanzeige pro Anzeigengruppe enthalten können, umfasst jede Anzeigengruppe mindestens eine Anzeigengruppenanzeige.

Sie können einer Anzeigengruppe oder Kampagne ein oder mehrere AdGroupCriterion oder CampaignCriterion hinzufügen. Diese Kriterien 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 Erweiterungen auf Konto-, Kampagnen- oder Anzeigengruppenebene hinzufügen. Mit Erweiterungen können Sie Ihre Anzeigen mit zusätzlichen Informationen wie Telefonnummer, Adresse oder Angeboten ergänzen.

Ressourcen

Ressourcen stellen die Einheiten 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 weltweit für alle Google Ads-Konten eindeutig, andere nur innerhalb eines bestimmten Bereichs.

Objekt-ID Umfang 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.
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.
Label-ID Global Ja
UserList 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 seinen Inhalt beschreibt. Beispielsweise kann AdGroupAd auf ein Objekt wie eine Textanzeige, eine Hotelanzeige oder eine lokale Anzeige verweisen. Auf diesen Wert kann über das Feld AdGroupAd.ad.type zugegriffen werden. Er gibt einen Wert im Enum AdType zurück.

Ressourcennamen

Jede Ressource wird eindeutig durch einen resource_name-String identifiziert, der die Ressource und ihre übergeordneten Elemente zu einem Pfad zusammenfasst. 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 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 (mutieren)

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 wird. Das kann nützlich 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 ein 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 ändern. Dazu gehört das Aktualisieren des Objekts über mehrere Threads in derselben Anwendung oder über verschiedene Anwendungen (z. B. Ihre App und eine gleichzeitige Google Ads-Benutzeroberflä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-Fehler 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 den Lastenausgleich auswirken und Ressourcen verschwenden, wenn Prozesse gezwungen sind, auf den Abschluss von Aufrufen zu warten.

Alternativ können Sie Objekte asynchron mit BatchJobService ändern. Dabei werden Batches von Vorgängen für mehrere Dienste ausgeführt, ohne auf den Abschluss zu warten. Nachdem ein Batch-Job gesendet wurde, führen die Google Ads API-Server Vorgänge asynchron aus. So werden Prozesse für andere Vorgänge freigegeben. Sie können den Jobstatus regelmäßig prüfen, um festzustellen, ob der Job abgeschlossen ist.

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, setzen Sie das optionale boolesche Feld validate_only der Anfrage auf true. 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 nützlich, um Anzeigen auf häufige Richtlinienverstöße zu testen. Anzeigen werden automatisch abgelehnt, wenn sie gegen Richtlinien verstoßen, z. B. in Bezug auf bestimmte Wörter, Satzzeichen, Groß- und Kleinschreibung oder Länge. 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. Ein Codebeispiel für die Behandlung von Richtlinienverstoßfehlern finden Sie hier.

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 zum Filtern der Anfrage verwendeten Prädikate und die Segmente angegeben werden, mit denen die Leistungsstatistiken weiter aufgeschlüsselt 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 ihr Datentyp.

Dieser Dienst liefert Informationen, die zum Erstellen einer Anfrage an GoogleAdsService erforderlich sind. Die von GoogleAdsFieldService zurückgegebenen Informationen sind auch in der Referenzdokumentation zu Feldern verfügbar.

Zurück
Übersicht
Weiter
Versionsverwaltung