API-Struktur

ondemand_video 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 Die Google Ads API besteht aus Ressourcen und Diensten. Eine Ressource stellt eine Google Ads- Entität, während Google Ads-Entitäten mithilfe 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 sein.

• Jeder Kunde enthält mindestens einen aktiven Kampagnen.

• Jede Kampagne enthält eine oder mehrere Anzeigengruppen. um Ihre Anzeigen in logischen Sammlungen zu gruppieren.

• Eine Anzeige in einer Anzeigengruppe ist eine Anzeige, die Sie ausgeführt wird. Außer bei App-Kampagnen, die nur eine Anzeigengruppe pro Anzeige enthalten können enthält, enthält jede Anzeigengruppe mindestens eine Anzeigengruppe.

Sie können ein oder mehrere AdGroupCriterion anhängen oder CampaignCriterion auf eine Anzeigengruppe oder Kampagne. Diese stellen Kriterien dar, die festlegen, wie Anzeigen ausgelöst werden.

Es gibt viele Kriteriumstypen. etwa Keywords, Altersgruppen und Standorte. In der Kampagne definierte Kriterien auf alle anderen Ressourcen in der Kampagne. Sie können auch angeben, kampagnenweite Budgets und Termine.

Schließlich können Sie am Ende der Seite Erweiterungen Konto-, Kampagnen- oder Anzeigengruppenebene. Mit Erweiterungen können Sie Informationen zu Ihren Anzeigen hinzufügen, wie Telefonnummer, Adresse oder Werbung.

Ressourcen

Ressourcen repräsentieren die Entitäten in Ihrem Google Ads-Konto. Campaign und AdGroup sind zwei Beispiele. von Ressourcen.

Objekt-IDs

Jedes Objekt in Google Ads wird durch eine eigene ID identifiziert. Einige dieser IDs sind weltweit eindeutig über alle Google Ads-Konten hinweg, während andere nur innerhalb in einen begrenzten Umfang.

Diese ID-Regeln können hilfreich sein, wenn Sie den lokalen Speicher für Ihre Google Ads-Kampagnen entwerfen. Objekte.

Einige Objekte können für mehrere Entitätstypen verwendet werden. In solchen Fällen wird das Objekt enthält ein type-Feld, das den Inhalt beschreibt. Beispiel: AdGroupAd kann auf ein Objekt wie eine Textanzeige verweisen, Hotelanzeige oder lokale Anzeige. Auf diesen Wert kann über die AdGroupAd.ad.type und gibt einen Wert im Feld AdType-Enum.

Ressourcennamen

Jede Ressource wird eindeutig durch einen resource_name-String identifiziert, der verkettet die Ressource und ihre übergeordneten Elemente zu einem Pfad. Beispiel: Kampagne Ressourcennamen haben 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 der resource_name:

customers/1234567/campaigns/987654

Dienste

Mit Diensten können Sie Ihre Google Ads-Entitäten abrufen und ändern. Es gibt drei Arten von von Diensten: Änderung, Objekt- und Statistikabruf sowie Metadatenabruf. .

Objekte ändern (mutate)

Diese Dienste ändern Instanzen eines verknüpften Ressourcentyps mithilfe einer mutate Sie liefern außerdem eine get-Anfrage, mit der eine einzelne Ressource abgerufen wird -Instanz, die bei der Untersuchung der Struktur einer Ressource nützlich sein kann.

Beispiele für Dienste:

• CustomerService zum Ändern Kunden.

• CampaignService zum Ändern Kampagnen.

• AdGroupService zum Ändern von Anzeigengruppen

Jede mutate-Anfrage muss entsprechende operation-Objekte enthalten. Für Beispiel: Die Methode CampaignService.MutateCampaigns erwartet mindestens Instanzen von CampaignOperation. Weitere Informationen finden Sie unter Objekte ändern und prüfen ausführlicher über Operationen.

Gleichzeitige Änderungen

Ein Google Ads-Objekt kann nicht gleichzeitig von mehr als einer Quelle geändert werden. Dieses Es können Fehler auftreten, wenn mehrere Nutzer dasselbe Objekt mit Ihrer App verknüpfen oder wenn Sie Google Ads-Objekte parallel mithilfe mehrerer Threads. Dazu gehört auch das Aktualisieren des Objekts von mehreren Threads im selben oder aus verschiedenen Anwendungen (z. B. Ihrer App und einem gleichzeitig durchgeführte Sitzung auf der Google Ads-Benutzeroberfläche.

Die API bietet keine Möglichkeit, ein Objekt vor der Aktualisierung zu sperren. wenn zwei Quellen gleichzeitig versuchen, ein Objekt zu ändern, löst die API den Fehler DatabaseError.CONCURRENT_MODIFICATION_ERROR

Asynchrone und synchrone „mutate“-Vorgänge

Die mutate-Methoden der Google Ads API sind synchron. API-Aufrufe geben nur eine Antwort zurück nach dem Ändern der Objekte, sodass Sie für jedes Objekt auf eine Antwort warten müssen. Dieser Ansatz lässt sich zwar relativ einfach programmieren, sich negativ auf das Load-Balancing und die Ressourcenverschwendung auswirken, wenn Prozesse gezwungen werden, auf den Abschluss der Anrufe warten.

Alternativ können Sie Objekte asynchron mit BatchJobService, die Batches von Vorgänge für mehrere Dienste ausführen, ohne auf deren Abschluss warten zu müssen. Sobald ein gesendet wird, führen Google Ads API-Server Vorgänge asynchron aus und Prozesse für andere Vorgänge freigegeben. Sie können regelmäßig prüfen, für den Abschluss des Jobs angezeigt.

Im Leitfaden zur Batch-Verarbeitung finden Sie weitere Informationen: asynchrone Verarbeitung.

mutate-Validierung

Die meisten mutate-Anfragen können validiert werden, ohne den Aufruf tatsächlich auszuführen mit echten Daten vergleichen. Sie können die Anfrage auf fehlende Parameter und falsche ohne den Vorgang 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 aber die endgültige Ausführung wird übersprungen. Wenn keine Fehler gefunden werden, ist ein leeres -Antwort zurückgegeben. Wenn die Validierung fehlschlägt, die Fehlerquellen anzeigen.

validate_only ist besonders hilfreich beim Testen von Anzeigen im Hinblick auf eine gemeinsame Richtlinie. Verstöße. Anzeigen werden automatisch abgelehnt, wenn sie gegen folgende Richtlinien verstoßen: Bestimmte Wörter, Satzzeichen, Großschreibung oder Länge Eine einzelne unzulässige Anzeige kann dazu führen, dass ein gesamter Batch fehlschlägt. Neue Anzeige in einem validate_only testen solche Verstöße aufdecken können. Weitere Informationen finden Sie im Codebeispiel für die Verarbeitung von Fehler aufgrund von Richtlinienverstößen, um zu sehen, in Aktion sehen.

Objekte und Leistungsstatistiken abrufen

GoogleAdsService ist die einzelne, einheitliche Dienst zum Abrufen von Objekten und Leistungsstatistiken

Alle Search- und SearchStream-Anfragen für GoogleAdsService erfordern eine Abfrage, die die Ressource angibt, die die Ressourcenattribute und Leistungsmesswerte, die abgerufen werden sollen, Prädikate zum Filtern der Anfrage und die Segmente, mit denen weitere Aufschlüsselung der Leistungsstatistiken. Weitere Informationen zum Abfrageformat finden Sie im Leitfaden zur Google Ads Query Language.

Metadaten abrufen

GoogleAdsFieldService Abrufe zu Ressourcen in der Google Ads API, wie z. B. die verfügbaren Attribute für eine Ressource und ihrem Datentyp.

Dieser Dienst stellt Informationen bereit, die zum Erstellen einer Abfrage für GoogleAdsService Der Einfachheit halber enthält der Informationen zurückgegeben, die von GoogleAdsFieldService ist auch verfügbar in der Referenzdokumentation zu Feldern.