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 Melden von Objekten, der zwei Suchmethoden bietet: SearchStream und Search. Suchanfragen werden in einem Abfragestring übergeben, der in Search Ads 360 Query Language geschrieben ist. Sie können Abfragen für Folgendes definieren:

• Bestimmte Attribute von Objekten abrufen
• Leistungsmesswerte für Objekte basierend auf einem Zeitraum abrufen
• Objekte anhand ihrer Attribute anordnen.
• Ergebnisse mithilfe von 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 Ihrer Abfrage entsprechen. Wenn Sie beispielsweise campaign.id, campaign.name und metrics.clicks abrufen, gibt die API ein SearchAds360Row-Objekt zurück, das ein Kampagnenobjekt mit festgelegten Feldern id und name sowie ein metrics-Objekt mit festgelegtem Feld clicks enthält.

Suchmethoden

SearchStream

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

• Der Download von Datenpaketen beginnt sofort, wobei das gesamte Ergebnis in einem Datenpuffer zwischengespeichert wird.
• Ihr Code kann mit dem Lesen der zwischengespeicherten Daten beginnen, ohne warten zu müssen, bis der gesamte Stream beendet ist.

Search

Es werden mehrere paginierte Anfragen zum Herunterladen des gesamten Berichts gesendet.

SearchStream bietet in der Regel eine bessere Leistung, da die Netzwerkzeit für das Anfordern einzelner Seiten entfällt. Wir empfehlen die Verwendung von SearchStream für alle Berichte mit mehr als 10.000 Zeilen. Es gibt keinen nennenswerten Leistungsunterschied zwischen den Methoden für kleinere Berichte (weniger als 10.000 Zeilen).

Die von Ihnen verwendete Methode hat keinen Einfluss auf die Kontingente und Limits Ihrer API: Eine einzelne Abfrage oder ein einzelner Bericht wird als ein Vorgang gezählt, unabhängig davon, ob die Ergebnisse aus Seiten aufgerufen oder gestreamt werden.

Beispiel für eine Suchanfrage

Diese Beispielabfrage gibt Leistungsdaten für ein Konto für die letzten 30 Tage nach Kampagne aufgeschlüsselt nach Gerät zurück:

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 Search Ads 360 Query Language finden Sie detaillierte Informationen zur Verwendung der einzelnen Klauseln der Suchanfrage.

Anfrage stellen

Um eine Anfrage zu senden, müssen Sie einen customer_id- und einen query-String an die Schnittstelle SearchAds360Service.SearchStream oder SearchAds360Service.Search übergeben.

Hinweis: Die folgenden Beispiele zeigen die zugrunde liegende HTTP/JSON-Anfrage. Damit werden die Konzepte veranschaulicht. Wir empfehlen, unsere auf gRPC basierenden Clientbibliotheken zu verwenden, um Anfragen in Ihrer eigenen App zu senden.

Die Anfrage besteht aus einem HTTP-POST an den Server der Search Ads 360 Reporting API 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 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.

Jeder SearchAds360Row steht für ein von der Abfrage zurückgegebenes Objekt. Jedes Objekt besteht aus einer Reihe von Attributen, die anhand der Felder ausgefüllt werden, die in der SELECT-Klausel der Abfrage angefordert werden. Attribute, die nicht in der SELECT-Klausel enthalten sind, werden in die Objekte der Antwort nicht ausgefüllt.

Beispiel: Die folgende Abfrage füllt jedes SearchAds360Row-Objekt nur mit campaign.id, campaign.name und campaign.status. 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 zur ordnungsgemäßen 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 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 gegenseitig. Jede Ressourcenseite enthält unter anderem die folgenden Informationen (falls vorhanden und angebracht):

Zugeordnete Ressourcen

Bei einigen Ressourcen haben Sie möglicherweise die Möglichkeit, verwandte Ressourcen implizit zu verknüpfen, indem Sie in der FROM-Klausel die zugehörigen Felder zusammen mit den Feldern der Ressource auswählen. Beispielsweise ist die Ressource campaign 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 der FROM-Klausel verwenden.

Im Abschnitt Zugeordnete Ressourcen werden die verfügbaren zugeordneten Ressourcen aufgelistet. Nicht allen Ressourcen sind Ressourcen zugeordnet.

Spalte „Ressourcenfelder“

Alle Felder der Ressource sind in der Spalte Ressourcenfelder enthalten. Jedes Ressourcenfeld ist mit weiteren Details zum Feld verknüpft, einschließlich Beschreibung, Kategorie, Datentyp, Typ-URL und Einstellung „Filterbar“, „Auswählbar“, „sortierbar“ und „Wiederholt“.

Spalte „Segmente“

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

In der Spalte Segmente werden 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 „Filterbar“, „Auswählbar“, „Sortable“ und „Wiederholt“. Wenn Sie die Ressource in der FROM-Klausel verwenden, können Sie nicht verfügbare Segmente über das Drop-down-Menü Ja/Nein herausfiltern.

Spalte „Messwerte“

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

In der Spalte Messwerte werden 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 „Filterbar“, „Auswählbar“, „Sortable“ und „Wiederholt“. Wenn Sie die Ressource in der FROM-Klausel verwenden, können Sie nicht verfügbare Messwerte über das Drop-down-Menü Ja/Nein herausfiltern.

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

Ressourcen segmentieren

Einige Ressourcen haben segmentierte Ressourcenfelder, die Sie auswählen können, wenn sich die Ressource in der FROM-Klausel befindet. Wenn Sie beispielsweise ein campaign-Ressourcenfeld wie campaign.name auswählen und campaign_budget in der FROM-Klausel verwenden, wird campaign.resource_name automatisch zurückgegeben und segmentiert, da campaign eine Segmentierungsressource campaign_budget ist.

Im Abschnitt Ressourcen segmentieren werden die verfügbaren Segmentierungsressourcen aufgelistet. Nicht alle Ressourcen haben segmentierte Ressourcen.

Auswählbar mit

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

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

Hinweis: Informationen zur Verwendung der einzelnen Klauseln einer Abfrage finden Sie unter Search Ads 360 Query Language.

Segmentierung

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

Zum Beispiel führt segments.device in der folgenden Abfrage zu einem Bericht mit einer Zeile für den impressions jedes Geräts für die in der FROM-Klausel angegebene Ressource.

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, die Sie verwenden können.

Mehrere Segmente

Achtung: Die Anzahl der Zeilen kann für jedes zusätzliche segments-Feld, das Sie der Abfrage hinzufügen, exponentiell zunehmen.

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 in der FROM-Klausel angegebenen Hauptressource 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

Beachten Sie, dass die Ergebnisse implizit nach jeder Instanz der Hauptressource segmentiert werden, jedoch 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 zuerst nach der in der FROM-Klausel angegebenen Ressource segmentiert. Messwerte sind 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 Feld resource_name.

Diese Beispielabfrage gibt automatisch ad_group.resource_name zurück und verwendet es 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"
      }
    }
  ]
}

Kerndatensegmente

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

Die folgenden Segmentfelder werden als Hauptdatumssegmente bezeichnet: segments.date, segments.week, segments.month, segments.quarter und segments.year.

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

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

Grundlegende Datumssegmentfelder sind eine Ausnahme von der allgemeinen Regel, dass Sie kein Segmentfeld in der WHERE-Klausel verwenden können, es sei denn, Sie schließen dieses Feld auch in die SELECT-Klausel ein. Weitere Informationen finden Sie unter Unzulässige Filter.

Zentrale Regeln für Datumssegmente:

• Sie können ein grundlegendes Datumsfeld in der WHERE-Klausel verwenden, ohne es in die SELECT-Klausel aufzunehmen. Sie können das Feld auch in beide Klauseln aufnehmen.

  Diese Beispielabfrage gibt clicks-Messwerte nach Kampagnenname während des Zeitraums zurück. 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 ein endliches Datum oder einen Datumsbereich in der WHERE-Klausel angeben. Die in den Klauseln SELECT und WHERE angegebenen Felder müssen nicht übereinstimmen.

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

  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 Zeiträume anzugeben. Beispiel:

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

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

Bei Kerndatumssegmenten, 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'

Hinweis: Wenn Sie ein Datum angeben, das nicht der erste Tag eines Zeitraums ist, wird der Fehler MISALIGNED_DATE_FOR_FILTER angezeigt.

Vordefinierter Zeitraum

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

Vordefinierter Zeitraum
TODAY	nur heute
YESTERDAY	nur gestern
LAST_7_DAYS	Letzte 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	Vorherige 14 Tage ohne heute.
LAST_30_DAYS	Letzte 30 Tage ohne heute.
THIS_WEEK_SUN_TODAY	Zeitraum zwischen dem letzten Sonntag und dem aktuellen Tag.
THIS_WEEK_MON_TODAY	Zeitraum zwischen dem letzten Montag und dem aktuellen Tag
LAST_WEEK_SUN_SAT	7-Tage-Zeitraum ab dem letzten 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, können Sie auf Messwerte mit dem Wert null für einige Entitäten stoßen. Weitere Informationen zum Umgang mit Nullmesswerten in Abfragen

UNBEKANNTE enum-Typen

Wenn eine Ressource mit dem enum-Datentyp UNKNOWN zurückgegeben wird, bedeutet dies, dass der Typ in der API-Version nicht vollständig unterstützt wird. Diese Ressourcen wurden möglicherweise über andere Benutzeroberflächen erstellt. Beispielsweise wird eine neue Kampagne oder Anzeige in die Search Ads 360-Benutzeroberfläche eingeführt, aber in der von Ihnen abgefragten API-Version 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, kann aber auf unbestimmte Zeit UNKNOWN bleiben.
• Neue Objekte vom Typ UNKNOWN können jederzeit angezeigt werden. Diese Objekte sind abwärtskompatibel, da der ENUM-Wert bereits verfügbar ist. Wir führen mit dieser Änderung neue Ressourcen ein, sobald sie verfügbar sind, damit Sie eine genaue Ansicht Ihres Kontos erhalten. Die Ressource UNKNOWN wird möglicherweise aufgrund neuer Aktivitäten in Ihrem Konto über andere Benutzeroberflächen oder daran angezeigt, dass eine Ressource nicht mehr unterstützt wird.
• UNKNOWN-Ressourcen können detaillierte Messwerte zugeordnet sein, die Sie abfragen können.
• UNKNOWN-Ressourcen sind in der Regel vollständig auf der Search Ads 360-Benutzeroberfläche sichtbar.