Objekte werden abgerufen

Die GoogleAdsService ist der einheitliche Dienst zum Abrufen von Objekten und Erstellen von Berichten in der Google Ads API. Der Dienst hat Methoden, die:

  • Bestimmte Attribute von Objekten abrufen.
  • Leistungsmesswerte für Objekte basierend auf einem Zeitraum abrufen.
  • Objekte anhand ihrer Attribute sortieren
  • Mit Bedingungen können Sie angeben, welche Objekte in der Antwort zurückgegeben werden sollen.
  • Anzahl der zurückgegebenen Objekte begrenzen.

Die GoogleAdsService kann Ergebnisse auf zwei Arten zurückgeben:

  • GoogleAdsService.SearchStream gibt alle Zeilen in einer einzelnen Streamingantwort zurück,was für große (mehr als 10.000 Zeilen) Ergebnismengen effizienter ist. Das kann sinnvoll sein, wenn Ihre Batchanwendung so viele Daten wie möglich so schnell wie möglich herunterladen soll.
  • Mit GoogleAdsService.Search werden lange Antworten in überschaubare Ergebnisseiten unterteilt. Das ist möglicherweise besser geeignet, wenn in Ihrer interaktiven Anwendung jeweils eine Seite mit Ergebnissen angezeigt wird.

Weitere Informationen zum Paging und Streaming

Anfrage stellen

Für die Suchmethode ist ein SearchGoogleAdsRequest erforderlich, das aus den folgenden Attributen besteht:

  • Ein customer_id
  • Eine Google Ads Query Language-query, die angibt, welche Ressource abgefragt werden soll, welche Attribute, Segmente und Messwerte abgerufen werden sollen und welche Bedingungen verwendet werden sollen, um die zurückgegebenen Objekte einzuschränken
  • (Nur GoogleAdsService.Search) Ein optionales page_token zum Abrufen des nächsten Batches von Ergebnissen bei Verwendung von Paging.

Weitere Informationen zur Google Ads Query Language finden Sie im Leitfaden zur Google Ads Query Language.

Antwort verarbeiten

Die GoogleAdsService gibt eine Liste von GoogleAdsRow-Objekten zurück.

Jedes GoogleAdsRow steht für ein Objekt, das von einer Abfrage zurückgegeben wird, und besteht aus einer Reihe von Attributen, die auf Grundlage der in der SELECT-Klausel angeforderten Feldern ausgefüllt werden. Attribute, die nicht in der SELECT-Klausel enthalten sind, werden in den GoogleAdsRow-Objekten in der Antwort nicht ausgefüllt.

Obwohl ein ad_group_criterion beispielsweise ein status-Attribut hat, wird das status-Feld des ad_group_criterion-Attributs der Zeile in einer Antwort auf eine Abfrage, in der die SELECT-Klausel nicht ad_group_criterion.status enthält, nicht ausgefüllt. Ebenso wird das Attribut campaign der Zeile nicht ausgefüllt, wenn die SELECT-Klausel keine Felder aus der campaign-Ressource enthält.

Jedes GoogleAdsRow kann unterschiedliche Attribute und Messwerte als eine andere Zeile im selben Ergebnis haben. Die Zeilen sollten also als Objekte und nicht als feste Zeilen einer Tabelle betrachtet werden.

UNKNOWN-Enum-Typen

Ressourcen, die mit dem Typ UNKNOWN zurückgegeben werden, werden in dieser API-Version nicht vollständig unterstützt. Diese Ressourcen können über andere Oberflächen wie die Google Ads-Benutzeroberfläche erstellt worden sein. Sie können Messwerte auswählen, wenn eine Ressource den Typ UNKNOWN hat, aber die Ressource nicht über die API ändern. Ein Beispiel hierfür wäre eine neue Kampagne oder Anzeige, die in der Benutzeroberfläche eingeführt wird, aber in der API-Version, die Sie abfragen, nicht unterstützt wird.

Folgendes ist zu beachten:

  • Eine Ressource mit dem Typ UNKNOWN kann später unterstützt werden oder auf unbestimmte Zeit UNKNOWN bleiben.
  • Neue Objekte vom Typ UNKNOWN können jederzeit angezeigt werden. Diese Objekte sind abwärtskompatibel, da der Enum-Wert bereits verfügbar ist. Mit dieser Änderung werden Ressourcen eingeführt, damit Sie einen genauen Überblick über Ihr Konto haben. Die UNKNOWN-Ressource kann aufgrund neuer Aktivitäten in Ihrem Konto über andere Schnittstellen oder wenn eine Ressource nicht mehr unterstützt wird, angezeigt werden.
  • UNKNOWN-Ressourcen können detaillierte Messwerte zugeordnet sein, die abgefragt werden können.
  • UNKNOWN-Ressourcen sind in der Regel vollständig in der Google Ads-Benutzeroberfläche sichtbar.
  • UNKNOWN-Ressourcen können in der Regel nicht geändert werden.

Segmentierung

Die Antwort enthält ein GoogleAdsRow für jede Kombination der folgenden Elemente:

  • Instanz der Hauptressource, die in der FROM-Klausel angegeben ist
  • Wert der einzelnen ausgewählten segment-Felder

Die Antwort auf eine Abfrage, in der FROM campaign ausgewählt wird und die segments.ad_network_type und segments.date in der SELECT-Klausel enthält, würde beispielsweise eine Zeile für jede Kombination aus Folgendem enthalten:

  • campaign
  • segments.ad_network_type
  • segments.date

Die Ergebnisse werden implizit nach jeder Instanz der Hauptressource segmentiert, nicht nach den Werten der ausgewählten einzelnen Felder. Beispiel:

SELECT campaign.status, metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

führt zu einer Zeile pro Kampagne und nicht zu einer Zeile pro eindeutigem Wert des Felds campaign.status.