Objekte abrufen

Der GoogleAdsService ist der einheitliche Dienst zum Abrufen von Objekten und Berichten 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
  • Verwenden Sie Bedingungen, um anzugeben, welche Objekte in der Antwort zurückgegeben werden sollen.
  • Begrenzen Sie die Anzahl der zurückgegebenen Objekte.

Die GoogleAdsService kann Ergebnisse auf zwei Arten zurückgeben:

  • GoogleAdsService.SearchStream gibt alle Zeilen in einer einzigen Streamingantwort zurück. Das ist bei großen Ergebnismengen (mehr als 10.000 Zeilen) effizienter. Dies wird empfohlen, wenn Ihre Anwendung vollständige Ergebnissätze herunterlädt oder Zeilen als Stream verarbeitet.
  • GoogleAdsService.Search teilt große Antworten in überschaubare Ergebnisseiten auf. Das ist nützlich, wenn Ihre interaktive Anwendung jeweils eine Seite mit Ergebnissen anzeigt.

Weitere Informationen zu Paging und Streaming

Anfrage stellen

GoogleAdsService.SearchStream erwartet einen SearchGoogleAdsStreamRequest und GoogleAdsService.Search erwartet einen SearchGoogleAdsRequest. Beide Anfragetypen umfassen:

  • 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

Je nach Methode unterstützt die Anfrage auch methodenspezifische Felder:

  • SearchGoogleAdsStreamRequest (nur SearchStream):
    • Ein optionales summary_row_setting, um eine Zusammenfassungszeile mit aggregierten Messwerten anzufordern.
  • SearchGoogleAdsRequest (nur Search):
    • Ein optionales page_token, um den nächsten Satz von Ergebnissen abzurufen, wenn Paging verwendet wird (page_size ist auf 10.000 Zeilen festgelegt; wenn page_size in der Anfrage festgelegt wird, wird ein RequestError.PAGE_SIZE_NOT_SUPPORTED-Fehler ausgegeben)
    • Eine optionale search_settings-Nachricht zum Konfigurieren von return_summary_row, return_total_results_count und omit_results
    • Ein optionaler boolescher Wert validate_only, um die Abfrage zu validieren, ohne sie auszuführen

Weitere Informationen zur Google Ads-Abfragesprache finden Sie im Leitfaden zur Google Ads-Abfragesprache.

Antwort verarbeiten

Die GoogleAdsService gibt eine Liste von GoogleAdsRow-Objekten zurück (entweder in gestreamten SearchGoogleAdsStreamResponse-Batches oder in einer ausgelagerten SearchGoogleAdsResponse).

Jedes GoogleAdsRow stellt ein von einer Abfrage zurückgegebenes Objekt dar und besteht aus einer Reihe von Attributen, die basierend auf den in der SELECT-Klausel angeforderten Feldern ausgefüllt werden. Attribute, die nicht in der SELECT-Klausel enthalten sind, werden nicht in den GoogleAdsRow-Objekten in der Antwort ausgefüllt.

Beispiel: Obwohl ein ad_group_criterion ein status-Attribut hat, wird das Feld status des ad_group_criterion-Attributs der Zeile in einer Antwort auf eine Abfrage, bei 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 Ressource campaign enthält.

Jede GoogleAdsRow kann andere Attribute und Messwerte als eine andere Zeile im selben Ergebnissatz haben. Die Zeilen sollten daher als Objekte und nicht als feste Zeilen einer Tabelle betrachtet werden.

UNKNOWN- und UNSPECIFIED-Enum-Typen

Ressourcen, die mit dem Enum-Wert UNKNOWN zurückgegeben werden, werden in dieser API-Version nicht vollständig unterstützt. UNSPECIFIED gibt an, dass ein Enum-Feld nicht festgelegt oder in der SELECT-Klausel nicht angefordert wurde. Ressourcen mit dem Enum-Wert UNKNOWN wurden möglicherweise über andere Oberflächen wie die Google Ads-Benutzeroberfläche erstellt. Sie können Messwerte auswählen, wenn eine Ressource den Typ UNKNOWN hat. Sie können die Ressource jedoch nicht über die API ändern. Ein Beispiel hierfür ist ein Kampagnen- oder Anzeigentyp, der in der Benutzeroberfläche verfügbar ist, aber in der von Ihnen abgefragten API-Version nicht unterstützt wird.

Hier einige Tipps zu den jeweiligen Asset-Typen:

  • Eine Ressource mit dem Typ UNKNOWN kann in einer späteren API-Version unterstützt werden oder unbegrenzt UNKNOWN bleiben.
  • Neue Objekte vom Typ UNKNOWN können jederzeit erscheinen. Diese Objekte sind abwärtskompatibel, da der Enum-Wert UNKNOWN in jedem Enum in der API vorhanden ist. Ressourcen werden mit UNKNOWN zurückgegeben, damit Sie einen genauen Überblick über die Gesamtleistungsmesswerte Ihres Kontos haben.
  • An UNKNOWN-Ressourcen können detaillierte Messwerte angehängt werden, die abgefragt werden können.
  • UNKNOWN-Ressourcen sind in der Regel in der Google Ads-Benutzeroberfläche vollständig sichtbar.
  • UNKNOWN-Ressourcen können im Allgemeinen nicht über die API 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 jedes ausgewählten segments-Felds

Die Antwort auf eine Abfrage, die FROM campaign auswählt und segments.ad_network_type und segments.date in der SELECT-Klausel enthält, enthält beispielsweise eine Zeile für jede Kombination der folgenden Elemente:

  • campaign
  • segments.ad_network_type
  • segments.date

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

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

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

Zurück
Objekte ändern
Weiter
Ressourcenmetadaten