Abfragestruktur

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

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

Klauseln verwenden Feldnamen, Ressourcennamen, Operatoren, Bedingungen und Sortierungen, um Ihnen bei der Auswahl der richtigen Daten zu helfen. Wenn sie in einer einzigen Anfrage kombiniert werden, kann eine Anfrage über die Google Ads API gestellt werden.

klauseln

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

AUSWÄHLEN

Mit der SELECT-Klausel wird eine Reihe von Feldern angegeben, die in der Anfrage abgerufen werden sollen. SELECT akzeptiert 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 einzigen 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
• Felder für zugeordnete Ressourcen
  • bidding_strategy.id
  • bidding_strategy.name
• Segmentfelder
  • segments.device
  • segments.date
• Messwerte
  • metrics.impressions
  • metrics.clicks

• Abfragen von Feldern, die nicht ausgewählt werden können. Für diese Felder wird das Metadatenattribut selectable als false gekennzeichnet.
• Attribute von wiederholten Feldern auswählen Für diese Felder wird das Metadatenattribut is_repeated als true gekennzeichnet.
• Sie wählen Felder aus, die für die angegebene Ressource in der FROM-Klausel nicht verfügbar sind. Attribute einiger Ressourcen können nicht zusammen ausgewählt werden. Außerdem ist für die Ressource in der FROM-Klausel nur eine Teilmenge aller Messwerte und Segmente verfügbar.
• Sie wählen Segmente oder Messwerte aus, die nicht miteinander kompatibel sind. Weitere Informationen finden Sie im Abschnitt zur Segmentierung.

Informationen zu den vorherigen Bedingungen finden Sie in unserer Referenzdokumentation oder unter 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 jeweilige Abfrage verwendet werden können. In der FROM-Klausel kann nur eine Ressource angegeben werden. Die FROM-Klausel ist erforderlich in einer Anfrage an die Methoden GoogleAdsService Search oder SearchStream. Die FROM-Klausel sollte jedoch nicht angegeben werden, wenn GoogleAdsFieldService verwendet wird.

Für eine bestimmte Abfrage kann in der FROM-Klausel nur eine Ressource vorhanden sein. Felder aus zugeordneten Ressourcen sind aber möglicherweise auch verfügbar. 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 aus 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, obwohl es in der Anfrage 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. campaign.resource_name wird beispielsweise in die Antwort auf die folgende Anfrage aufgenommen:

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, können Sie eine oder mehrere Bedingungen angeben, die durch AND getrennt werden. 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 in der SELECT-Klausel enthalten sein. Ausnahmen sind die folgenden Datumssegmente, die als Kern-Datumssegmente bezeichnet werden:

• 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 Kerndatumsegment handelt, muss ein endlicher Zeitraum mit Kerndatumsegmenten in der WHERE-Anweisung angegeben werden:

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 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.

Beim Filtern ist es wichtig, die Groß- und 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 anhand eines Feldnamens 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.

In 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 mehrere Felder in der ORDER BY-Klausel mit einer durch Kommas getrennten Liste angeben. Die Sortierung erfolgt in derselben Reihenfolge wie in der Abfrage angegeben. Wenn Sie in dieser Abfrage beispielsweise Anzeigengruppendaten auswählen, werden die Ergebnisse in aufsteigender Reihenfolge nach Kampagnennamen, 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 an einer Zusammenfassung interessiert sind.

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, damit Entwurfsobjekte zurückgegeben werden können. 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 zu verhindern, dass der Ressourcenname jedes Ressourcentyps in der Antwort zurückgegeben wird, sofern er nicht explizit in der SELECT-Klausel angefordert wird. Die Standardeinstellung ist false.

SELECT
  campaign.name,
  customer.id
FROM campaign

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

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

Zusätzliche Sprachregeln

Zusätzlich zu den Beispielen für jede Anweisung bietet die Google Ads-Abfragesprache die folgenden Verhaltensweisen, die genutzt werden können:

• Es ist nicht erforderlich, dass sich das Hauptressourcenfeld in der SELECT-Klausel einer Abfrage befindet. Sie können beispielsweise nur ein oder mehrere Hauptressourcenfelder zum Filtern von Daten 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. Es sind keine anderen Felder aus der Ressource in der Abfrage 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'