Objekte abrufen

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.
• Beschränken Sie die Anzahl der zurückgegebenen Objekte.

Die GoogleAdsService kann Ergebnisse auf zwei Arten zurückgeben:

• GoogleAdsService.SearchStream gibt alle Zeilen in einer einzelnen Streamingantwort zurück. Das ist effizienter für große Ergebnismengen (mehr als 10.000 Zeilen). Diese Option empfiehlt sich, wenn Ihre Anwendung vollständige Ergebnissätze herunterlädt oder Zeilen als Stream verarbeitet.
• Mit GoogleAdsService.Search werden große Antworten in überschaubare Ergebnisseiten unterteilt. Das ist nützlich, wenn in Ihrer interaktiven Anwendung jeweils eine Seite mit Ergebnissen angezeigt wird.

Weitere Informationen zum Paging im Vergleich zum Streaming

Anfrage stellen

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

• 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 werden in der Anfrage auch methodenspezifische Felder unterstützt:

• SearchGoogleAdsStreamRequest (nur SearchStream):
  • Ein optionales summary_row_setting, um eine Zusammenfassungszeile mit aggregierten Messwerten anzufordern
• SearchGoogleAdsRequest (nur Search):
  • Ein optionales page_token zum Abrufen des nächsten Batches von Ergebnissen bei Verwendung von Paging (page_size ist auf 10.000 Zeilen festgelegt; wenn page_size in der Anfrage festgelegt wird,wird der Fehler RequestError.PAGE_SIZE_NOT_SUPPORTED 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 Query Language finden Sie im Leitfaden zur Google Ads Query Language.

Antwort verarbeiten

Mit GoogleAdsService wird eine Liste von GoogleAdsRow-Objekten zurückgegeben (entweder in gestreamten SearchGoogleAdsStreamResponse-Batches oder in einer paginierten SearchGoogleAdsResponse>).

Jedes GoogleAdsRow steht für ein Objekt, das von einer Anfrage zurückgegeben wird, 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 die GoogleAdsRow-Objekte in der Antwort eingefügt.

Obwohl ein ad_group_criterion beispielsweise ein status-Attribut hat, wird das Feld status 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.

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

ENUM-Typen UNKNOWN und UNSPECIFIED

Ressourcen, die mit dem Enumerationswert UNKNOWN zurückgegeben werden, werden in dieser API-Version nicht vollständig unterstützt. UNSPECIFIED gibt an, dass ein Enumerationsfeld nicht festgelegt oder in der SELECT-Anweisung nicht angefordert wurde. Ressourcen mit dem Enum-Wert UNKNOWN können über andere Schnittstellen 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 ein Kampagnen- oder Anzeigentyp, der in der Benutzeroberfläche verfügbar ist, aber in der API-Version, die Sie abfragen, nicht unterstützt wird.

Hier einige wichtige Punkte:

• Eine Ressource mit dem Typ UNKNOWN kann in einer späteren API-Version 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 Aufzählungswert UNKNOWN in jeder Aufzählung in der API vorhanden ist. Ressourcen werden mit UNKNOWN zurückgegeben, damit Sie einen genauen Überblick über die Gesamtleistungsstatistiken Ihres Kontos erhalten.
• 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 über die API geändert werden.

Segmentierung

Die Antwort enthält ein GoogleAdsRow für jede Kombination aus:

• Instanz der in der FROM-Klausel angegebenen Hauptressource
• Wert jedes ausgewählten Felds segments

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

• 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.