Google Ads-Abfragesprache

Mit der Google Ads-Abfragesprache können Sie die Google Ads API um folgende Informationen bitten:

Ressourcen und zugehörige Attribute, Segmente und Messwerte mit

GoogleAdsService Suchen oder SearchStream

Das Ergebnis einer GoogleAdsService-Abfrage ist eine Liste von GoogleAdsRow-Instanzen. Jede GoogleAdsRow steht für eine Ressource. Wenn Attribute oder Messwerte angefordert werden, enthält die Zeile auch diese Felder. Wenn Segmente angefordert werden, enthält die Antwort außerdem eine zusätzliche Zeile für jedes Segment-Ressourcen-Tupel.

Metadaten zu verfügbaren Feldern und Ressourcen in

GoogleAdsFieldService

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

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

Attribute einer Ressource abfragen

Unten sehen Sie eine einfache Abfrage für Attribute der Kampagnenressource, die zeigt, 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 erfolgt die Sortierung nach Kampagnen-ID. Jedes resultierende GoogleAdsRow stellt ein campaign-Objekt dar, das mit den ausgewählten Feldern ausgefüllt ist, einschließlich der resource_name der jeweiligen Kampagne.

Weitere Informationen zu den für Kampagnenabfragen verfügbaren Feldern finden Sie in der Referenzdokumentation zu Campaign.

Messwerte abfragen

Neben 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

Mit dieser Abfrage werden nur Kampagnen mit dem Status PAUSED gefiltert, die mehr als 1.000 Impressionen erzielt haben. Die Ergebnisse werden nach Kampagnen-ID sortiert. Jede resultierende GoogleAdsRow hat ein metrics-Feld, das mit den ausgewählten Messwerten ausgefü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 nach ähnlichen 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 nach Messwerten werden bei dieser Abfrage nur die Kampagnen gefiltert, die den Status PAUSED haben und mehr als 1.000 Impressionen erzielt haben. Die Daten werden jedoch nach Datum segmentiert. Das führt dazu, dass jede resultierende GoogleAdsRow ein Tupel aus einer Kampagne und dem Datum Segment darstellt. Bei der Segmentierung werden die ausgewählten Messwerte aufgeteilt und in der SELECT-Klausel nach den einzelnen Segmenten gruppiert.

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

Attribute einer verknüpften Ressource abfragen

In einer Abfrage für eine bestimmte Ressource können Sie gegebenenfalls eine Verbindung zu anderen zugehörigen Ressourcen herstellen. Diese verknüpften Ressourcen werden als „zugewiesene Ressourcen“ bezeichnet. Sie können eine implizite Zusammenführung mit zugeordneten Ressourcen durchführen, indem Sie in Ihrer Abfrage ein Attribut 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. Jedes resultierende GoogleAdsRow ist ein campaign-Objekt, das mit den ausgewählten Kampagnenattributen sowie dem ausgewählten Attribut der Gebotsstrategie bidding_strategy.name ausgefüllt ist.

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

Mutation basierend auf Abfrageergebnissen

Wenn Sie eine Abfrage für eine bestimmte Ressource ausführen, können Sie die zurückgegebenen Ergebnisse sofort als Objekte verwenden, sie ändern und an die Mutate-Methode im Dienst dieser Ressource zurücksenden. Unten sehen Sie einen Beispiel-Workflow:

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

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 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 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-Abfragesprache in GoogleAdsService. Der Ordner Grundlegende Vorgänge enthält Beispiele wie GetCampaigns, GetKeywords und SearchForGoogleAdsFields.