Google Ads-Abfragesprache

Schlüsselterminologie

Ressource

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

Segment

Eine Dimension, mit der Daten gruppiert werden, z. B. segments.date oder segments.device. Wenn Segmente mit Messwerten in die SELECT-Klausel aufgenommen werden, werden die Messwerte nach Segment aufgeteilt.

Messwert

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

Zugeordnete Ressource

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

Ressourcen- oder Metadateninformationen abfragen

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

• Ressourcen und die 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 Details zu ihrer Kompatibilität und ihrem Typ.

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

Weitere Informationen zur Abfragestruktur finden Sie unter Abfragestruktur und Grammatik der Google Ads Query Language.

Abfrage von Ressourcenattributen

Hier ist ein Beispiel für eine einfache Abfrage für Attribute der Kampagnenressource, die zeigt, wie die Kampagnen-ID, der Name und der Status zurückgegeben werden:

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

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

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

Messwerte abfragen

Neben den 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

Mit dieser Abfrage werden nur die Kampagnen mit dem Status PAUSED gefiltert, die mehr als 1.000 Impressionen erzielt haben. Die Ergebnisse werden nach Kampagnen-ID sortiert. Jeder resultierende GoogleAdsRow hätte ein metrics-Feld, das mit den ausgewählten Messwerten gefüllt ist.

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

Segmente abfragen

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 beim Abfragen von Messwerten werden in dieser Abfrage nur die Kampagnen gefiltert, die den Status PAUSED haben und mehr als 1.000 Impressionen erzielt haben. Bei dieser Abfrage werden die Daten jedoch nach Datum segmentiert. Jedes resultierende GoogleAdsRow steht für ein Tupel aus einer Kampagne und dem Datumssegment. Beim Segmentieren werden die ausgewählten Messwerte aufgeteilt und nach jedem Segment in der SELECT-Klausel gruppiert.

Eine Liste der Segmente, die abgefragt werden können, finden Sie in der Segments-Dokumentation.

Attribute einer zugehörigen Ressource abfragen

In einer Abfrage für eine bestimmte Ressource können Sie unter Umständen Joins mit anderen zugehörigen Ressourcen ausführen, sofern diese verfügbar sind. Diese verknüpften Ressourcen werden als „Ressourcen mit Quellenangabe“ bezeichnet. Sie können implizit mit Attributressourcen 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

Mit dieser Abfrage werden nicht nur Kampagnenattribute ausgewählt, sondern auch zugehörige Attribute aus jeder ausgewählten Kampagne abgerufen. Jedes resultierende GoogleAdsRow steht für ein campaign-Objekt, das mit den ausgewählten Kampagnenattributen sowie dem ausgewählten Attribut für die Gebotsstrategie bidding_strategy.name gefüllt ist.

Informationen dazu, welche zugehörigen Ressourcen für Kampagnenabfragen verfügbar sind, finden 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.
• Mit GoogleAdsFieldService können Sie die Kompatibilität von Feldern und Datentypen prüfen, bevor Sie komplexe Abfragen erstellen.
• Einige Felder, insbesondere solche, die große Datenmengen oder komplexe Berechnungen umfassen, können die Abfragekosten erhöhen.

Mutieren basierend auf Abfrageergebnissen

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 ein Beispiel für einen Workflow:

1. Führen Sie eine Abfrage für alle PAUSED-Kampagnen mit mehr als 1.000 Impressionen aus.
2. Rufen Sie das Campaign-Objekt aus dem Feld campaign jedes 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 und einem entsprechenden FieldMask auf, um sie zu aktualisieren.

Feldmetadaten

Mit Anfragen, die an GoogleAdsFieldService gesendet werden, sollen Feldmetadaten abgerufen werden. 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 zum Validieren oder Erstellen einer Abfrage bereitgestellt werden, können Entwickler dies programmatisch tun. Hier ist eine typische Anfrage 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.

Versionsspezifische Unterschiede

Die Syntax, Klauseln und Operatoren der Google Ads-Abfragesprache sind in allen unterstützten Google Ads API-Versionen (v23, v24 und v25) identisch. Der Katalog der abfragbaren Ressourcen, Segmente, Messwerte und Berichtsfunktionen unterscheidet sich jedoch je nach Hauptversion. Fragen Sie GoogleAdsFieldService am Endpunkt der Ziel-API-Version ab, um die Felder und Kompatibilitätsregeln für diese Version zu prüfen:

• Ressourcen für Zielvorhaben für den Kundenlebenszyklus:In Version 25 und höher werden alle Zielvorhaben für den Kundenlebenszyklus („Kundenakquisition“, „Kundenbindung“ und „Loyalty-Kundenbindung“) über die einheitlichen Ressourcen goal und campaign_goal_config abgefragt. Damit werden customer_lifecycle_goal und campaign_lifecycle_goal ersetzt, die in Version 24 und früher für Zielvorhaben für die Kundenakquisition verwendet wurden. Für Zielvorhaben für die Kundenbindung wurden goal und campaign_goal_config verwendet.
• Messwerte für Assets mit Erweiterung der finalen URL:In Version 25 und höher werden bei der Abfrage von final_url_expansion_asset_view alle auswählbaren Messwerte für die Ansicht zurückgegeben. In Version 24 und früher enthalten Antworten nur metrics.conversions und metrics.conversions_value für Performance Max-Kampagnen sowie metrics.impressions für Suchkampagnen.
• Shopping-Produktberichte für App-Kampagnen:In Version 24 und höher werden mit der Ressource shopping_product zusätzlich zu Shopping-, Performance Max-, Demand Gen- und Videokampagnen auch Produktzeilen für App-Kampagnen zurückgegeben. In Version 23 sind App-Kampagnen in den shopping_product-Ergebnissen ausgeschlossen.
• Versionsspezifische Ressourcen, Segmente und Messwerte:
  • Version 25 und höher:Enthält Ressourcen für die Analyse der Anzeigenwirkung (z. B. lift_measurement_config), Segmente wie segments.ad_sub_format_type und segments.loyalty_membership sowie YouTube-Messwerte zum Engagement (metrics.youtube_likes, metrics.youtube_comments und metrics.youtube_shares). local_services_lead.contact_details.email wird entfernt (in Version 24 und früher auswählbar).
  • Version 24 und höher:Enthält die Ressource cart_data_sales_view, segments.conversion_attribution_event_type auf shopping_performance_view, segments.mobile_device_platform und segments.ad_network_type auf performance_max_placement_view. Entfernt campaign.video_brand_safety_suitability (ersetzt durch customer.video_brand_safety_suitability), segments.ad_sub_network_type auf campaign_budget und segments.click_type auf ad_group_asset, campaign_asset und customer_asset (die nur in Version 23 ausgewählt werden können).
• Fehlercode für detaillierte Datenrückschau: Abfragen, die nach segments.date, segments.week oder segments.hour segmentieren (oder nach einem Zeitraum filtern, der kürzer als ein Monat ist) und über das 37-Monats-Lookback-Window hinausgehen, geben in Version 24 und höher DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED zurück (oder DateRangeError.UNKNOWN in Version 23). Weitere Informationen finden Sie unter Zeiträume.

Codebeispiele

In den Clientbibliotheken finden Sie Beispiele für die Verwendung der Google Ads-Abfragesprache in GoogleAdsService. Der Ordner basic operations enthält Beispiele wie GetCampaigns, GetKeywords und SearchForGoogleAdsFields.