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
• Ordnen Sie Objekte anhand ihrer Attribute.
• 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

Sendet eine einzelne Anfrage und initiiert unabhängig von der Berichtsgröße eine persistente Verbindung zur Search Ads 360 Reporting API.

• 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 aufeinanderfolgende Anfragen zum Herunterladen des gesamten Berichts gesendet.

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

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.

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 basierend auf den Feldern ausgefüllt werden, die in der SELECT-Klausel der Abfrage angefordert 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 ausgelassen.

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 werden alle verfügbaren Segmente und Messwertfelder aufgelistet.

Einige Ressourcen, Segmente und Messwerte sind nicht kompatibel und können nicht zusammen verwendet werden, während andere vollständig kompatibel sind und sich ergänzen. 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 der FROM-Klausel verwenden, verwenden Sie das Drop-down-Menü Ja/Nein, um nicht verfügbare Messwerte herauszufiltern.

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 die SELECT-Klausel aufnehmen können.

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

Sie können in der SELECT-Klausel Ihrer Abfrage mehrere Segmente angeben. Die Antwort enthält ein SearchAds360Row-Objekt für jede Kombination der Instanz der Hauptressource, die in der FROM-Klausel angegeben ist, und den 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 und 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.

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"
      }
    }
  ]
}

Zentrale Datumssegmente

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 Hauptachsen bezeichnet: segments.date, segments.week, segments.month, segments.quarter und segments.year.

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

  Bei dieser Beispielabfrage werden während des Zeitraums clicks-Messwerte nach Kampagnenname 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.

  Diese Beispielabfrage gibt clicks-Messwerte nach Kampagnenname zurück, segmentiert nach Monat für alle Tage im Zeitraum.

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

ISO 8601-Daten

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 zentrale Datumssegmente, die einen Zeitraum erfordern (segments.week, segments.month, segments.quarter), können Sie den Operator = mit dem ersten Tag des Zeitraums verwenden. Beispiel:

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

Vordefinierte Datumsangaben

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

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, bleibt aber möglicherweise auf unbestimmte Zeit UNKNOWN.
• 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 Ressource UNKNOWN kann aufgrund neuer Aktivitäten in Ihrem Konto über andere Benutzeroberflächen angezeigt werden oder weil eine Ressource nicht mehr formell unterstützt wird.
• An UNKNOWN-Ressourcen sind möglicherweise detaillierte Messwerte angehängt, die Sie abfragen können.
• UNKNOWN-Ressourcen sind in der Search Ads 360-Benutzeroberfläche normalerweise vollständig sichtbar.