Video: Sehen Sie sich das Gespräch 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 Google Ads-Entitäten von Diensten abgerufen und bearbeitet werden.
Objekthierarchie
Ein Google Ads-Konto kann als Hierarchie von Objekten betrachtet werden.
Die oberste Ressource eines Kontos ist der Kunde.
Jeder Kunde umfasst mindestens eine aktive Kampagne.
Jede Kampagne enthält eine oder mehrere Anzeigengruppen, in denen Ihre Anzeigen in logischen Gruppen zusammengefasst sind.
Eine Anzeige in einer Anzeigengruppe ist eine von Ihnen ausgelieferte Anzeige. Mit Ausnahme von App-Kampagnen, die nur eine Anzeigengruppe pro Anzeigengruppe enthalten können, enthält jede Anzeigengruppe eine oder mehrere Anzeigengruppen-Anzeigen.
Sie können ein oder mehrere AdGroupCriterion- oder CampaignCriterion-Elemente 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 Termine 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 Werbung hinzufügen.
Weitere Informationen
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 durch eine eigene ID identifiziert. Einige dieser IDs sind in allen Google Ads-Konten global eindeutig, andere nur innerhalb eines begrenzten Gültigkeitsbereichs.
| 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 (AdGroupId, AdId)-Paar ist global eindeutig |
| ID des Anzeigengruppenkriteriums | Anzeigengruppe | Nein, aber das (AdGroupId, CriterionId)-Paar ist global eindeutig |
| ID des Kampagnenkriteriums | Kampagne | Nein, aber das (CampaignId, CriterionId)-Paar ist global eindeutig |
| Anzeigenerweiterungen | Kampagne | Nein, aber das (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 |
| Nutzerlisten-ID | Global | Ja |
Diese ID-Regeln können hilfreich sein, wenn Sie den 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 ein type-Feld, das seinen Inhalt beschreibt. Beispielsweise kann sich AdGroupAd 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. 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 in einem Pfad verkettet. Kampagnenressourcennamen haben beispielsweise folgendes Format:
customers/customer_id/campaigns/campaign_id
Für eine Kampagne mit der ID 987654 im Google Ads-Konto mit der Kundennummer 1234567 sähe der resource_name also so aus:
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 Metadatenabrufdienste.
Objekte ändern (mutate)
Diese Dienste ändern Instanzen eines verknüpften Ressourcentyps mit einer mutate-Anfrage. Sie liefern auch eine get-Anfrage, die eine einzelne Ressourceninstanz abruft, was nützlich sein kann, um die Struktur einer Ressource zu untersuchen.
Beispiele für Dienste:
CustomerServicezum Ändern von KundenCampaignServicezum Ändern von Kampagnen.AdGroupServicezum Ändern von Anzeigengruppen
Jede mutate-Anfrage muss entsprechende operation-Objekte enthalten. Die Methode CampaignService.MutateCampaigns erwartet beispielsweise eine oder mehrere Instanzen von CampaignOperation. 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 Anwendung aktualisieren oder wenn Sie Google Ads-Objekte mit mehreren Threads parallel ändern. Dazu gehört auch die Aktualisierung des Objekts über mehrere Threads derselben Anwendung oder verschiedener Anwendungen, z. B. Ihrer Anwendung und einer gleichzeitig stattfindenden 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, löst die API den Fehler DatabaseError.CONCURRENT_MODIFICATION_ERROR aus.
Asynchrone und synchrone „mutate“-Vorgänge
Die mutate-Methoden der Google Ads API sind synchron. API-Aufrufe geben erst nach dem Ändern von Objekten eine Antwort zurück. Sie müssen also für jede Anfrage auf eine Antwort warten. Dieser Ansatz lässt sich zwar relativ einfach programmieren, er könnte sich jedoch negativ auf das Load-Balancing und die Ressourcenverschwendung auswirken, wenn Prozesse auf den Abschluss von Aufrufen warten müssen.
Ein alternativer Ansatz besteht darin, Objekte asynchron mit BatchJobService zu ändern. Dabei werden Batch-Vorgänge für mehrere Dienste ausgeführt, ohne auf deren Abschluss zu warten. Nachdem ein Batch-Auftrag gesendet wurde, führen die Google Ads API-Server die Vorgänge asynchron aus. Dadurch werden Prozesse für andere Vorgänge frei. Sie können regelmäßig prüfen, ob der Jobstatus abgeschlossen ist.
Weitere Informationen zur asynchronen Verarbeitung finden Sie im Leitfaden zur Batch-Verarbeitung.
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, aber die letzte Ausführung wird ü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 überprüfen. Anzeigen werden automatisch abgelehnt, wenn sie gegen Richtlinien wie bestimmte Wörter, Zeichensetzung, Großschreibung oder Länge verstoßen. Eine einzelne fehlerhafte Anzeige kann dazu führen, dass ein ganzer Batch fehlschlägt. Wenn Sie eine neue Anzeige innerhalb einer validate_only-Anfrage testen, können Sie solche Verstöße aufdecken. 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, in der die abzufragende Ressource, die abzurufenden Ressourcenattribute und Leistungsmesswerte, die zum Filtern der Anfrage zu verwendenden Prädikate und die Segmente angegeben sind, mit denen Leistungsstatistiken weiter aufgegliedert 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 ihr Datentyp.
Dieser Dienst stellt Informationen bereit, die zum Erstellen einer Abfrage für GoogleAdsService erforderlich sind. Der Einfachheit halber finden Sie die von GoogleAdsFieldService zurückgegebenen Informationen auch in der Referenzdokumentation zu Feldern.