Abfragestruktur

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

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

In Klauseln werden Feldnamen, Ressourcennamen, Operatoren, Bedingungen und Sortierungen verwendet, damit Sie die richtigen Daten auswählen können. Wenn Sie sie zu einer einzelnen Abfrage kombinieren, können Sie die Anfrage an die Google Ads API senden.

Klauseln

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

SELECT

Mit der Klausel SELECT wird eine Reihe von Feldern angegeben, 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 Klausel SELECT ist in einer Abfrage erforderlich.

Die folgende Beispielabfrage zeigt, wie Sie Attribute für eine bestimmte Ressource auswählen:

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

• Felder der Hauptressource
  • campaign.id
  • campaign.name
• Felder der zugehörigen Ressource
  • 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 ist das Metadatenattribut selectable auf false gesetzt.
• Auswählen von Attributen wiederkehrender Felder. Für diese Felder ist das Metadatenattribut is_repeated auf true gesetzt.
• Auswählen von Feldern, die für die angegebene Ressource in der Klausel FROM nicht verfügbar sind. Attribute einiger Ressourcen können nicht zusammen ausgewählt werden. Außerdem ist für die Ressource in der Klausel FROM nur eine Teilmenge aller Messwerte und Segmente verfügbar.
• Auswählen 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.

FROM

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

In der Klausel FROM kann für eine bestimmte Abfrage nur eine Ressource vorhanden sein. Felder aus zugehörigen Ressourcen sind jedoch möglicherweise auch verfügbar. Diese Ressourcen werden implizit mit der Ressource in der Klausel FROM verknüpft. Sie müssen also nur ihre Attribute zur Klausel SELECT hinzufügen, um ihre Werte zurückzugeben. Nicht alle Ressourcen haben zugehörige 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 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 zugehörige Ressourcen, wenn mindestens ein Feld ausgewählt ist. So ist beispielsweise campaign.resource_name in der Antwort für die folgende Abfrage enthalten:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

Die Klausel WHERE gibt Bedingungen an, die beim Filtern von Daten für die Anfrage angewendet werden sollen. Wenn Sie die Klausel WHERE 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 Klausel WHERE ist in einer Abfrage optional.

Im folgenden Beispiel wird WHERE verwendet, um Messwerte aus einem 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 von den folgenden Datumssegmenten, die als Hauptdatumssegmente bezeichnet werden:

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

In der folgenden Abfrage ist segments.date ausgewählt. Da dieses Segment ein Hauptdatumssegment ist, müssen Sie in der WHERE Klausel einen endlichen Zeitraum angeben, 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 segments.date, segments.week, segments.month, segments.quarter und segments.year. Wenn eines dieser Segmente ausgewählt ist, muss mindestens eines davon in der Klausel WHERE 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 Klausel ORDER BY gibt die Reihenfolge an, in der die Ergebnisse zurückgegeben werden. 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 Klausel ORDER BY ist in einer Abfrage optional.

Die folgende Abfrage sortiert die zurückgegebenen Kampagnen nach der Anzahl der Klicks, von der höchsten zur niedrigsten:

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

Sie können in der Klausel ORDER BY mehrere Felder in einer durch Kommas getrennten Liste angeben. Die Sortierung erfolgt in derselben Reihenfolge wie in der Abfrage angegeben. In dieser Abfrage, in der Anzeigengruppendaten ausgewählt werden, werden die Ergebnisse beispielsweise in aufsteigender Reihenfolge nach Kampagnennamen, dann in absteigender Reihenfolge nach der Anzahl der Impressionen und dann in absteigender Reihenfolge nach der 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 Klausel LIMIT können Sie die Anzahl der zurückzugebenden Ergebnisse angeben. Das ist nützlich, wenn Sie nur eine Teilmenge 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 Klausel PARAMETERS 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

Setzen Sie include_drafts auf true, um Entwurfsobjekte zurückzugeben. Der Standardwert ist false.

Die folgende Abfrage ruft beispielsweise Entwurfskampagnen 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 den Ressourcennamen jedes Ressourcentyps in der Antwort auszulassen, es sei denn, er wurde explizit in der Klausel SELECT angefordert. Der Standardwert 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

Neben den Beispielen für jede Klausel unterstützt Google Ads Query Language die folgenden Verhaltensweisen:

• Das Feld der Hauptressource ist in der Klausel SELECT für eine Abfrage nicht erforderlich. Sie können beispielsweise ein oder mehrere Felder der Hauptressource 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 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 (campaign.resource_name, z. B.) kann verwendet werden, um Daten zu filtern oder zu sortieren:

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