Objekte abrufen

Der GoogleAdsService ist der einheitliche Dienst zum Abrufen von Objekten und für Berichte der Google Ads API. Der Dienst bietet folgende Methoden:

• Bestimmte Attribute von Objekten abrufen
• Leistungsmesswerte für Objekte basierend auf einem Datumsbereich abrufen
• Objekte anhand ihrer Attribute sortieren
• Bedingungen verwenden, um anzugeben, welche Objekte in der Antwort zurückgegeben werden sollen
• Die Anzahl der zurückgegebenen Objekte begrenzen

Die GoogleAdsService kann Ergebnisse auf zwei Arten zurückgeben:

• GoogleAdsService.SearchStream gibt alle Zeilen in einer einzelnen Streaming-Antwort zurück. Das ist effizienter für große Ergebnismengen (mehr als 10.000 Zeilen). Diese Methode ist möglicherweise besser geeignet, wenn Ihre Batchanwendung so viele Daten wie möglich so schnell wie möglich herunterladen soll.
• GoogleAdsService.Search unterteilt große Antworten in überschaubare Ergebnisseiten. Diese Methode ist möglicherweise besser geeignet, wenn Ihre interaktive Anwendung jeweils eine Seite mit Ergebnissen anzeigt.

Weitere Informationen zu Paging und Streaming

Anfrage stellen

Für die Suchmethode ist eine SearchGoogleAdsRequest erforderlich, die aus den folgenden Attributen besteht:

• Eine customer_id
• Eine Google Ads Query Language-query, die angibt, welche Ressource abgefragt werden soll, welche Attribute, Segmente und Messwerte abgerufen werden sollen und welche Bedingungen verwendet werden sollen, um die zurückgegebenen Objekte einzuschränken
• (GoogleAdsService.Search nur) Ein optionales page_token, um beim Paging den nächsten Batch von Ergebnissen abzurufen.

Weitere Informationen zur Google Ads Query Language finden Sie im Google Ads Query Language Leitfaden.

Antwort verarbeiten

Der GoogleAdsService gibt eine Liste von GoogleAdsRow-Objekten zurück.

Jede GoogleAdsRow stellt ein Objekt dar, das von einer Abfrage zurückgegeben wurde, und besteht aus einer Reihe von Attributen, die basierend auf den in der SELECT-Klausel angeforderten Feldern gefüllt werden. Attribute, die nicht in der SELECT-Klausel enthalten sind, werden in den GoogleAdsRow-Objekten in der Antwort nicht gefüllt.

Obwohl ein ad_group_criterion beispielsweise ein status-Attribut hat, wird das status-Feld des Attributs ad_group_criterion der Zeile in einer Antwort auf eine Abfrage, bei der die SELECT-Klausel ad_group_criterion.status nicht enthält, nicht gefüllt. Ebenso wird das Attribut campaign der Zeile nicht gefüllt, wenn die SELECT-Klausel keine Felder aus der Ressource campaign enthält.

Jede GoogleAdsRow kann andere Attribute und Messwerte als eine andere Zeile in derselben Ergebnismenge haben. Die Zeilen sollten daher als Objekte und nicht als feste Zeilen einer Tabelle betrachtet werden.

Unbekannte Enum-Typen

Ressourcen, die mit dem Typ UNKNOWN zurückgegeben werden, werden in dieser API-Version nicht vollständig unterstützt. Diese Ressourcen wurden möglicherweise über andere Schnittstellen wie die Google Ads-Benutzeroberfläche erstellt. Sie können Messwerte auswählen, wenn eine Ressource den Typ UNKNOWN hat, aber die Ressource nicht über die API ändern. Ein Beispiel dafür wäre eine neue Kampagne oder Anzeige, die auf der Benutzeroberfläche eingeführt wird, aber in der API-Version, die Sie abfragen, nicht unterstützt wird.

Beachten Sie Folgendes:

• Eine Ressource mit dem Typ UNKNOWN kann später unterstützt werden oder auf unbestimmte Zeit UNKNOWN bleiben.
• Neue Objekte mit dem Typ UNKNOWN können jederzeit angezeigt werden. Diese Objekte sind abwärtskompatibel, da der Enum-Wert bereits verfügbar ist. Ressourcen werden mit dieser Änderung eingeführt, sobald sie verfügbar sind, damit Sie einen genauen Überblick über Ihr Konto haben. Die Ressource UNKNOWN kann aufgrund neuer Aktivitäten in Ihrem Konto über andere Schnittstellen oder wenn eine Ressource nicht mehr unterstützt wird, angezeigt werden.
• An UNKNOWN-Ressourcen können detaillierte Messwerte angehängt sein, die abgefragt werden können.
• UNKNOWN-Ressourcen sind in der Regel auf der Google Ads-Benutzeroberfläche vollständig sichtbar.
• UNKNOWN-Ressourcen können in der Regel nicht geändert werden.

Segmentierung

Die Antwort enthält eine GoogleAdsRow für jede Kombination aus:

• Instanz der in der FROM-Klausel angegebenen Hauptressource
• Wert jedes ausgewählten segment-Felds

Die Antwort auf eine Abfrage, die FROM campaign auswählt und segments.ad_network_type und segments.date in der SELECT-Klausel enthält, enthält beispielsweise eine Zeile für jede Kombination aus:

• campaign
• segments.ad_network_type
• segments.date

Die Ergebnisse werden implizit nach jeder Instanz der Hauptressource segmentiert, nicht nach den Werten der ausgewählten einzelnen Felder. Beispiel:

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

führt zu einer Zeile pro campaign und nicht zu einer Zeile pro eindeutigem Wert des campaign.status Felds.