Die GoogleAdsService
ist der einheitliche Dienst zum Abrufen von Objekten und Erstellen von Berichten in der Google Ads API. Der Dienst hat Methoden, die:
- Bestimmte Attribute von Objekten abrufen.
- Leistungsmesswerte für Objekte basierend auf einem Zeitraum abrufen.
- Objekte anhand ihrer Attribute sortieren
- Mit Bedingungen können Sie angeben, welche Objekte in der Antwort zurückgegeben werden sollen.
- Anzahl der zurückgegebenen Objekte begrenzen.
Die GoogleAdsService
kann Ergebnisse auf zwei Arten zurückgeben:
GoogleAdsService.SearchStream
gibt alle Zeilen in einer einzelnen Streamingantwort zurück,was für große (mehr als 10.000 Zeilen) Ergebnismengen effizienter ist. Das kann sinnvoll sein, wenn Ihre Batchanwendung so viele Daten wie möglich so schnell wie möglich herunterladen soll.- Mit
GoogleAdsService.Search
werden lange Antworten in überschaubare Ergebnisseiten unterteilt. Das ist möglicherweise besser geeignet, wenn in Ihrer interaktiven Anwendung jeweils eine Seite mit Ergebnissen angezeigt wird.
Weitere Informationen zum Paging und Streaming
Anfrage stellen
Für die Suchmethode ist ein SearchGoogleAdsRequest
erforderlich, das aus den folgenden Attributen besteht:
- Ein
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 - (Nur
GoogleAdsService.Search
) Ein optionalespage_token
zum Abrufen des nächsten Batches von Ergebnissen bei Verwendung von Paging.
Weitere Informationen zur Google Ads Query Language finden Sie im Leitfaden zur Google Ads Query Language.
Antwort verarbeiten
Die GoogleAdsService
gibt eine Liste von GoogleAdsRow
-Objekten zurück.
Jedes GoogleAdsRow
steht für ein Objekt, das von einer Abfrage zurückgegeben wird, und besteht aus einer Reihe von Attributen, die auf Grundlage der in der SELECT
-Klausel angeforderten Feldern ausgefüllt werden. Attribute, die nicht in der SELECT
-Klausel enthalten sind, werden in den GoogleAdsRow
-Objekten in der Antwort nicht ausgefüllt.
Obwohl ein ad_group_criterion
beispielsweise ein status
-Attribut hat, wird das status
-Feld des ad_group_criterion
-Attributs der Zeile in einer Antwort auf eine Abfrage, in der die SELECT
-Klausel nicht ad_group_criterion.status
enthält, nicht ausgefüllt. Ebenso wird das Attribut campaign
der Zeile nicht ausgefüllt, wenn die SELECT
-Klausel keine Felder aus der campaign
-Ressource enthält.
Jedes GoogleAdsRow
kann unterschiedliche Attribute und Messwerte als eine andere Zeile im selben Ergebnis haben. Die Zeilen sollten also als Objekte und nicht als feste Zeilen einer Tabelle betrachtet werden.
UNKNOWN-Enum-Typen
Ressourcen, die mit dem Typ UNKNOWN
zurückgegeben werden, werden in dieser API-Version nicht vollständig unterstützt. Diese Ressourcen können über andere Oberflächen wie die Google Ads-Benutzeroberfläche erstellt worden sein. Sie können Messwerte auswählen, wenn eine Ressource den Typ UNKNOWN
hat, aber die Ressource nicht über die API ändern. Ein Beispiel hierfür wäre eine neue Kampagne oder Anzeige, die in der Benutzeroberfläche eingeführt wird, aber in der API-Version, die Sie abfragen, nicht unterstützt wird.
Folgendes ist zu beachten:
- Eine Ressource mit dem Typ
UNKNOWN
kann später unterstützt werden oder auf unbestimmte ZeitUNKNOWN
bleiben. - Neue Objekte vom Typ
UNKNOWN
können jederzeit angezeigt werden. Diese Objekte sind abwärtskompatibel, da der Enum-Wert bereits verfügbar ist. Mit dieser Änderung werden Ressourcen eingeführt, damit Sie einen genauen Überblick über Ihr Konto haben. DieUNKNOWN
-Ressource kann aufgrund neuer Aktivitäten in Ihrem Konto über andere Schnittstellen oder wenn eine Ressource nicht mehr unterstützt wird, angezeigt werden. UNKNOWN
-Ressourcen können detaillierte Messwerte zugeordnet sein, die abgefragt werden können.UNKNOWN
-Ressourcen sind in der Regel vollständig in der Google Ads-Benutzeroberfläche sichtbar.UNKNOWN
-Ressourcen können in der Regel nicht geändert werden.
Segmentierung
Die Antwort enthält ein GoogleAdsRow
für jede Kombination der folgenden Elemente:
- Instanz der Hauptressource, die in der
FROM
-Klausel angegeben ist - Wert der einzelnen ausgewählten
segment
-Felder
Die Antwort auf eine Abfrage, in der FROM campaign
ausgewählt wird und die segments.ad_network_type
und segments.date
in der SELECT
-Klausel enthält, würde beispielsweise eine Zeile für jede Kombination aus Folgendem enthalten:
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 Kampagne und nicht zu einer Zeile pro eindeutigem Wert des Felds campaign.status
.