Abfragestruktur

Abfragen für Ressourcen-, Segment- und Messwertfelder können an die GoogleAdsService-Methode Search oder SearchStream gesendet werden. Wenn Sie eine Abfrage in der Google Ads Query Language erstellen möchten, verwenden Sie die Grammatik der Sprache. Eine allgemeine Übersicht über die Google Ads Query Language finden Sie in der Übersicht über die Google Ads Query Language. Eine Abfrage besteht aus mehreren Klauseln:

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

In Klauseln werden Feldnamen, Ressourcennamen, Operatoren, Bedingungen und Sortierungen verwendet, um die richtigen Daten auszuwählen. Wenn Sie die Anfrage in einer einzigen Abfrage zusammenfassen, können Sie sie an die Google Ads API senden.

klauseln

In den folgenden Abschnitten werden Zweck und Syntax der einzelnen Google Ads Query Language-Klauseln beschrieben.

AUSWÄHLEN

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 und gibt die Werte in der Antwort zurück. Die SELECT-Klausel ist in einer Abfrage erforderlich.

Die folgende Beispielabfrage zeigt, wie Attribute für eine bestimmte Ressource ausgewählt werden:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Sie können in einer einzelnen Anfrage verschiedene Feldtypen anfordern, z. B.:

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
  • Hauptressourcenfelder
    • campaign.id
    • campaign.name
  • Zugewiesene Ressourcenfelder
    • bidding_strategy.id
    • bidding_strategy.name
  • Segmentfelder
    • segments.device
    • segments.date
  • Messwerte
    • metrics.impressions
    • metrics.clicks
  • Abfrage von Feldern, die nicht auswählbar sind. Bei diesen Feldern ist das Metadatenattribut selectable als false gekennzeichnet.
  • Attribute von wiederkehrenden Feldern auswählen. Bei diesen Feldern ist das Metadatenattribut is_repeated als true gekennzeichnet.
  • Auswählen von Feldern, die für die angegebene Ressource in der FROM-Klausel nicht verfügbar sind. Attribute einiger Ressourcen können nicht zusammen ausgewählt werden und für die Ressource in der FROM-Klausel ist nur eine Teilmenge aller Messwerte und Segmente verfügbar.
  • Auswahl von Segmenten oder Messwerten, die nicht miteinander kompatibel sind. Weitere Informationen finden Sie unter Segmentierung.

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

VOM

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

In der FROM-Klausel einer Abfrage kann zwar nur eine Ressource vorhanden sein, aber es können auch Felder aus zugeordneten Ressourcen verfügbar sein. Diese Ressourcen werden implizit mit der Ressource in der FROM-Klausel verknüpft. Sie müssen also nur ihre Attribute 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 ist ad_group.resource_name in der Antwort enthalten, obwohl es in der Abfrage nicht explizit ausgewählt wurde:

SELECT ad_group.id
FROM ad_group

Dasselbe gilt für zugeordnete Ressourcen, wenn mindestens ein Feld ausgewählt ist. campaign.resource_name ist beispielsweise in der Antwort für die folgende Abfrage enthalten:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Die WHERE-Klausel gibt Bedingungen an, die beim Filtern von Daten für die Anfrage angewendet werden sollen. Wenn Sie die WHERE-Klausel verwenden, geben Sie eine oder mehrere Bedingungen an, die durch AND getrennt sind. Bedingungen folgen in der Regel dem Muster field_name Operator value (oder verwenden BETWEEN value AND value, IS NULL oder IS NOT NULL). 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 mit Impressionen auf Mobilgeräten in den letzten 30 Tagen angefordert:

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 auch in der SELECT-Klausel enthalten sein, mit Ausnahme der folgenden Datumssegmente, die als Haupt-Datumssegmente bezeichnet werden:

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

In der folgenden Abfrage wird segments.date ausgewählt. Da es sich bei diesem Segment um ein Haupt-Datumssegment handelt, müssen Sie in der WHERE-Klausel einen begrenzten Zeitraum angeben, der aus Haupt-Datumssegmenten besteht:

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

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

Weitere Informationen zum Filtern nach Datum finden Sie unter Zeiträume.

Beachten Sie beim Filtern die Groß-/Kleinschreibung des Operators. 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 Ergebnisse zurückgegeben werden. So können Sie die Daten nach einem Feldnamen auf- oder absteigend sortieren. 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 sortiert, von der höchsten zur niedrigsten:

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

Sie können in der ORDER BY-Klausel mehrere Felder in einer durch Kommas getrennten Liste angeben. Die Sortierung erfolgt in der Reihenfolge, die in der Abfrage angegeben ist. In dieser Abfrage, in der Anzeigengruppendaten ausgewählt werden, 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 zurückzugebenden Ergebnisse angeben. Das ist nützlich, wenn Sie nur einen Teil der Ergebnisse benötigen.

Mit LIMIT kann beispielsweise die Gesamtzahl der Ergebnisse für die folgende Abfrage eingeschränkt werden:

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.

Die folgenden Metaparameter werden unterstützt:

include_drafts

Legen Sie include_drafts auf true fest, um Entitätsentwürfe zurückzugeben. Die Standardeinstellung ist false.

Mit der folgenden Abfrage werden beispielsweise Kampagnenentwürfe zusammen mit regulären Kampagnen abgerufen:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

Setzen Sie omit_unselected_resource_names auf true, um den Ressourcennamen jedes Ressourcentyps in der Antwort wegzulassen, sofern er nicht explizit in der SELECT-Klausel angefordert wird. Die Standardeinstellung ist false.

Abfrage Zurückgegebene Ressourcen 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

omit_unselected_resource_names ist standardmäßig auf false festgelegt, sodass alle resource_name-Felder zurückgegeben werden.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

–

omit_unselected_resource_names ist als true angegeben und weder campaign.resource_name noch customer.resource_name ist Teil der SELECT-Klausel.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

omit_unselected_resource_names wird als true angegeben und campaign.resource_name wird als Teil der SELECT-Klausel angefordert.

Zusätzliche Sprachregeln

Zusätzlich zu den Beispielen für die einzelnen Klauseln unterstützt die Google Ads-Abfragesprache die folgenden Verhaltensweisen:

  • Das Hauptressourcenfeld ist in der SELECT-Klausel für eine Abfrage nicht erforderlich. Sie können beispielsweise ein oder mehrere Hauptressourcenfelder verwenden, um Daten zu filtern, ohne sie auszuwählen:

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

  • Messwerte können ausschließlich für eine bestimmte Ressource ausgewählt werden. In der Abfrage sind keine anderen Felder 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'
Zurück
Abfragegrammatik
Weiter
Zeiträume