Abfragestruktur

Abfragen für Ressourcen-, Segment- und Messwertfelder können an die Methoden Search oder SearchStream von GoogleAdsService gesendet werden. Wenn Sie eine Abfrage in der Google Ads-Abfragesprache erstellen möchten, müssen Sie die Grammatik der Sprache verwenden. 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. Nachdem sie zu einer einzelnen Abfrage kombiniert wurden, kann eine Anfrage über die Google Ads API gesendet werden.

Wichtiger Hinweis :GoogleAdsFieldService ist ein Katalog für Google Ads Query Language-Clients mit Metadaten zu allen Ressourcenfeldern, Segmentfeldern und Messwerten sowie deren Beziehungen zueinander und Verfügbarkeit in den einzelnen Klauseln, wie unten definiert. Weitere Informationen finden Sie in der Dokumentation zu GoogleAdsField.

klauseln

Video: GAQL-Feldkompatibilität

AUSWÄHLEN

Mit der SELECT-Klausel wird eine Reihe von Feldern angegeben, die in der Anfrage abgerufen werden sollen. SELECT nimmt eine durch Kommas getrennte Liste von Ressourcenfeldern, Segmentfeldern und Messwerten entgegen 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 verschiedene Feldtypen in einer einzigen Anfrage 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 aufgrund der folgenden Einschränkungen möglicherweise nicht in der SELECT-Klausel zulässig:

• Abfragen von Feldern, die nicht ausgewählt werden können. Das Selectable-Metadatenattribut dieser Felder ist als false gekennzeichnet.
• Attribute von wiederkehrenden Feldern auswählen Das isRepeated-Metadatenattribut dieser Felder ist als true gekennzeichnet.
• In der FROM-Klausel werden Felder ausgewählt, die für die angegebene Ressource nicht verfügbar sind. Attribute einiger Ressourcen können nicht gemeinsam ausgewählt werden. Außerdem ist für die Ressource in der FROM-Klausel nur ein Teil aller Messwerte und Segmente verfügbar.
• Sie haben Segmente oder Messwerte ausgewählt, die nicht miteinander kompatibel sind. Weitere Informationen finden Sie im Abschnitt Segmentierung.

Informationen zu den oben genannten Bedingungen finden Sie in unseren Referenzdokumenten 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 einzige Ressource angegeben werden. Die Klausel FROM ist erforderlich in einer Abfrage an die Methoden GoogleAdsService Search oder SearchStream. Sie sollte jedoch nicht angegeben werden, wenn die Methode GoogleAdsFieldService verwendet wird.

In der FROM-Klausel für eine bestimmte Abfrage kann nur eine Ressource vorhanden sein. Es können aber auch Felder aus zugeordneten Ressourcen verfügbar sein. Diese Ressourcen werden implizit mit der Ressource in der FROM-Klausel zusammengeführt. Sie müssen also nur die 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 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 der Antwort für die folgende Abfrage enthalten sein:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Wichtiger Hinweis :Wenn in der Ressource in der FROM-Klausel eine andere Ressource als segment aufgeführt ist, werden alle Attribute dieser Ressource als Segment verwendet.

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 und sie mit AND voneinander trennen. Jede Bedingung sollte dem Muster field_name Operator value folgen. Die WHERE-Klausel 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. Die folgenden Datumssegmente, die als Kerndatumssegmente bezeichnet werden, sind Ausnahmen:

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

In der folgenden Abfrage ist segments.date ausgewählt. Da es sich bei diesem Segment um ein Kerndatumssegment handelt, ist in der WHERE-Klausel ein begrenzter Zeitraum aus Kerndatumssegmenten anzugeben.

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.

Wichtig: Das Trennzeichen AND kann nur zwischen Operatorbedingungen (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") und nicht innerhalb einer einzelnen Operatorbedingung (WHERE segments.device != "DESKTOP" AND "MOBILE") verwendet werden.

Beim Filtern ist es wichtig, zwischen Groß- und Kleinschreibung zu unterscheiden. 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 festgelegt, in der die Ergebnisse zurückgegeben werden sollen. So können Sie die Daten nach einem Feldnamen 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.

Mit der folgenden Abfrage werden die zurückgegebenen Kampagnen nach der Anzahl der Klicks von der höchsten zur niedrigsten sortiert:

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

Sie können mehrere Felder in der ORDER BY-Klausel 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 an einer Zusammenfassung interessiert sind.

Mit LIMIT können Sie beispielsweise die Gesamtzahl der Ergebnisse für die folgende Abfrage einschränken:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Wichtig :Mit LIMIT können Sie die Ergebnisse abschneiden. Verwenden Sie das Feld page_size von GoogleAdsService.Search, um lange Ergebnislisten zu verarbeiten.

PARAMETER

Mit der Klausel PARAMETERS können Sie Metaparameter für die Anfrage angeben. Diese Parameter können sich darauf auswirken, welche Zeilen zurückgegeben werden.

Derzeit werden die folgenden Metaparameter unterstützt:

include_drafts

Legen Sie include_drafts auf true fest, um die Rückgabe von Entwürfen zuzulassen. Die Standardeinstellung ist false.

Mit der folgenden Abfrage werden beispielsweise sowohl Kampagnen in der Entwurfsphase als auch reguläre Kampagnen abgerufen:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Legen Sie omit_unselected_resource_names auf true fest, damit der Ressourcenname jedes Ressourcentyps in der Antwort nicht zurückgegeben wird, es sei denn, dies wird in der SELECT-Klausel ausdrücklich angefordert. Die Standardeinstellung ist false.

Hinweis: Wenn Sie eines der zurückgegebenen Objekte für Aktualisierungs- oder Löschvorgänge verwenden möchten, empfehlen wir, diese Option auf false festzulegen, da Ressourcen ohne Ressourcennamen nicht für Änderungsvorgänge verwendet werden können. Wenn Sie diese Option auf true festlegen, müssen Sie die Ressourcennamen sowohl der primären Ressource als auch aller Attributressourcen, die Sie mit der Abfrage abrufen, explizit anfordern.

omit_unselected_resource_names examples
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names ist standardmäßig false. Daher werden alle „resource_name“-Felder zurückgegeben.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: Keine. omit_unselected_resource_names ist als true angegeben und campaign.resource_name und customer.resource_name sind nicht Teil der SELECT-Klausel.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: campaign.resource_name omit_unselected_resource_names ist 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 bietet die Google Ads-Abfragesprache die folgenden Verhaltensweisen:

• Es ist nicht erforderlich, dass sich das Hauptressourcenfeld in der SELECT-Klausel einer Abfrage befindet. Beispielsweise können Sie nur ein oder mehrere Hauptressourcenfelder 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 weiteren 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
  

• Mit dem Feld resource_name (z. B. campaign.resource_name) können Daten gefiltert oder sortiert werden:

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