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.
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 mitfalse
gekennzeichnet. - Attribute wiederkehrender Felder auswählen Das Metadatenattribut
isRepeated
dieser Felder ist mittrue
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 derFROM
-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
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.
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
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
.
übersprungen – Beispiele für unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.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.cost_micros 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'