Google Ads-Abfragesprache

Mit der Google Ads Query Language können Sie die Google Ads API abfragen

Ressourcen und ihre zugehörigen Attribute, Segmente und Messwerte mithilfe von
GoogleAdsService Suche oder SearchStream
Das Ergebnis einer GoogleAdsService-Abfrage ist eine Liste mit GoogleAdsRow-Instanzen, wobei jede GoogleAdsRow für eine Ressource steht. 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 der Segmentressourcen.
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.

Attribute einer Ressource abfragen

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

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

Mit dieser Abfrage wird nach Kampagnen-ID sortiert. Jede resultierende GoogleAdsRow würde ein campaign-Objekt darstellen, das mit den ausgewählten Feldern gefüllt ist (einschließlich der resource_name der jeweiligen Kampagne).

Informationen zu weiteren 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 verwandte 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 Kampagnen mit dem Status PAUSED und mehr als 1.000 Impressionen, wobei nach Kampagnen-ID sortiert wird. In jedem resultierenden GoogleAdsRow wird das Feld metrics mit den ausgewählten Messwerten gefüllt.

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

Segmente abfragen

Neben den ausgewählten Attributen für eine bestimmte Ressource können Sie auch nach zugehörigen 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 filtert diese Abfrage nur nach Kampagnen mit dem Status PAUSED und mehr als 1.000 Impressionen. Die Daten werden bei dieser Abfrage jedoch nach Datum segmentiert. Dies führt zu jeder resultierenden GoogleAdsRow, die ein Tupel einer Kampagne und das Datum Segment darstellt. Beachten Sie, dass durch die Segmentierung die ausgewählten Messwerte aufgeteilt und nach jedem Segment in der SELECT-Klausel gruppiert werden.

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

In einer Abfrage für eine bestimmte Ressource können Sie gegebenenfalls einen Join mit anderen verwandten Ressourcen durchführen, sofern verfügbar. Diese verwandten Ressourcen werden als „zugeordnete Ressourcen“ bezeichnet. Sie können implizit mit zugeordneten Ressourcen zusammenführen, indem Sie ein Attribut in der 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 mit den ausgewählten Kampagnenattributen und dem ausgewählten Gebotsstrategieattribut bidding_strategy.name dar.

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

Basierend auf Abfrageergebnissen ändern

Bei der Abfrage einer bestimmten Ressource können Sie diese zurückgegebenen Ergebnisse sofort als Objekte verwenden, sie ändern und zurück an die mutate-Methode im Dienst dieser Ressource senden. Hier ein Beispiel für einen Workflow:

  1. Führen Sie eine Abfrage für alle Kampagnen aus, die derzeit den Status PAUSED haben und mehr als 1.000 Impressionen erzielen.
  2. Rufen Sie das Campaign-Objekt aus dem Feld campaign von jedem GoogleAdsRow in der Antwort ab.
  3. Ändern Sie den Status der einzelnen Kampagnen von „PAUSED“ zu „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. Diese Informationen können verwendet werden, um zu verstehen, wie die Felder zusammen in einer Abfrage verwendet werden können. Da Daten über die API verfügbar sind und die erforderlichen Metadaten zum Validieren oder Erstellen einer Abfrage bereitstellen, können Entwickler dies programmatisch tun. Hier ist eine typische Abfrage von 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 Dokumentation zu GoogleAdsField.

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. Für den Ordner reporting gibt es ein GetKeywordStats-Beispiel.