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.
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:
CustomerService
zum Ändern von Kunden.CampaignService
zum Ändern von KampagnenAdGroupService
zum Ändern von Anzeigengruppen
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.