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
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.
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 Ressourcecampaign
eine zugeordnete Ressource der Ressourcead_group
. Das bedeutet, dass Sie Felder wiecampaign.id
undcampaign.bidding_strategy_type
in Ihre Abfrage aufnehmen können, wenn Siead_group
in derFROM
-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 derselbenSELECT
-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 derFROM
-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 derselbenSELECT
-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 derFROM
-Klausel verwenden, können Sie nicht verfügbare Messwerte über das Drop-down-Menü Ja/Nein herausfiltern.
- 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 eincampaign
-Ressourcenfeld wiecampaign.name
auswählen undcampaign_budget
in derFROM
-Klausel verwenden, wirdcampaign.resource_name
automatisch zurückgegeben und segmentiert, dacampaign
eine Segmentierungsressourcecampaign_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 jedessegments
-Feld das Expandable-Feld Auswählbar mit. Darin sind alle kompatiblen Ressourcenfelder,metrics
-Felder und anderesegments
-Felder aufgeführt, die Sie in IhreSELECT
-Klausel aufnehmen können.
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
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
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 dieSELECT
-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, dasssegments.date
nicht in derSELECT
-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 derWHERE
-Klausel angeben. Die in den KlauselnSELECT
undWHERE
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'
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 ZeitUNKNOWN
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 RessourceUNKNOWN
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.