Google Ads-Abfragesprache

Schlüsselterminologie

Ressource

Eine Entität in Google Ads, z. B. campaign oder ad_group.

Segment

Eine Dimension, die zum Gruppieren von Daten verwendet wird, z. B. segments.date oder segments.device. Wenn Segmente in der SELECT-Klausel mit Messwerten enthalten sind, werden die Messwerte nach Segment aufgeschlüsselt.

Messwert

Ein Maß für die Leistung, z. B. metrics.impressions oder metrics.clicks.

Attributierte Ressource

Eine Ressource, die implizit mit der Hauptressource in der FROM-Klausel verknüpft ist. So können Sie ihre Attribute zusammen mit den Attributen der Hauptressource auswählen.

Abfrage von Ressourcen- oder Metadateninformationen

Mit der Google Ads Query Language können Sie die Google Ads API nach den folgenden Arten von Informationen abfragen:

• Ressourcen und ihre zugehörigen Attribute, Segmente und Messwerte mit GoogleAdsService Search 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 Segment-Ressourcen-Tupel.

• Metadaten zu verfügbaren Feldern und Ressourcen in GoogleAdsFieldService: Dieser Dienst bietet einen Katalog abfragbarer Felder mit Angaben 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.

Weitere Informationen zur Abfragestruktur finden Sie unter Query Structure und Google Ads Query Language Grammar.

Abfrage von Ressourcenattributen

Hier ist ein Beispiel für eine einfache Abfrage von Attributen der Kampagnenressource, die zeigt, wie Sie die Kampagnen-ID, den Namen und den Status zurückgeben:

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

Diese Abfrage wird nach Kampagnen-ID sortiert. Jede resultierende GoogleAdsRow stellt ein campaign-Objekt dar, das mit den ausgewählten Feldern gefüllt ist, einschließlich des resource_name der Kampagne.

Welche anderen Felder für Kampagnenabfragen verfügbar sind, erfahren Sie in der Campaign Referenzdokumentation.

Abfrage von Messwerten

Neben den ausgewählten Attributen für eine bestimmte Ressource können Sie auch nach zugehörigen Messwerten suchen:

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 Kampagnen mit dem Status PAUSED und mehr als 1.000 Impressionen und sortiert nach Kampagnen-ID. Jede resultierende GoogleAdsRow enthält ein metrics-Feld, das mit den ausgewählten Messwerten gefüllt ist.

Eine Liste der abfragbaren Messwerte finden Sie in der Metrics Dokumentation.

Abfrage von Segmenten

Neben den ausgewählten Attributen für eine bestimmte Ressource können Sie auch nach zugehörigen Segmenten suchen:

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 filtert diese Abfrage nur nach Kampagnen mit dem Status PAUSED und mehr als 1.000 Impressionen. Bei dieser Abfrage werden die Daten jedoch nach Datum segmentiert. Das führt dazu, dass jede resultierende GoogleAdsRow ein Tupel aus einer Kampagne und dem Datum Segment darstellt. Durch die Segmentierung werden die ausgewählten Messwerte aufgeschlüsselt und nach den einzelnen Segmenten in der SELECT-Klausel gruppiert.

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

Abfrage von Attributen einer zugehörigen Ressource

In einer Abfrage für eine bestimmte Ressource können Sie gegebenenfalls mit anderen zugehörigen Ressourcen verknüpfen. Diese zugehörigen Ressourcen werden als „attributierte Ressourcen“ bezeichnet. Sie können implizit mit attribuierten Ressourcen verknüpfen, 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

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

Welche attribuierten Ressourcen für Kampagnenabfragen verfügbar sind, erfahren Sie in der Campaign Referenzdokumentation.

Best Practices

• Wählen Sie nur die Felder aus, die Sie benötigen, um lange Antwortzeiten und Zeitüberschreitungen zu vermeiden.
• Verwenden Sie LIMIT während der Entwicklung und des Testens, um die Verarbeitung großer Ergebnismengen zu vermeiden.
• Wenden Sie Filter in der WHERE-Klausel an, um die Datenübertragung und die Antwortgröße zu minimieren.
• Verwenden Sie GoogleAdsFieldService, um die Feldkompatibilität und Datentypen zu prüfen, bevor Sie komplexe Abfragen erstellen.
• Beachten Sie, dass einige Felder, insbesondere solche mit großen Datenmengen oder komplexen Berechnungen, die Abfragekosten erhöhen können.

Änderungen basierend auf Abfrageergebnissen vornehmen

Wenn Sie eine bestimmte Ressource abfragen, können Sie die zurückgegebenen Ergebnisse sofort als Objekte verwenden, sie ändern und an die Mutate-Methode im Dienst dieser Ressource zurücksenden. Hier ist ein Beispiel für einen Workflow: 1. Führen Sie eine Abfrage für alle Kampagnen aus, die derzeit PAUSED sind und mehr als 1.000 Impressionen haben. 1. Rufen Sie das Campaign-Objekt aus dem Feld campaign jeder GoogleAdsRow in der Antwort ab. 1. Ändern Sie den Status jeder Kampagne von PAUSED in ENABLED. 1. Rufen Sie CampaignService.MutateCampaigns mit den geänderten Kampagnen auf, um sie zu aktualisieren.

Feldmetadaten

Abfragen, die an GoogleAdsFieldService gesendet werden, dienen zum Abrufen von Feldmetadaten. Anhand dieser Informationen können Sie nachvollziehen, wie die Felder in einer Abfrage zusammen verwendet werden können. Da Daten über die API verfügbar sind und die erforderlichen Metadaten zur Validierung oder Erstellung einer Abfrage bereitgestellt werden, 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 entweder 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

Die Clientbibliotheken enthalten Beispiele für die Verwendung der Google Ads Query Language in GoogleAdsService. Der Ordner Grundlegende Vorgänge enthält Beispiele wie GetCampaigns, GetKeywords und SearchForGoogleAdsFields.