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 von Objekten und zum Erstellen von Berichten, der zwei Suchmethoden bietet: SearchStream und Search. Suchanfragen werden in einem Abfragestring übergeben, der in der Search Ads 360-Abfragesprache geschrieben ist. Sie können Abfragen definieren, um:

• Bestimmte Attribute von Objekten abrufen
• Leistungsmesswerte für Objekte basierend auf einem Zeitraum abrufen.
• Objekte anhand ihrer Attribute sortieren
• Ergebnisse mit Bedingungen filtern, um anzugeben, welche Objekte zurückgegeben werden sollen
• Beschränken Sie die Anzahl der zurückgegebenen Objekte.

Bei beiden Suchmethoden werden alle Zeilen zurückgegeben, die Ihrer Anfrage entsprechen. 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 eine dauerhafte Verbindung zur Search Ads 360 Reporting API, unabhängig von der Berichtsgröße.

• Datenpakete werden sofort heruntergeladen und das gesamte Ergebnis wird in einem Datenpuffer zwischengespeichert.
• Ihr Code kann mit dem Lesen der gepufferten Daten beginnen, ohne auf das Ende des gesamten Streams warten zu müssen.

Search

Sendet mehrere paginierte Anfragen, um den gesamten Bericht herunterzuladen.

SearchStream bietet in der Regel eine bessere Leistung, da die Round-Trip-Netzwerkzeit für das Anfordern einzelner Seiten entfällt. Wir empfehlen,SearchStream für alle Berichte mit mehr als 10.000 Zeilen zu verwenden. Bei kleineren Berichten (<10.000 Zeilen) gibt es keinen signifikanten Leistungsunterschied zwischen den Methoden.

Die 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 seitenweise oder als Stream abgerufen werden.

Beispiel für eine Suchanfrage

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

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 stellen, müssen Sie einen customer_id- und einen query-String an die Schnittstelle SearchAds360Service.SearchStream oder SearchAds360Service.Search übergeben.

Die Anfrage besteht aus einem 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 ist ein vollständiges Beispiel für die Berichtsdefinition für searchStream, die in einer HTTP-POST-Anfrage enthalten ist:

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 Anfrage zurückgegeben wird. Jedes Objekt besteht aus einer Reihe von Attributen, die auf Grundlage 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 wird beispielsweise jedes SearchAds360Row-Objekt nur mit campaign.id, campaign.name und campaign.status gefü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 sind alle verfügbaren Segment- und Messwertfelder aufgeführt.

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

Zugeordnete Ressourcen

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

Im Abschnitt Attributed resources (Zugeordnete Ressourcen) werden die verfügbaren zugeordneten Ressourcen aufgeführt. Nicht alle Ressourcen haben zugeordnete Ressourcen.

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, Typ-URL und Einstellungen für Filterung, Auswahl, Sortierung und Wiederholung.

Spalte „Segmente“

Nicht alle Segmentfelder sind für eine bestimmte Ressource verfügbar.

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 ist mit vollständigen Details dazu verknüpft, einschließlich Beschreibung, Kategorie, Datentyp, Typ-URL und Einstellungen für Filterung, Auswahl, Sortierung und Wiederholung. Wenn Sie die Ressource in Ihrer FROM-Klausel verwenden, können Sie im 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 ist mit vollständigen Details dazu verknüpft, einschließlich Beschreibung, Kategorie, Datentyp, Typ-URL und Einstellungen für Filterung, Auswahl, Sortierung und Wiederholung. Wenn Sie die Ressource in Ihrer FROM-Klausel verwenden, filtern Sie mit dem Drop-down-Menü Ja/Nein Messwerte heraus, die nicht verfügbar sind.

Ressourcen segmentieren

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

Im Abschnitt Segmenting resources (Segmentierungsressourcen) werden die verfügbaren Segmentierungsressourcen aufgeführt. Nicht für alle Ressourcen sind Segmentierungsressourcen verfügbar.

Auswählbar mit

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

Die Seite segments enthält für jedes segments-Feld einen maximierbaren Bereich Auswählbar mit, in dem alle kompatiblen Ressourcenfelder, metrics-Felder und anderen segments-Felder aufgeführt sind, die Sie in Ihre SELECT-Klausel aufnehmen können.

Segmentierung

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

Wenn Sie beispielsweise segments.device in der folgenden Abfrage verwenden, wird ein Bericht mit einer Zeile für die impressions jedes Geräts für die in der FROM-Klausel angegebene Ressource generiert.

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

Die von SearchAds360Service.SearchStream zurückgegebenen Ergebnisse sehen 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"
      }
    },
    ...
  ]
}

Eine Liste der verfügbaren Segmentfelder finden Sie unter segments.

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 aus der Instanz der in der FROM-Klausel angegebenen Hauptressource 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, nicht aber 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 zuerst nach der in der FROM-Klausel angegebenen Ressource segmentiert. Messwerte werden nach dem Feld resource_name dieser Ressource segmentiert.

Diese Beispielabfrage gibt automatisch ad_group.resource_name zurück und verwendet sie implizit, 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 Datensegmente

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

Die folgenden Segmentfelder werden als Kernsegmentfelder für das Datum bezeichnet: segments.date, segments.week, segments.month, segments.quarter und segments.year.

Diese Beispielabfrage gibt die clicks-Messwerte für Kampagnen der letzten 30 Tage zurück.

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

Felder für Hauptdatumssegmente sind eine Ausnahme von der allgemeinen Regel, dass Sie kein Segmentfeld in Ihrer WHERE-Klausel verwenden können, es sei denn, Sie fügen das Feld auch in Ihre SELECT-Klausel ein. Weitere Informationen finden Sie unter Unzulässiges Filtern.

Regeln für Segmente mit selbst erhobenen Daten:

• Sie können ein wichtiges Datumsfeld in Ihrer WHERE-Klausel verwenden, ohne es in Ihre SELECT-Klausel aufzunehmen. Sie können das Feld auch in beide Klauseln einfügen.

  Mit dieser Beispielabfrage werden clicks-Messwerte nach Kampagnenname für den 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 wichtiges Datumsfeld in Ihre SELECT-Klausel aufnehmen, müssen Sie in Ihrer WHERE-Klausel ein endliches Datum oder einen endlichen Zeitraum angeben. Die in den SELECT- und WHERE-Klauseln angegebenen Felder müssen nicht übereinstimmen.

  Mit dieser Beispielabfrage werden clicks-Messwerte nach Kampagnennamen segmentiert nach Monat für alle Tage im 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 Zeiträume 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 Segmente mit Kerndaten, die einen Zeitraum erfordern (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'

Vordefinierte Zeiträume

Sie können auch die folgenden vordefinierten Datumsangaben und Zeiträume verwenden:

Beispiel:

WHERE segments.date DURING LAST_30_DAYS

Keine Messwerte

Wenn Sie eine Abfrage ausführen, können bei einigen Einheiten Messwerte mit dem Wert „0“ auftreten. Informationen zum Umgang mit Messwerten mit dem Wert „0“ in Ihren Abfragen

UNKNOWN-Enum-Typen

Wenn eine Ressource mit dem Enum-Datentyp UNKNOWN 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 Schnittstellen erstellt. Beispiel: Eine neue Kampagne oder Anzeige wird in der Search Ads 360-Benutzeroberfläche eingeführt, wird aber in der API-Version, die Sie abfragen, noch nicht unterstützt.

Sie können weiterhin Messwerte auswählen, wenn eine Ressource den Typ UNKNOWN hat. Beachten Sie jedoch Folgendes:

• Eine Ressource mit dem Typ UNKNOWN wird möglicherweise später unterstützt, es kann aber auch sein, dass sie auf unbestimmte Zeit UNKNOWN bleibt.

• 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 führen wir Ressourcen ein, damit Sie einen genauen Überblick über Ihr Konto haben. Die Ressource UNKNOWN wird möglicherweise angezeigt, weil in Ihrem Konto über andere Schnittstellen neue Aktivitäten stattgefunden haben oder weil eine Ressource nicht mehr offiziell unterstützt wird.

• UNKNOWN-Ressourcen können detaillierte Messwerte haben, die Sie abfragen können.

• UNKNOWN-Ressourcen sind in der Regel vollständig in der Search Ads 360-Benutzeroberfläche sichtbar.