Abfragestruktur

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

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

In den Klauseln werden Feldnamen, Ressourcennamen, Operatoren, Bedingungen und Sortierungen verwendet, um die richtigen Daten auszuwählen. Wenn sie zu einer einzelnen Abfrage kombiniert werden, kann eine Anfrage mit der Google Ads API gestellt werden.

Klauseln

ondemand_video Video: GAQL-Feldkompatibilität

SELECT

Die Klausel SELECT 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 Anweisung SELECT 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

• Ressourcenfelder

  • campaign.id
  • campaign.name

• Ressourcenfelder

  • 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 wiederholter Felder. Für diese Felder ist das Metadatenattribut isRepeated 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 im Abschnitt zur 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 wird. 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 einzelne Ressource angegeben werden. Die Klausel FROM ist erforderlich in einer Abfrage an die GoogleAdsService Search oder SearchStream Methoden. 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 Attributed Resources 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 Attributed Resources. 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 andere Ressourcen, wenn mindestens ein Feld ausgewählt ist. Beispiel: campaign.resource_name ist 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. Bei Verwendung der Klausel WHERE können eine oder mehrere Bedingungen mit AND getrennt angegeben werden. Jede Bedingung muss dem Muster field_name Operator value folgen. 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 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

In der folgenden Abfrage ist segments.date ausgewählt. Da dieses Segment ein Kern-Datumssegment ist, muss in der Klausel WHERE ein endlicher Zeitraum angegeben werden, der aus Kern-Datumssegmenten 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 zur Datumsfilterung finden Sie unter Zeiträume.

Beim Filtern ist die Groß-/Kleinschreibung des Operators wichtig. Weitere Informationen finden Sie unter Berücksichtigung der 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 sollen. So können Sie die Daten anhand eines Feldnamens in auf- 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 Anweisung 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 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 Klausel LIMIT können Sie die Anzahl der zurückzugebenden Ergebnisse angeben. Das ist nützlich, wenn Sie nur eine Zusammenfassung benötigen.

Mit LIMIT kann beispielsweise die Gesamtzahl der Ergebnisse für die folgende Abfrage begrenzt 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, damit Entwurfsobjekte zurückgegeben werden können. Die Standardeinstellung 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 zu verhindern, dass der Ressourcename jedes Ressourcentyps in der Antwort zurückgegeben wird, es sei denn, er wurde explizit in der Klausel SELECT angefordert. 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

Neben den Beispielen für die einzelnen Anweisungen bietet die Google Ads-Abfragesprache die folgenden Verhaltensweisen, die genutzt werden können:

• Das Feld der Hauptressource muss nicht in der Klausel SELECT für eine Abfrage enthalten sein. Beispielsweise können Sie nur ein oder mehrere Felder der Hauptressource verwenden, um Daten zu filtern:

  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 begleitende 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'