Google Ads-Abfragesprache

Ressourcen- oder Metadateninformationen abfragen

Mit der Google Ads Query Language können Sie die Google Ads API nach den folgenden Arten von Informationen abfragen:

• Ressourcen und die zugehörigen Attribute, Segmente und Messwerte mit GoogleAdsService Search oder SearchStream: Das Ergebnis einer GoogleAdsService-Abfrage ist eine Liste von GoogleAdsRow-Instanzen, wobei jede GoogleAdsRow eine Ressource darstellt.

  Wenn Attribute oder Messwerte angefordert werden, enthält die Zeile auch diese Felder. Wenn Segmente angefordert werden, enthält die Antwort auch eine zusätzliche Zeile für jedes Segment-Ressourcen-Tupel.

• Metadaten zu verfügbaren Feldern und Ressourcen in GoogleAdsFieldService: Dieser Dienst bietet einen Katalog abfragbarer Felder mit Informationen zu ihrer Kompatibilität und ihrem Typ.

  Das Ergebnis einer GoogleAdsFieldService-Abfrage ist eine Liste von GoogleAdsField-Instanzen, wobei jede GoogleAdsField Details zum angeforderten Feld enthält.

Ressourcenattribute abfragen

Hier ist ein Beispiel für eine einfache Abfrage für Attribute der Kampagnenressource, die zeigt, wie die Kampagnen-ID, der Name und der Status zurückgegeben werden:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Bei dieser Abfrage wird nach Kampagnen-ID sortiert. Jedes resultierende GoogleAdsRow-Objekt stellt ein campaign-Objekt dar, das mit den ausgewählten Feldern gefüllt ist, einschließlich der resource_name der Kampagne.

Informationen zu anderen Feldern, die für Kampagnenabfragen verfügbar sind, finden Sie in der Referenzdokumentation zu Campaign.

Messwerte abfragen

Neben den ausgewählten Attributen für eine bestimmte Ressource können Sie auch zugehörige Messwerte abfragen:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Mit dieser Abfrage werden nur die Kampagnen mit dem Status PAUSED gefiltert, die mehr als 1.000 Impressionen erzielt haben. Die Ergebnisse werden nach Kampagnen-ID sortiert. Jede resultierende GoogleAdsRow hätte ein metrics-Feld, das mit den ausgewählten Messwerten gefüllt ist.

Eine Liste der abfragbaren Messwerte finden Sie in der Dokumentation zu Metrics.

Segmente abfragen

Neben den ausgewählten Attributen für eine bestimmte Ressource können Sie auch nach zugehörigen Segmenten suchen:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Ähnlich wie beim Abfragen von Messwerten werden in dieser Abfrage nur die Kampagnen gefiltert, die den Status PAUSED haben und mehr als 1.000 Impressionen erzielt haben. Bei dieser Abfrage werden die Daten jedoch nach Datum segmentiert. Jedes resultierende GoogleAdsRow stellt also ein Tupel aus einer Kampagne und dem Datum Segment dar. Beim Segmentieren werden die ausgewählten Messwerte aufgeteilt und nach jedem Segment in der SELECT-Anweisung gruppiert.

Eine Liste der abfragbaren Segmente finden Sie in der Dokumentation zu Segments.

Attribute einer verknüpften Ressource abfragen

In einer Abfrage für eine bestimmte Ressource können Sie möglicherweise Joins mit anderen zugehörigen Ressourcen ausführen, sofern diese verfügbar sind. Diese verknüpften Ressourcen werden als „Ressourcen mit Quellenangabe“ bezeichnet. Sie können implizit Joins für attributierte Ressourcen erstellen, indem Sie ein Attribut in Ihrer Abfrage auswählen.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Mit dieser Abfrage werden nicht nur Kampagnenattribute ausgewählt, sondern auch zugehörige Attribute aus jeder ausgewählten Kampagne abgerufen. Jedes resultierende GoogleAdsRow steht für ein campaign-Objekt, das mit den ausgewählten Kampagnenattributen sowie dem ausgewählten Attribut für die Gebotsstrategie bidding_strategy.name gefüllt ist.

Informationen dazu, welche Ressourcen mit Attributen für Kampagnenabfragen verfügbar sind, finden Sie in der Campaign-Referenzdokumentation.

Mutieren basierend auf Abfrageergebnissen

Wenn Sie eine bestimmte Ressource abfragen, können Sie die zurückgegebenen Ergebnisse sofort als Objekte verwenden, sie ändern und an die Mutate-Methode im Dienst der Ressource zurücksenden. Beispiel für einen Workflow: 1. Führen Sie eine Abfrage für alle Kampagnen aus, die derzeit PAUSED sind und mehr als 1.000 Impressionen haben. 1. Rufen Sie das Campaign-Objekt aus dem Feld campaign jedes GoogleAdsRow in der Antwort ab. 1. Ändern Sie den Status jeder Kampagne von PAUSED in ENABLED. 1. Rufen Sie CampaignService.MutateCampaigns mit den geänderten Kampagnen auf, um sie zu aktualisieren.

Feldmetadaten

An GoogleAdsFieldService gesendete Anfragen dienen zum Abrufen von Feldmetadaten. Anhand dieser Informationen können Sie nachvollziehen, wie die Felder in einer Abfrage zusammen verwendet werden können. Da Daten über die API verfügbar sind und die erforderlichen Metadaten zum Validieren oder Erstellen einer Abfrage bereitgestellt werden, können Entwickler dies programmatisch tun. Hier ist eine typische Abfrage für Metadaten:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Sie können <INSERT_RESOURCE_OR_FIELD> in dieser Abfrage durch eine Ressource (z. B. customer oder campaign) oder ein Feld (z. B. campaign.id, metrics.impressions oder ad_group.id) ersetzen.

Eine Liste der abfragbaren Felder finden Sie in der Dokumentation zu GoogleAdsField.

Codebeispiele

In den Clientbibliotheken finden Sie Beispiele für die Verwendung der Google Ads-Abfragesprache in GoogleAdsService. Der Ordner basic operations enthält Beispiele wie GetCampaigns, GetKeywords und SearchForGoogleAdsFields.