Suchberichte in der Search Ads 360 Reporting API erstellen

In den folgenden Abschnitten erfahren Sie, wie Sie Suchberichte in der Search Ads 360 Reporting API erstellen.

Suchdienst

Die Search Ads 360 Reporting API bietet einen speziellen Dienst für die Suche und Berichterstellung.

SearchAds360Service ist ein einheitlicher Dienst zum Abrufen und Erstellen von Objektberichten, der zwei Suchmethoden bietet: SearchStream und Search. Suchanfragen werden in einem Suchstring übergeben, der in der Search Ads 360-Abfragesprache geschrieben ist. Sie können Abfragen für Folgendes definieren:

• Bestimmte Attribute von Objekten abrufen.
• Leistungsmesswerte für Objekte nach einem bestimmten Zeitraum abrufen
• Objekte anhand ihrer Attribute sortieren
• Ergebnisse mit Bedingungen filtern, die angeben, welche Objekte zurückgegeben werden sollen
• Begrenzen Sie die Anzahl der zurückgegebenen Objekte.

Bei beiden Suchmethoden werden alle Zeilen zurückgegeben, die mit Ihrer Suchanfrage übereinstimmen. Wenn Sie beispielsweise campaign.id, campaign.name und metrics.clicks abrufen, gibt die API ein SearchAds360Row zurück, das ein Kampagnenobjekt mit den festgelegten Feldern id und name sowie ein metrics-Objekt mit dem festgelegten Feld clicks enthält.

Suchmethoden

SearchStream

Es wird eine einzelne Anfrage gesendet und unabhängig von der Berichtsgröße eine persistente Verbindung mit der Search Ads 360 Reporting API hergestellt.

• Der Download von Datenpaketen beginnt sofort und das gesamte Ergebnis wird in einem Datenpuffer zwischengespeichert.
• Ihr Code kann mit dem Lesen der zwischengespeicherten Daten beginnen, ohne auf das Ende des gesamten Streams warten zu müssen.

Search

Es werden mehrere paginated-Anfragen gesendet, um den gesamten Bericht herunterzuladen.

SearchStream bietet in der Regel eine bessere Leistung, da die Netzwerklaufzeit für die Anfrage einzelner Seiten entfällt. Wir empfehlen die Verwendung von SearchStream für alle Berichte mit mehr als 10.000 Zeilen. Bei kleineren Berichten (weniger als 10.000 Zeilen) gibt es keinen signifikanten Leistungsunterschied zwischen den Methoden.

Die von Ihnen verwendete Methode hat keine Auswirkungen auf Ihre API-Kontingente und ‑Limits: Eine einzelne Abfrage oder ein einzelner Bericht wird als ein Vorgang gezählt, unabhängig davon, ob die Ergebnisse gepuffert oder gestreamt werden.

Beispiel für eine Suchanfrage

In dieser Beispielabfrage werden Leistungsdaten für ein Konto für die letzten 30 Tage nach Kampagne und nach Gerät segmentiert zurückgegeben:

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Hinweis :In der Search Ads 360-Abfragesprache finden Sie detaillierte Informationen zur Verwendung der einzelnen Klauseln der Suchanfrage.

Anfrage stellen

Um eine Anfrage zu senden, müssen Sie der SearchAds360Service.SearchStream- oder SearchAds360Service.Search-Benutzeroberfläche einen customer_id- und einen query-String übergeben.

Hinweis: In den folgenden Beispielen wird die zugrunde liegende HTTP-/JSON-Anfrage angezeigt. Damit werden die Konzepte veranschaulicht. Wir empfehlen, unsere Clientbibliotheken zu verwenden, die auf gRPC basieren, um Anfragen in Ihrer eigenen App zu senden.

Die Anfrage besteht aus einer HTTP-POST an den Search Ads 360 Reporting API-Server unter einer der folgenden URLs:

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

Hier ein vollständiges Beispiel für die Berichtsdefinition für searchStream in einer HTTP-POST-Anfrage:

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

Antwort verarbeiten

SearchAds360Service gibt eine Liste von SearchAds360Row-Objekten zurück.

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

Mit der folgenden Abfrage werden beispielsweise jedes SearchAds360Row-Objekt nur mit campaign.id, campaign.name und campaign.status ausgefüllt. Andere Attribute wie campaign.engine_id oder campaign.bidding_strategy_type werden weggelassen.

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

Referenzdokumentation

Der Abschnitt Referenz enthält alle Informationen, die Sie für die korrekte Verwendung der einzelnen Artefakte benötigen. Für jede Ressource gibt es eine Seite, z. B. ad_group und campaign. Auf den Seiten segments und metrics sind alle verfügbaren Segment- und Messwertfelder aufgeführt.

Einige Ressourcen, Segmente und Messwerte sind nicht kompatibel und können nicht zusammen verwendet werden. Andere sind vollständig kompatibel und ergänzen sich. Jede Ressourcenseite enthält unter anderem die folgenden Informationen (sofern verfügbar und angemessen):

Zugewiesene Ressourcen

Bei einigen Ressourcen haben Sie möglicherweise die Möglichkeit, verknüpfte Ressourcen implizit zusammenzuführen, indem Sie ihre Felder zusammen mit den Feldern der Ressource in Ihrer FROM-Klausel auswählen. Die Ressource campaign ist beispielsweise eine zugeordnete Ressource der Ressource ad_group. Das bedeutet, dass Sie Felder wie campaign.id und campaign.bidding_strategy_type in Ihre Abfrage aufnehmen können, wenn Sie ad_group in Ihrer FROM-Klausel verwenden.

Im Abschnitt Zugewiesene Ressourcen sind die verfügbaren zugewiesenen Ressourcen aufgeführt. Nicht allen Ressourcen sind Ressourcen zugeordnet.

Spalte „Ressourcenfelder“

Alle Felder der Ressource sind in der Spalte Ressourcenfelder enthalten. Jedes Ressourcenfeld enthält einen Link zu weiteren Details zum Feld, einschließlich Beschreibung, Kategorie, Datentyp, URL des Typs sowie den Einstellungen „Filterbar“, „Auswählbar“, „Sortierbar“ und „Wiederholbar“.

Spalte „Segmente“

Nicht alle Segmentfelder können für eine bestimmte Ressource ausgewählt werden.

In der Spalte Segmente sind die segments-Felder aufgeführt, die Sie in derselben SELECT-Klausel wie die Felder der Ressource verwenden können. Jedes Feld enthält einen Link zu vollständigen Details zum Feld, einschließlich Beschreibung, Kategorie, Datentyp, Typ-URL und Einstellung für filterbar, auswählbar, sortierbar und wiederholbar. Wenn Sie die Ressource in Ihrer FROM-Klausel verwenden, können Sie über das Drop-down-Menü Ja/Nein Segmente herausfiltern, die nicht verfügbar sind.

Messwertspalte

Nicht alle Messwertfelder sind für eine bestimmte Ressource auswählbar.

In der Spalte Messwerte sind die metrics-Felder aufgeführt, die Sie in derselben SELECT-Klausel wie die Felder der Ressource verwenden können. Jedes Feld enthält einen Link zu vollständigen Details zum Feld, einschließlich Beschreibung, Kategorie, Datentyp, Typ-URL und Einstellung für filterbar, auswählbar, sortierbar und wiederholbar. Wenn Sie die Ressource in Ihrer FROM-Klausel verwenden, können Sie im Drop-down-Menü Ja/Nein Messwerte herausfiltern, die nicht verfügbar sind.

Hinweis :Wenn Sie währungsbezogene Messwerte (z.B. „cost_micros“) für ein bestimmtes Datum oder einen bestimmten Zeitraum abrufen möchten, müssen Sie „segments.date“ in die SELECT-Klausel aufnehmen.

Ressourcen segmentieren

Einige Ressourcen haben segmentierende Ressourcenfelder, die Sie auswählen können, wenn sich die Ressource in Ihrer FROM-Klausel befindet. Wenn Sie beispielsweise ein campaign-Ressourcenfeld wie campaign.name auswählen und campaign_budget in Ihrer FROM-Klausel verwenden, wird campaign.resource_name automatisch zurückgegeben und für die Segmentierung verwendet, da campaign eine segmentierende Ressource von campaign_budget ist.

Im Abschnitt Segmentierungsressourcen sind die verfügbaren Segmentierungsressourcen aufgeführt. Nicht alle Ressourcen haben Segmentierungsressourcen.

Auswählbar mit

Einige segments-Felder sind mit anderen Ressourcen, Segmenten und Messwerten nicht kompatibel.

Auf der Seite segments können Sie für jedes segments-Feld die Option Mit maximieren. Daraufhin werden alle kompatiblen Ressourcenfelder, metrics-Felder und anderen segments-Felder aufgelistet, die Sie in Ihre SELECT-Klausel aufnehmen können.

Hinweis: Weitere Informationen zur Verwendung der einzelnen Klauseln einer Abfrage finden Sie unter Search Ads 360-Abfragesprache.

Segmentierung

Sie können Ihre Suchergebnisse segmentieren, indem Sie der SELECT-Klausel Ihrer Abfrage ein segments.FIELD_NAME-Feld hinzufügen.

Wenn Sie beispielsweise segments.device in die folgende Abfrage einfügen, wird ein Bericht mit einer Zeile für die impressions jedes Geräts für die in der FROM-Klausel angegebenen Ressourcen erstellt.

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

Die von SearchAds360Service.SearchStream zurückgegebenen Ergebnisse sehen in etwa so aus:

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

Unter segments finden Sie eine Liste der verfügbaren Segmentfelder.

Mehrere Segmente

Achtung: Die Anzahl der Zeilen kann sich mit jedem zusätzlichen segments-Feld, das Sie der Abfrage hinzufügen, exponentiell erhöhen.

Sie können in der SELECT-Klausel Ihrer Abfrage mehrere Segmente angeben. Die Antwort enthält ein SearchAds360Row-Objekt für jede Kombination aus der Instanz der Hauptressource, die in der FROM-Klausel angegeben ist, und dem Wert jedes ausgewählten segment-Felds.

Die folgende Abfrage gibt beispielsweise eine Zeile für jede Kombination aus campaign, segments.ad_network_type und segments.date zurück.

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

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

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

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

Implizite Segmentierung

Jeder Bericht wird anfangs nach der in der FROM-Klausel angegebenen Ressource segmentiert. Messwerte werden nach dem Feld resource_name dieser Ressource segmentiert.

Hinweis: Das Feld resource_name der Ressource in der FROM-Klausel wird immer zurückgegeben, auch wenn es nicht in der SELECT-Klausel angegeben ist. Weitere Informationen finden Sie unter resource_name-Feld.

In dieser Beispielabfrage wird ad_group.resource_name automatisch zurückgegeben und implizit verwendet, um Messwerte auf ad_group-Ebene zu segmentieren.

SELECT metrics.impressions
FROM ad_group

Der zurückgegebene JSON-String sieht in etwa so aus:

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

Wichtige Zeiträume

Sie können in der WHERE-Klausel grundlegende Datumssegmente verwenden, um ein Datum oder einen Zeitraum anzugeben.

Die folgenden Segmentfelder werden als Datensegmente für die Hauptangaben bezeichnet: segments.date, segments.week, segments.month, segments.quarter und segments.year.

Mit dieser Beispielabfrage werden clicks-Messwerte für Kampagnen der letzten 30 Tage zurückgegeben.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Felder für grundlegende Datumssegmente sind eine Ausnahme von der allgemeinen Regel, dass Sie ein Segmentfeld in der WHERE-Klausel nur verwenden können, wenn Sie das Feld auch in die SELECT-Klausel aufnehmen. Weitere Informationen finden Sie unter Unzulässige Filterung.

Wichtige Regeln für Datumssegmente:

• Sie können ein Hauptdatumsfeld in der WHERE-Klausel verwenden, ohne es in die SELECT-Klausel aufzunehmen. Sie können das Feld auch in beiden Klauseln angeben.

  In dieser Beispielabfrage werden clicks-Messwerte nach Kampagnenname im angegebenen Zeitraum zurückgegeben. Beachten Sie, dass segments.date nicht in der SELECT-Klausel enthalten ist.

  SELECT
      campaign.name,
      metrics.clicks
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

• Wenn Sie ein Hauptdatumsfeld in die SELECT-Klausel aufnehmen, müssen Sie in der WHERE-Klausel ein bestimmtes Datum oder einen bestimmten Zeitraum angeben. Die in den SELECT- und WHERE-Klauseln angegebenen Felder müssen nicht übereinstimmen.

  Mit dieser Beispielabfrage werden clicks-Messwerte nach Kampagnenname und nach Monat für alle Tage im angegebenen Zeitraum zurückgegeben.

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

ISO 8601-Datumsangaben

Sie können das Format YYYY-MM-DD (ISO 8601) verwenden, um Datumsangaben und Datumsbereiche anzugeben, z. B.:

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

Für grundlegende Datumssegmente, für die ein Zeitraum erforderlich ist (segments.week, segments.month, segments.quarter), können Sie den Operator = mit dem ersten Tag des Zeitraums verwenden, z. B.:

WHERE segments.month = '2022-06-01'

Hinweis: Wenn Sie ein Datum angeben, das nicht der erste Tag eines Zeitraums ist, erhalten Sie die Fehlermeldung MISALIGNED_DATE_FOR_FILTER.

Vordefinierte Datumsangaben

Sie können auch die folgenden vordefinierten Datumsangaben und -bereiche verwenden:

Vordefinierte Datumsangaben
TODAY	nur heute
YESTERDAY	nur gestern
LAST_7_DAYS	Die letzten 7 Tage ohne den heutigen Tag.
LAST_BUSINESS_WEEK	Vorherige 5-Tage-Arbeitswoche (Montag bis Freitag)
THIS_MONTH	alle Tage im aktuellen Monat
LAST_MONTH	alle Tage im vorherigen Monat
LAST_14_DAYS	Die letzten 14 Tage (heutigen Tag ausschließen)
LAST_30_DAYS	Letzte 30 Tage (heutigen Tag ausschließen)
THIS_WEEK_SUN_TODAY	Zeitraum zwischen dem Vorwochen-Sonntag und dem aktuellen Tag.
THIS_WEEK_MON_TODAY	Zeitraum zwischen dem Vorwochen-Montag und dem aktuellen Tag.
LAST_WEEK_SUN_SAT	7-tägiger Zeitraum, beginnend mit dem vorherigen Sonntag.
LAST_WEEK_MON_SUN	7-Tage-Zeitraum ab dem vorherigen Montag.

Beispiel:

WHERE segments.date DURING LAST_30_DAYS

Null-Messwerte

Wenn Sie eine Abfrage ausführen, sehen Sie möglicherweise für einige Entitäten Messwerte mit dem Wert „0“. Weitere Informationen zum Umgang mit Null-Messwerten in Abfragen

UNBEKANNTE ENUM-TYPEN

Wenn eine Ressource mit dem UNKNOWN-Enum-Datentyp zurückgegeben wird, bedeutet das, dass der Typ in der API-Version nicht vollständig unterstützt wird. Diese Ressourcen wurden möglicherweise über andere Oberflächen erstellt. Beispiel: Eine neue Kampagne oder Anzeige wird in der Search Ads 360-Benutzeroberfläche eingeführt, wird aber von der API-Version, die Sie abfragen, noch nicht unterstützt.

Sie können Messwerte auch für Ressourcen vom Typ UNKNOWN auswählen. Beachten Sie dabei Folgendes:

• Eine Ressource mit dem Typ UNKNOWN wird möglicherweise später unterstützt, kann aber unbegrenzt als UNKNOWN angezeigt werden.
• Neue Objekte vom Typ UNKNOWN können jederzeit erscheinen. Diese Objekte sind abwärtskompatibel, da der Aufzählungswert bereits verfügbar ist. Wir führen mit dieser Änderung Ressourcen ein, sobald sie verfügbar sind, damit Sie einen genauen Überblick über Ihr Konto haben. Die UNKNOWN-Ressource kann aufgrund neuer Aktivitäten in Ihrem Konto über andere Oberflächen oder aufgrund der Einstellung einer Ressource angezeigt werden.
• UNKNOWN-Ressourcen können detaillierte Messwerte enthalten, die Sie abfragen können.
• UNKNOWN-Ressourcen sind in der Search Ads 360-Benutzeroberfläche normalerweise vollständig sichtbar.