Suchberichte in der Search Ads 360 Reporting API erstellen

In den folgenden Abschnitten erfahren Sie, wie Sie Suchberichte in Suchanzeigen erstellen. 360 Reporting API.

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 mit zwei Suchmethoden: SearchStream und Search. Suchanfragen sind Die Daten werden in einem Abfragestring übergeben, der in der Search Ads 360 Query Language geschrieben wurde. Sie können Abfragen für Folgendes definieren:

  • Spezifische Attribute von Objekten abrufen
  • Leistungsmesswerte für Objekte basierend auf einem Zeitraum abrufen
  • Ordnen Sie Objekte anhand ihrer Attribute.
  • 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 zum Beispiel campaign.id, campaign.name und metrics.clicks abrufen, gibt die API eine SearchAds360Row, die ein Kampagnenobjekt mit den Feldern id und name enthält und ein metrics-Objekt mit dem festgelegten Feld clicks.

Suchmethoden

SearchStream

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

  • Der Download von Datenpaketen beginnt sofort mit dem gesamten Ergebnis Datenpuffer im Cache gespeichert werden.
  • Ihr Code kann mit dem Lesen der zwischengespeicherten Daten beginnen, ohne auf bis zum Ende des Streams.
Search

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

SearchStream bietet in der Regel eine bessere Leistung, da hier die Roundtrip-Netzwerkzeit, die für die Anforderung einzelner Seiten erforderlich ist. Wir empfehlen die Verwendung von SearchStream für alle Berichte mit mehr als 10.000 Zeilen. Es gibt keine signifikante Leistungsunterschied zwischen den Methoden für kleinere Berichte (weniger als 10.000 Zeilen).

Die von Ihnen verwendete Methode hat keinen Einfluss 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 per Pager oder Streaming dargestellt werden.

Beispiel für eine Suchanfrage

Diese Beispielabfrage gibt Leistungsdaten für ein Konto für die letzten 30 Tage zurück nach Kampagne, 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 senden, müssen Sie einen customer_id- und einen query-String übergeben. an SearchAds360Service.SearchStream oder SearchAds360Service.Search .

Die Anfrage besteht aus einem HTTP-POST an die Search Ads 360 Reporting API. des Servers unter einer der folgenden URLs abrufen:

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

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

Hier sehen Sie ein vollständiges Beispiel für die Berichtsdefinition von 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 Objekt, das von der Abfrage zurückgegeben wird. Jedes Objekt besteht aus einer Reihe von Attributen, die basierend auf den angeforderten Feldern ausgefüllt werden. in der SELECT-Klausel der Abfrage ein. Nicht in SELECT enthaltene Attribute werden in der Antwort nicht in die Objekte eingefügt.

Bei der folgenden Abfrage wird beispielsweise jedes SearchAds360Row-Objekt nur mit dem Parameter campaign.id, campaign.name und campaign.status. Andere Attribute wie campaign.engine_id oder campaign.bidding_strategy_type werden weggelassen.

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

Referenzdokumentation

Abschnitt Referenz enthält alle Informationen, die Sie benötigen, um jedes Artefakt richtig zu verwenden. Es gibt eine Seite für jede Ressource, z. B. ad_group und campaign Die Seiten segments und metrics alle verfügbaren Segmente und Messwertfelder auf.

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

Zugeordnete Ressourcen

Bei einigen Ressourcen können Sie ggf. zugehörige indem Sie ihre Felder zusammen mit den Feldern der Ressource in Ihre FROM-Klausel. Die Ressource campaign ist beispielsweise ein zugeordnete Ressource der ad_group-Ressource. Das bedeutet, dass Sie Felder wie campaign.id und campaign.bidding_strategy_type in Ihr zurück, wenn ad_group in Ihrer FROM-Klausel verwendet wird.

Im Abschnitt Zugeordnete Ressourcen sind die verfügbaren zugeordneten Ressourcen aufgeführt. Nicht haben alle Ressourcen zugeordnete Ressourcen.

Spalte „Ressourcenfelder“

Alle Felder der Ressource sind in der Spalte Ressourcenfelder enthalten. Jedes Ressourcenfeld ist mit weiteren Details verlinkt, Beschreibung, Kategorie, Datentyp, Typ URL, filterbar, selectable, wiederholt werden können.

Spalte „Segmente“

Mit einer bestimmten Ressource können nicht alle Segmentfelder ausgewählt werden.

In der Spalte Segmente sind die segments-Felder aufgeführt, die Sie in den SELECT-Klausel wie die Felder der Ressource. Jedes Feld enthält einen Link zur vollständigen Details zum Feld, einschließlich Beschreibung, Kategorie, Datentyp und Typ URL, filterbar, auswählbar, sortierbar und wiederholt. Wenn Sie Wenn Sie die Ressource in der FROM-Klausel verwenden, können Sie das Drop-down-Menü Ja/Nein verwenden. um nicht verfügbare Segmente herauszufiltern.

Spalte „Messwerte“

Bei einer bestimmten Ressource können nicht alle Messwertfelder ausgewählt werden.

In der Spalte Messwerte sind die metrics-Felder aufgeführt, die du in den SELECT-Klausel wie die Felder der Ressource. Jedes Feld enthält einen Link zur vollständigen Details zum Feld, einschließlich Beschreibung, Kategorie, Datentyp und Typ URL, filterbar, auswählbar, sortierbar und wiederholt. Wenn Sie indem Sie die Ressource in der FROM-Klausel verwenden, nutzen Sie das Drop-down-Menü Ja/Nein, um und filtern Sie Messwerte heraus, die nicht verfügbar sind.

Ressourcen segmentieren

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

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

Auswählbar mit

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

Die Seite segments enthält ein erweiterbares Feld Auswählbar mit für jedes segments-Feld, das Listet alle kompatiblen Ressourcenfelder, metrics-Felder und andere segments auf die Sie in die SELECT-Klausel aufnehmen können.

Segmentierung

Sie können die Suchergebnisse segmentieren, indem Sie segments.FIELD_NAME der SELECT-Klausel Ihrer Abfrage hinzu.

Beispiel: segments.device im Abfrage unten führt zu einem Bericht mit einer Zeile für die impressions von jedem Gerät 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: wie diesen JSON-String:

{
  "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 Liste verfügbarer Segmentfelder, die Sie verwenden können.

Mehrere Segmente

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

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

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

Beachten Sie, dass die Ergebnisse implizit nach jeder Instanz des Haupt- Ressource, 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 Kampagne unterschiedlichen Wert des Felds campaign.status.

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

Implizite Segmentierung

Jeder Bericht ist anfangs nach der Ressource segmentiert, die in den FROM angegeben ist. Klausel. Messwerte sind nach dem Feld resource_name dieser Ressource segmentiert

Diese Beispielabfrage gibt automatisch ad_group.resource_name und implizit zurück werden damit Messwerte auf ad_group-Ebene segmentiert.

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 zentrale Datumssegmente in der WHERE-Klausel verwenden, um ein Datum anzugeben. oder einen bestimmten Zeitraum.

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

Diese Beispielabfrage gibt clicks-Kampagnenmesswerte 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

Die Felder für grundlegende Datumssegmente stellen eine Ausnahme von der allgemeinen Regel dar, bei der Sie kann in Ihrer WHERE-Klausel kein Segmentfeld verwenden, es sei denn, Sie fügen auch das SELECT-Klausel angegeben werden. Weitere Informationen finden Sie unter Unzulässiges Filtern. Informationen.

Grundlegende Regeln für Datumssegmente:

  • Sie können ein zentrales Datumsfeld in Ihrer WHERE-Klausel verwenden, ohne es in die SELECT-Klausel angegeben werden. Sie können das Feld auch in beide Klauseln aufnehmen.

    Diese Beispielabfrage gibt während des Datums clicks-Messwerte nach Kampagnenname zurück Bereich. segments.date ist nicht in der SELECT-Klausel enthalten.

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

  • Wenn Sie ein zentrales Datumsfeld in die SELECT-Klausel aufnehmen, müssen Sie ein ein endliches Datum oder einen Zeitraum in der WHERE-Klausel. Die in der Spalte Die SELECT- und WHERE-Klauseln 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

Du kannst das Format YYYY-MM-DD (ISO 8601) verwenden, um Daten 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'

Für zentrale Datumssegmente, die einen bestimmten Zeitraum erfordern (segments.week, segments.month, segments.quarter) können Sie den =-Operator mit der ersten Tag des Zeitraums, zum Beispiel:

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

Vordefinierter Zeitraum

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

Vordefinierter Zeitraum
TODAY nur heute
YESTERDAY nur gestern
LAST_7_DAYS Vorherige 7 Tage ohne heute.
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 Vorherige 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 Zeitraum von 7 Tagen ab dem letzten Sonntag.
LAST_WEEK_MON_SUN Zeitraum von 7 Tagen ab dem letzten Montag.

Beispiel:

WHERE segments.date DURING LAST_30_DAYS

Keine Messwerte

Wenn Sie eine Abfrage ausführen, können Messwerte mit dem Wert Null für einige Entitäten. Weitere Informationen zum Umgang mit Messwerten ohne Werte in Abfragen

UNKNOWN enum-Typen

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

Sie können weiterhin Messwerte auswählen, wenn eine Ressource vom Typ UNKNOWN ist, aber Sie beachten Sie bitte Folgendes:

  • Eine Ressource mit dem Typ UNKNOWN wird möglicherweise später unterstützt, bleibt aber erhalten UNKNOWN auf unbestimmte Zeit.
  • Neue Objekte des Typs UNKNOWN können jederzeit auftauchen. Diese Objekte sind abwärtskompatibel, da der enum-Wert bereits verfügbar ist. Wir stellen vor: mit dieser Änderung, sobald sie verfügbar sind, damit Sie ein genaues Ansicht Ihres Kontos. Die Ressource UNKNOWN kann aufgrund von neuen Aktivitäten in Ihrem Konto über andere Benutzeroberflächen oder weil eine Ressource nicht mehr formell unterstützt.
  • UNKNOWN Ressourcen sind möglicherweise detaillierte Messwerte angehängt, die Sie Abfrage.
  • UNKNOWN-Ressourcen sind normalerweise vollständig in der Search Ads 360-Benutzeroberfläche sichtbar.