Google Ads-Abfragesprache

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Die Google Ads Query Language kann die Google Ads API nach

Ressourcen und ihre zugehörigen Attribute, Segmente und Messwerte mithilfe von
GoogleAdsService Suche oder SearchStream
Das Ergebnis einer GoogleAdsService-Abfrage ist eine Liste von GoogleAdsRow-Instanzen, wobei jede GoogleAdsRow eine Ressource darstellt. Wenn Attribute oder Messwerte angefordert werden, enthält die Zeile auch diese Felder. Wenn Segmente angefordert werden, enthält die Antwort auch eine zusätzliche Zeile für jedes Tupel aus Segmentressourcen.
Metadaten zu verfügbaren Feldern und Ressourcen in
GoogleAdsFieldService

Dieser Dienst bietet einen Katalog von abfragbaren Feldern mit Details zu ihrer Kompatibilität und ihrem Typ.

Das Ergebnis einer GoogleAdsFieldService-Abfrage ist eine Liste von GoogleAdsField-Instanzen, wobei jede GoogleAdsField Details zum angeforderten Feld enthält.

Attribute einer Ressource abfragen

Im Folgenden finden Sie eine einfache Abfrage für Attribute der Kampagnenressource, die veranschaulichen, wie Kampagnen-ID, -Name und -Status zurückgegeben werden:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Bei dieser Abfrage wird nach Kampagnen-ID sortiert. Jedes Ergebnis GoogleAdsRow würde ein campaign-Objekt darstellen, das mit den ausgewählten Feldern gefüllt wird (einschließlich resource_name dieser bestimmten Kampagne).

Weitere Informationen zu den anderen Feldern, die für Kampagnenabfragen verfügbar sind, finden Sie in der Referenzdokumentation zu Campaign.

Messwerte abfragen

Neben ausgewählten Attributen für eine bestimmte Ressource können Sie auch zugehörige Messwerte abfragen:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Diese Abfrage filtert nur nach den Kampagnen mit dem Status PAUSED und mit mehr als 1.000 Impressionen, wobei die Sortierung nach Kampagnen-ID erfolgt. Für jedes resultierende GoogleAdsRow wird ein metrics-Feld mit den ausgewählten Messwerten ausgefüllt.

Eine Liste der Messwerte, die abgefragt werden können, finden Sie in der Dokumentation zu Metrics.

Segmente abfragen

Neben ausgewählten Attributen für eine bestimmte Ressource können Sie auch nach ähnlichen Segmenten abfragen:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Ähnlich wie bei der Abfrage von Messwerten werden bei dieser Abfrage nur die Kampagnen mit dem Status PAUSED und mit mehr als 1.000 Impressionen gefiltert. Die Daten werden jedoch nach Datum segmentiert. Dies führt dazu, dass jedes Ergebnis GoogleAdsRowein Tupel einer Kampagne und das Datum Segment darstellt. Dabei ist zu beachten, dass die Segmentierung die ausgewählten Messwerte teilt, indem sie nach den einzelnen Segmenten in der SELECT-Klausel gruppiert werden.

Eine Liste der abfragbaren Segmente finden Sie in der Segments-Dokumentation.

In einer Abfrage für eine bestimmte Ressource können Sie ggf. eine Verknüpfung mit anderen zugehörigen Ressourcen herstellen. Diese zugehörigen Ressourcen werden als „zugeordnete Ressourcen“ bezeichnet. Sie können implizit mit zugeordneten Ressourcen verknüpft werden, indem Sie ein Attribut in Ihrer Abfrage auswählen.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Mit dieser Abfrage werden nicht nur Kampagnenattribute ausgewählt, sondern auch zugehörige Attribute aus jeder ausgewählten Kampagne abgerufen. Jedes resultierende GoogleAdsRow stellt ein campaign-Objekt dar, das mit den ausgewählten Kampagnenattributen sowie dem ausgewählten Gebotsstrategieattribut bidding_strategy.name ausgefüllt wird.

Informationen zu den für Ressourcenabfragen verfügbaren Ressourcen finden Sie in der Referenzdokumentation zu Campaign.

Änderung anhand von Abfrageergebnissen

Wenn Sie eine bestimmte Ressource abfragen, können Sie die zurückgegebenen Ergebnisse sofort als Objekte übernehmen, sie ändern und an die Methode „mutieren“ im Dienst dieser Ressource zurücksenden. Hier ein Beispiel für einen Workflow:

  1. Führen Sie eine Abfrage für alle Kampagnen aus, die derzeit PAUSED sind und Impressionen über 1.000 haben.
  2. Rufen Sie das Objekt Campaign aus dem Feld campaign jeder GoogleAdsRow in der Antwort ab.
  3. Ändern Sie den Status der einzelnen Kampagnen von PAUSED in ENABLED.
  4. Rufen Sie CampaignService.MutateCampaigns mit den geänderten Kampagnen auf, um sie zu aktualisieren.

Feldmetadaten

An GoogleAdsFieldService gesendete Abfragen sind zum Abrufen von Feldmetadaten gedacht. Anhand dieser Informationen können Sie nachvollziehen, wie die Felder in einer Abfrage gemeinsam verwendet werden können. Da Daten aus der API verfügbar sind und die erforderlichen Metadaten zum Validieren oder Erstellen einer Abfrage enthalten, können Entwickler dies programmatisch tun. Hier ist eine typische Abfrage für Metadaten:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Sie können <INSERT_RESOURCE_OR_FIELD> in dieser Abfrage durch eine Ressource (z. B. customer oder campaign) oder ein Feld (z. B. campaign.id, metrics.impressions oder ad_group.id) ersetzen.

Eine Liste der abfragbaren Felder finden Sie in der GoogleAdsField-Dokumentation.

Codebeispiele

In den Clientbibliotheken finden Sie Beispiele für die Verwendung der Google Ads Query Language in GoogleAdsService. Der Ordner basic operations enthält Beispiele wie GetCampaigns, GetKeywords und SearchForGoogleAdsFields. Der Ordner reporting enthält ein Beispiel für GetKeywordStats.