Google Ads-Abfragesprache

Tipp: Verwenden Sie den interaktiven Query Builder, um Ihre GAQL-Abfragen zu erstellen und zu validieren.

Schlüsselterminologie

Ressource

Ein Element 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 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 ist, sodass Sie ihre Attribute zusammen mit den Attributen der Hauptressource auswählen können.

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-Abfrage 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 von Attributen der Kampagnenressource, mit der die Kampagnen-ID, der Name und der Status zurückgegeben werden:

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

Diese Abfrage sortiert nach Kampagnen-ID. 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.

Weitere Felder, 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

Mit dieser Abfrage werden nur die Kampagnen mit dem Status PAUSED und mehr als 1.000 Impressionen gefiltert und nach Kampagnen-ID sortiert. Jedes resultierende GoogleAdsRow-Objekt 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.

Segmente abfragen

Neben ausgewählten Attributen für eine bestimmte Ressource können Sie auch zugehörige Segmente 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 Kampagnen mit dem Status PAUSED und mehr als 1.000 Impressionen berücksichtigt. Diese Abfrage segmentiert die Daten jedoch nach Datum. Dies führt dazu, dass jede resultierende GoogleAdsRow ein Tupel aus einer Kampagne und dem Datumssegment darstellt. Durch die Segmentierung werden die ausgewählten Messwerte aufgeteilt und nach jedem Segment in der SELECT-Klausel gruppiert.

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

Attribute einer zugehörigen Ressource abfragen

In einer Abfrage für eine bestimmte Ressource können Sie gegebenenfalls einen Join mit anderen zugehörigen Ressourcen durchführen, sofern verfügbar. Diese zugehörigen Ressourcen werden als „zugeordnete Ressourcen“ bezeichnet. Sie können implizit einen Join mit attributierten Ressourcen erstellen, 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-Objekt stellt ein campaign-Objekt dar, das mit den ausgewählten Kampagnenattributen sowie dem ausgewählten Gebotsstrategieattribut bidding_strategy.name gefüllt ist.

Informationen dazu, welche zugeordneten Ressourcen für Kampagnenabfragen verfügbar sind, finden Sie in der Referenzdokumentation zu Campaign.

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.

Basierend auf Abfrageergebnissen mutieren

Wenn Sie eine bestimmte Ressource abfragen, können Sie die zurückgegebenen Ergebnisse sofort als Objekte übernehmen, 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 einer entsprechenden FieldMask auf, um sie zu aktualisieren.

Hinweis: Wenn Sie Ressourcen aktualisieren, die aus einer Abfrage abgerufen wurden, geben Sie eine FieldMask an (oder verwenden Sie das integrierte Feldmasken-Dienstprogramm Ihrer Clientbibliothek), damit nur die geänderten Felder aktualisiert werden. So vermeiden Sie READ_ONLY_FIELD- oder IMMUTABLE_FIELD-Fehler oder das unbeabsichtigte Überschreiben anderer Attribute.

Feldmetadaten

An GoogleAdsFieldService gesendete Abfragen dienen zum Abrufen von Feldmetadaten. Anhand dieser Informationen können Sie nachvollziehen, wie die Felder in einer Abfrage zusammen verwendet werden können. Da die 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 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.

Wichtiger Hinweis: Beachten Sie, dass diese Abfrage keine FROM-Klausel enthält.

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

Versionsspezifische Unterschiede

Die Syntax, Klauseln und Operatoren der Google Ads Query Language sind in allen unterstützten Google Ads API-Versionen (v23, v24, v25 und v26) identisch. Der Katalog der abfragbaren Ressourcen, Segmente, Messwerte und Berichtsverhalten 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:

• Asset-Ansicht „Erweiterung der finalen URL“:
  • Unterstützung von Shopping-Kampagnen (v26 und höher): final_url_expansion_asset_view unterstützt neben Performance Max- und Suchkampagnen auch Shopping-Kampagnen (campaign.advertising_channel_type = 'SHOPPING'). Bei Shopping-Kampagnen können Sie ad_group-Felder auswählen und danach filtern, aber keine asset_group-Felder auswählen.
  • Auswählbare Messwerte (v25 und höher): Wenn Sie final_url_expansion_asset_view abfragen, werden alle auswählbaren Messwerte für die Ansicht zurückgegeben. In v24 und früheren Versionen enthalten Antworten nur metrics.conversions und metrics.conversions_value für Performance Max-Kampagnen und metrics.impressions für Suchkampagnen.
• Ressourcen für Zielvorhaben für den Kundenlebenszyklus: Ab Version 25 werden alle Zielvorhaben für den Kundenlebenszyklus (Kundenakquisition, Kundenbindung und Kundenbindungsprogramm) über die einheitlichen Ressourcen goal und campaign_goal_config abgefragt. Diese ersetzen customer_lifecycle_goal und campaign_lifecycle_goal, die in Version 24 und früher für Zielvorhaben „Kundenakquisition“ verwendet wurden, sowie goal und campaign_goal_config für Zielvorhaben „Kundenbindung“.
• Shopping-Produktberichte für App-Kampagnen: Ab v24 gibt die Ressource shopping_product Produktzeilen für App-Kampagnen sowie für Shopping-, Performance Max-, Demand Gen- und Videokampagnen zurück. In v23 sind App-Kampagnen von den shopping_product-Ergebnissen ausgeschlossen.
• Versionsspezifische Ressourcen, Segmente und Messwerte:
  • v26 und höher: Enthält die Ressource search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property und Messwerte für den Suchanstieg (z. B. metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros und metrics.search_lift_impressions).
  • Ab Version 25: Enthält Ressourcen zur Messung der Anzeigenwirkung auf die Markenbekanntheit (z. B. lift_measurement_config), Segmente wie segments.ad_sub_format_type und segments.loyalty_membership sowie YouTube-Interaktionsmesswerte (metrics.youtube_likes, metrics.youtube_comments und metrics.youtube_shares). local_services_lead.contact_details.email (in Version 24 und früheren Versionen auswählbar) wird entfernt.
  • v24 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 (nur in v23 auswählbar).
• Fehlercode für detaillierten Lookback-Window: 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 Lookback-Window von 37 Monaten hinausgehen, geben in v24 und höher DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (oder in v23 DateRangeError.UNKNOWN) zurück. Weitere Informationen finden Sie unter Zeiträume.

Codebeispiele

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