Abfragestruktur

Abfragen für Ressourcen-, Segment- und Messwertfelder können an die Methoden GoogleAdsService Search oder SearchStream gesendet werden. Um eine Abfrage in Google Ads Query Language zu erstellen, müssen Sie sie gemäß der Sprachgrammatik erstellen. Eine Abfrage besteht aus mehreren Klauseln:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

In Klauseln werden Feldnamen, Ressourcennamen, Operatoren, Bedingungen und Reihenfolgen verwendet, damit Sie die richtigen Daten auswählen können. Nachdem die Daten zu einer Abfrage zusammengefasst wurden, kann über die Google Ads API eine Anfrage gestellt werden.

Wichtiger Hinweis :Die GoogleAdsFieldService enthält einen Katalog für Google Ads Query Language-Clients mit Metadaten zu allen Ressourcenfeldern, Segmentfeldern und Messwerten sowie zu deren Beziehungen zueinander und zur Verfügbarkeit in den einzelnen Klauseln, wie unten definiert. Weitere Informationen finden Sie in der Dokumentation zu GoogleAdsField.

klauseln

Video: Kompatibilität von GAQL-Feldern

SELECT

Die SELECT-Klausel gibt eine Reihe von Feldern an, die in der Anfrage abgerufen werden sollen. SELECT verwendet eine durch Kommas getrennte Liste von Ressourcenfeldern, Segmentfeldern und Messwerten, die die Werte in der Antwort zurückgibt. Die SELECT-Klausel ist in einer Abfrage erforderlich.

Die folgende Beispielabfrage zeigt ein Beispiel für die Auswahl von Attributen für eine bestimmte Ressource:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Sie können verschiedene Feldtypen in einer einzelnen Anfrage anfordern. Beispiel:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

• Ressourcenfelder

  • campaign.id
  • campaign.name

• Ressourcenfelder

  • bidding_strategy.id
  • bidding_strategy.name

• Segmentfelder

  • segments.device
  • segments.date

• Messwerte

  • metrics.impressions
  • metrics.clicks

Einige Felder sind in der SELECT-Klausel möglicherweise aufgrund der folgenden Einschränkungen nicht zulässig:

• Nicht auswählbare Felder abfragen Das Metadatenattribut Selectable dieser Felder ist mit false gekennzeichnet.
• Attribute wiederkehrender Felder auswählen Das Metadatenattribut isRepeated dieser Felder ist mit true gekennzeichnet.
• Felder auswählen, die für die angegebene Ressource in der FROM-Klausel nicht verfügbar sind Die Attribute einiger Ressourcen können nicht zusammen ausgewählt werden. Außerdem ist nur ein Teil aller Messwerte und Segmente für die Ressource in der FROM-Klausel verfügbar.
• Auswahl von Segmenten oder Messwerten, die nicht miteinander kompatibel sind Weitere Informationen hierzu finden Sie im Abschnitt zur Segmentierung.

Informationen zu den oben genannten Bedingungen finden Sie in unserer Referenzdokumentation oder auf GoogleAdsFieldService.

VOM

Die FROM-Klausel gibt die Hauptressource an, die zurückgegeben wird. Die Ressource in der FROM-Klausel definiert, welche Felder in allen anderen Klauseln für die angegebene Abfrage verwendet werden können. In der FROM-Klausel kann nur eine Ressource angegeben werden. Die FROM-Klausel ist in einer Abfrage an die GoogleAdsService-Methode Search oder SearchStream erforderlich. Sie sollte jedoch nicht angegeben werden, wenn die GoogleAdsFieldService verwendet wird.

Während in der FROM-Klausel für eine bestimmte Abfrage nur eine Ressource vorhanden sein kann, sind möglicherweise auch Felder aus zugeordneten Ressourcen verfügbar. Diese Ressourcen werden implizit mit der Ressource in der FROM-Klausel verknüpft. Sie müssen ihre Attribute also nur der SELECT-Klausel hinzufügen, um ihre Werte zurückzugeben. Nicht alle Ressourcen haben zugeordnete Ressourcen. Im folgenden Beispiel können Sie sowohl die Anzeigengruppen-ID als auch die Kampagnen-ID von Anzeigengruppen anfordern:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Das Feld resource_name der Hauptressource wird immer zurückgegeben. Im folgenden Beispiel wird ad_group.resource_name in die Antwort aufgenommen, auch wenn sie in der Abfrage nicht explizit ausgewählt wurde:

SELECT ad_group.id
FROM ad_group

Dasselbe gilt für andere Ressourcen, wenn mindestens ein Feld ausgewählt ist. Beispiel: campaign.resource_name wird in die Antwort auf die folgende Abfrage aufgenommen:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Wichtiger Hinweis :Wenn die Ressource in der FROM-Klausel eine andere Ressource als segment auflistet, dient die Auswahl aller Attribute dieser Ressource als Segment.

DABEI GILT:

Die WHERE-Klausel gibt Bedingungen an, die beim Filtern von Daten für die Anfrage angewendet werden sollen. Bei Verwendung der WHERE-Klausel können eine oder mehrere Bedingungen mit AND zur Trennung angegeben werden. Jede Bedingung sollte dem Muster field_name Operator value folgen. Die WHERE-Klausel ist in einer Abfrage optional.

Im folgenden Beispiel wird WHERE verwendet, um Messwerte für einen bestimmten Zeitraum zurückzugeben:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Sie können mehrere Bedingungen kombinieren, um die Daten zu filtern. In diesem Beispiel wird die Anzahl der Klicks für alle Kampagnen angefordert, die in den letzten 30 Tagen auf Mobilgeräten Impressionen erzielt haben.

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

Segmente in der WHERE-Klausel müssen in der SELECT-Klausel enthalten sein. Die folgenden Datumssegmente, die als Kerndatensegmente bezeichnet werden, sind Ausnahmen:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Beachten Sie in der folgenden Abfrage, dass segments.date ausgewählt ist. Da es sich bei diesem Segment um ein Kerndatumssegment handelt, muss in der WHERE-Klausel ein endlicher Zeitraum angegeben werden, der aus Hauptdatumssegmenten besteht.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Alle Segmente, die die oben genannte Bedingung erfüllen, sind: „Segmente.date“, „Segmente.week“, „segments.month“, „Segmente.quarter“ und „Segmente.year“. Wenn eines dieser Segmente ausgewählt ist, muss mindestens eines davon in der WHERE-Klausel verwendet werden.

Wichtiger Hinweis: Das Trennzeichen AND kann nur zwischen Operatorbedingungen (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") und nicht innerhalb einer einzelnen Operatorbedingung (WHERE segments.device != "DESKTOP" AND "MOBILE") verwendet werden.

Beim Filtern ist es wichtig, die Groß-/Kleinschreibung des Operators zu beachten. Weitere Informationen finden Sie unter Groß-/Kleinschreibung.

Eine vollständige Liste der Operatoren finden Sie in der Sprachgrammatik.

ORDER BY

Die ORDER BY-Klausel gibt die Reihenfolge an, in der die Ergebnisse zurückgegeben werden sollen. So können Sie die Daten basierend auf einem Feldnamen in aufsteigender oder absteigender Reihenfolge anordnen. Jede Sortierung wird als field_name gefolgt von ASC oder DESC angegeben. Wenn weder ASC noch DESC angegeben ist, wird standardmäßig ASC verwendet. Die ORDER BY-Klausel ist in einer Abfrage optional.

Mit der folgenden Abfrage werden die zurückgegebenen Kampagnen nach der Anzahl der Klicks in absteigender Reihenfolge sortiert:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Sie können mithilfe einer durch Kommas getrennten Liste mehrere Felder in der ORDER BY-Klausel angeben. Die Sortierung erfolgt in der gleichen Reihenfolge, wie in der Abfrage angegeben. In dieser Abfrage zum Auswählen von Anzeigengruppendaten werden die Ergebnisse beispielsweise in aufsteigender Reihenfolge nach Kampagnenname, dann in absteigender Reihenfolge nach Anzahl der Impressionen und dann in absteigender Reihenfolge nach Anzahl der Klicks sortiert:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

Mit der LIMIT-Klausel können Sie die Anzahl der Ergebnisse angeben, die zurückgegeben werden sollen. Dies ist nützlich, wenn Sie nur an einer Zusammenfassung interessiert sind.

Beispielsweise kann LIMIT verwendet werden, um die Gesamtzahl der Ergebnisse für die folgende Abfrage einzuschränken:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Wichtiger Hinweis: Mit LIMIT können Sie die Ergebnisse kürzen. Verwenden Sie das Feld page_size von GoogleAdsService.Search, um lange Ergebnislisten zu verarbeiten.

PARAMETER

Mit der PARAMETERS-Klausel können Sie Metaparameter für die Anfrage angeben. Diese Parameter können sich darauf auswirken, welche Arten von Zeilen zurückgegeben werden.

Derzeit werden die folgenden Metaparameter unterstützt:

include_drafts

Legen Sie include_drafts auf true fest, damit Entwurfsentitäten zurückgegeben werden können. Die Standardeinstellung ist false.

Die folgende Abfrage ruft beispielsweise Kampagnenentwürfe zusammen mit regulären Kampagnen ab:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Setzen Sie omit_unselected_resource_names auf true, um zu verhindern, dass der Ressourcenname jedes Ressourcentyps in der Antwort zurückgegeben wird, es sei denn, dies wird explizit in der SELECT-Klausel angefordert. Die Standardeinstellung ist false.

Hinweis :Wenn Sie eines der zurückgegebenen Objekte für Aktualisierungs- oder Entfernungsvorgänge verwenden möchten, sollten Sie diese Option auf false festlegen, da Ressourcen ohne Ressourcennamen nicht in mutate-Vorgängen verwendet werden können. Wenn Sie diese Option auf true setzen, müssen Sie die Ressourcennamen der primären Ressource und aller Attributressourcen, die Sie mit der Abfrage abrufen, explizit anfordern.

übersprungen – Beispiele für unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names ist standardmäßig auf false eingestellt, sodass alle Felder von „resource_name“ zurückgegeben werden.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: Keine. omit_unselected_resource_names wird als true angegeben und campaign.resource_name und customer.resource_name sind nicht Teil der SELECT-Klausel.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: campaign.resource_name omit_unselected_resource_names wird als true angegeben und campaign.resource_name wird als Teil der SELECT-Klausel angefordert.

Regeln für zusätzliche Sprachen

Zusätzlich zu den Beispielen für jede Klausel bietet die Google Ads Query Language die folgenden Verhaltensweisen, die verwendet werden können:

• Das Hauptressourcenfeld muss nicht in der SELECT-Klausel einer Abfrage enthalten sein. So kann es beispielsweise sinnvoll sein, nur ein oder mehrere Hauptressourcenfelder zum Filtern von Daten zu verwenden:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• Messwerte können ausschließlich für eine bestimmte Ressource ausgewählt werden. Für die Abfrage sind keine anderen Felder aus der Ressource erforderlich:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.costMicros
  FROM campaign
  

• Segmentierungsfelder können ohne zugehörige Ressourcenfelder oder Messwerte ausgewählt werden:

  SELECT segments.device FROM campaign
  

• Das Feld resource_name (z. B. campaign.resource_name) kann zum Filtern oder Sortieren von Daten verwendet werden:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'