Abfragestruktur

Abfragen 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 Abfrage besteht aus einer Reihe von 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 einzelnen Abfrage kombiniert werden, kann eine Anfrage über die Google Ads API gestellt werden.

klauseln

ondemand_video Video: GAQL Field Compatibility

AUSWÄHLEN

Die SELECT-Klausel gibt eine Reihe von Feldern an, die in der Anfrage abgerufen werden sollen. SELECT akzeptiert eine durch Kommas getrennte Liste mit Ressourcenfeldern, Segmentfeldern und Messwerten und gibt die Werte in der Antwort zurück. Die SELECT-Klausel ist in einer Abfrage erforderlich.

Die Beispielabfrage unten 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

• 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 aufgrund der folgenden Einschränkungen möglicherweise nicht zulässig:

• Abfragen von Feldern, die nicht ausgewählt werden können. Für diese Felder ist das Metadatenattribut Selectable als false gekennzeichnet.
• Attribute von wiederkehrenden Feldern auswählen Für diese Felder ist das Metadatenattribut isRepeated 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. Außerdem ist für die Ressource in der FROM-Klausel nur eine Teilmenge aller Messwerte und Segmente verfügbar.
• Sie haben Segmente oder Messwerte ausgewählt, 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.

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 einzelne Ressource angegeben werden. Die FROM-Klausel ist erforderlich in einer Abfrage für 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 Attributed Resources 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 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 wird ad_group.resource_name in die Antwort aufgenommen, 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 wird 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. Jede Bedingung sollte dem Muster field_name Operator value entsprechen. Die WHERE-Klausel ist in einer Abfrage optional.

Im Folgenden sehen Sie ein Beispiel für die Verwendung von WHERE zum Zurückgeben von Messwerten aus einem bestimmten Zeitraum:

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. Die folgenden Datumssegmente, die als Kern-Datumssegmente bezeichnet werden, sind Ausnahmen:

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

Beachten Sie, dass in der folgenden Abfrage segments.date ausgewählt ist. Da es sich bei diesem Segment um ein wichtiges Datumssegment handelt, muss ein endlicher Zeitraum angegeben werden, der aus wichtigen Datumssegmenten in der WHERE-Klausel 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 WHERE-Klausel verwendet werden.

Beim Filtern ist es wichtig, die Groß-/Kleinschreibung des Operators zu beachten. Weitere Informationen finden Sie unter Berücksichtigung der Groß-/Kleinschreibung.

Eine vollständige Liste der Operatoren finden Sie in der Sprachgrammatik.

ORDER BY

Mit der ORDER BY-Klausel wird die Reihenfolge angegeben, 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 die Reihenfolge standardmäßig auf ASC festgelegt. 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. In dieser Abfrage werden beispielsweise Anzeigengruppendaten ausgewählt. Die Ergebnisse werden in aufsteigender Reihenfolge nach Kampagnenname, dann in absteigender Reihenfolge nach Anzahl der Impressionen und schließlich 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

Setzen Sie include_drafts auf true, 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, damit der Ressourcenname der einzelnen Ressourcentypen in der Antwort nur zurückgegeben wird, wenn er in der SELECT-Klausel explizit 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 Klausel bietet die Google Ads-Abfragesprache die folgenden Verhaltensweisen, die genutzt werden können:

• Es ist nicht erforderlich, dass sich das Hauptressourcenfeld für eine Abfrage in der SELECT-Klausel befindet. Beispiel: Sie möchten Daten nur anhand eines oder mehrerer Hauptressourcenfelder 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. 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'