Leggi le sezioni seguenti per scoprire come creare report di ricerca nell'API Search Ads 360 Reporting.
Servizio di ricerca
L'API Search Ads 360 Reporting offre un servizio speciale per la ricerca e la generazione di report.
SearchAds360Service
è un servizio unificato di recupero degli oggetti e di generazione di report
che offre due metodi di ricerca: SearchStream
e Search
. Le ricerche vengono
passate in una stringa di query scritta nel Linguaggio di query di Search Ads 360. Puoi definire query per:
- Recuperare attributi specifici degli oggetti.
- Recupera le metriche sul rendimento per gli oggetti in base a un intervallo di date.
- Ordina gli oggetti in base ai loro attributi.
- Filtra i risultati utilizzando condizioni che specificano quali oggetti restituire
- Limita il numero di oggetti restituiti.
Entrambi i metodi di ricerca restituiscono tutte le righe corrispondenti alla query. Ad esempio, quando recuperi campaign.id
, campaign.name
e metrics.clicks
, l'API restituisce SearchAds360Row
contenente un oggetto campagna con i campi id
e name
impostati, nonché un oggetto metrics
con il relativo campo clicks
impostato.
Metodi di ricerca
SearchStream
Invia una singola richiesta e avvia una connessione permanente con l'API Search Ads 360 Reporting, indipendentemente dalle dimensioni del report.
- Il download dei pacchetti di dati inizia immediatamente con l'intero risultato memorizzato nella cache in un buffer dei dati.
- Il codice può iniziare a leggere i dati nel buffer senza dover attendere il completamento dell'intero flusso.
Search
Invia più richieste impaginate per scaricare l'intero report.
SearchStream
in genere offre prestazioni migliori perché elimina il tempo di rete di andata e ritorno necessario per richiedere le singole pagine. Ti consigliamo di utilizzare SearchStream
per tutti i report con oltre 10.000 righe. Non esiste una differenza significativa in termini di rendimento tra i metodi per i report di dimensioni inferiori (< 10.000 righe).
Il metodo utilizzato non influisce su quote e limiti dell'API: una singola query o un singolo report viene conteggiato come un'unica operazione indipendentemente dal fatto che i risultati vengano pagati o trasmessi in streaming.
Esempio di query di ricerca
Questa query di esempio restituisce i dati sul rendimento di un account per gli ultimi 30 giorni per campagna, segmentati per dispositivo:
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
Fai una richiesta
Per inviare una richiesta, devi passare una stringa customer_id
e una stringa query
all'interfaccia SearchAds360Service.SearchStream
o SearchAds360Service.Search
.
La richiesta consiste in un POST
HTTP al server dell'API Search Ads 360 Reporting in corrispondenza di uno dei seguenti URL:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
Ecco un esempio completo della definizione del report a searchStream
racchiusa in una richiesta POST
HTTP:
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" }
Elaborare una risposta
SearchAds360Service
restituisce un elenco di oggetti SearchAds360Row
.
Ogni SearchAds360Row
rappresenta un oggetto restituito dalla query. Ogni oggetto è costituito da un insieme di attributi che vengono compilati in base ai campi richiesti nella clausola SELECT
della query. Gli attributi non inclusi nella clausola SELECT
non vengono compilati negli oggetti nella risposta.
Ad esempio, la query seguente completa ogni oggetto SearchAds360Row
solo con campaign.id
, campaign.name
e campaign.status
. Altri attributi, come campaign.engine_id
o campaign.bidding_strategy_type
, vengono omessi.
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
Documentazione di riferimento
La sezione Riferimento include tutte le informazioni necessarie per utilizzare correttamente ciascun artefatto. C'è una pagina per ogni risorsa, ad esempio ad_group
e campaign
.
Le pagine segments
e metrics
elencano tutti i segmenti e i campi delle metriche disponibili.
Alcune risorse, segmenti e metriche sono incompatibili e non possono essere utilizzati insieme, mentre altri sono completamente compatibili e si integrano a vicenda. Ogni pagina delle risorse include le seguenti informazioni (se disponibili e appropriate) e altro ancora:
- Risorse attribuite
Per alcune risorse, potresti avere la possibilità di unire implicitamente le risorse correlate selezionando i rispettivi campi insieme a quelli della risorsa nella clausola
FROM
. Ad esempio, la risorsacampaign
è una risorsa attribuita della risorsaad_group
. Ciò significa che puoi includere campi comecampaign.id
ecampaign.bidding_strategy_type
nella query quando utilizziad_group
nella clausolaFROM
.La sezione Risorse attribuite elenca le risorse attribuite disponibili. Non tutte le risorse hanno risorse attribuite.
- Colonna Campi delle risorse
Tutti i campi della risorsa sono inclusi nella colonna Campi delle risorse. Ogni campo delle risorse rimanda a ulteriori dettagli sul campo, tra cui descrizione, categoria, tipo di dati, URL del tipo e impostazione filtrabile, selezionabile, ordinabile e ripetuta.
- Colonna Segmenti
Non tutti i campi del segmento sono selezionabili con una determinata risorsa.
La colonna Segmenti elenca i campi
segments
che puoi utilizzare nella stessa clausolaSELECT
dei campi della risorsa. Ogni campo contiene un link a dettagli completi sul campo, tra cui descrizione, categoria, tipo di dati, tipo di URL e impostazione filtrabile, selezionabile, ordinabile e ripetuta. Se utilizzi la risorsa nella clausolaFROM
, puoi utilizzare il menu a discesa Sì/No per filtrare i segmenti non disponibili.- Colonna Metriche
Non tutti i campi delle metriche sono selezionabili con una determinata risorsa.
La colonna Metriche elenca i campi
metrics
che puoi utilizzare nella stessa clausolaSELECT
dei campi della risorsa. Ogni campo contiene un link a dettagli completi sul campo, tra cui descrizione, categoria, tipo di dati, tipo di URL e impostazione filtrabile, selezionabile, ordinabile e ripetuta. Se utilizzi la risorsa nella clausolaFROM
, utilizza il menu a discesa Sì/No per escludere le metriche non disponibili.
- Segmentazione delle risorse
Alcune risorse hanno campi di risorse di segmentazione che puoi selezionare quando la risorsa si trova nella clausola
FROM
. Ad esempio, se selezioni un campo risorsacampaign
, comecampaign.name
, quando utilizzicampaign_budget
nella clausolaFROM
, verrà restituito e segmentato automaticamentecampaign.resource_name
, perchécampaign
è una risorsa di segmentazione dicampaign_budget
.La sezione Segmentazione delle risorse elenca le risorse di segmentazione disponibili. Non tutte le risorse hanno risorse di segmentazione.
- Selezionabile con
Alcuni campi
segments
non sono compatibili con altre risorse, segmenti e metriche.La pagina
segments
include un campo Selezionabile con espandibile per ogni camposegments
che elenca tutti i campi delle risorse compatibili, i campimetrics
e altri campisegments
che puoi includere nella clausolaSELECT
.
Segmentazione
Puoi segmentare i risultati di ricerca aggiungendo un campo segments.FIELD_NAME
alla clausola SELECT
della query.
Ad esempio, segments.device
nella
query riportata di seguito genera un report con una riga per impressions
di ogni
dispositivo per la risorsa specificata nella clausola FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
I risultati restituiti da SearchAds360Service.SearchStream
sono simili alla seguente stringa JSON:
{
"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"
}
},
...
]
}
Consulta segments
per un
elenco dei campi dei segmenti disponibili che puoi utilizzare.
Più segmenti
Puoi specificare più segmenti nella clausola SELECT
della query. La risposta contiene un oggetto SearchAds360Row
per ogni combinazione dell'istanza della risorsa principale specificata nella clausola FROM
e il valore di ogni campo segment
selezionato.
Ad esempio, la seguente query restituirà una riga per ogni combinazione di campaign
, segments.ad_network_type
e segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
Tieni presente che i risultati vengono segmentati implicitamente in base a ogni istanza della risorsa principale, ma non in base ai valori dei singoli campi selezionati.
La seguente query di esempio genera una riga per campagna, non una riga per
valore distinto del campo campaign.status
.
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
Segmentazione implicita
Ogni report viene inizialmente segmentato in base alla risorsa specificata nella clausola FROM
. Le metriche sono segmentate in base al campo resource_name
di questa risorsa
Questa query di esempio restituisce automaticamente ad_group.resource_name
e lo utilizza implicitamente
per segmentare le metriche a livello di ad_group
.
SELECT metrics.impressions
FROM ad_group
La stringa JSON restituita è simile a questa:
{
"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"
}
}
]
}
Segmenti di data principali
Puoi utilizzare i segmenti di data principali nella clausola WHERE
per specificare una data
o un periodo di tempo.
I seguenti campi di segmenti sono noti come segmenti di data principali:
segments.date
, segments.week
, segments.month
, segments.quarter
e
segments.year
.
Questa query di esempio restituisce le metriche clicks
della campagna per gli ultimi 30 giorni.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
I campi dei segmenti di data principali sono un'eccezione alla regola generale secondo cui non puoi utilizzare un campo dei segmenti nella clausola WHERE
, a meno che tu non includa il campo anche nella clausola SELECT
. Per ulteriori informazioni, consulta la sezione Filtro vietato.
Regole principali per i segmenti di data:
Puoi utilizzare un campo della data di base nella clausola
WHERE
senza includerlo nella clausolaSELECT
. Se vuoi, puoi anche includere il campo in entrambe le clausole.Questa query di esempio restituisce le metriche
clicks
per nome della campagna durante l'intervallo di date. Tieni presente chesegments.date
non è incluso nella clausolaSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Se includi un campo della data di base nella clausola
SELECT
, devi specificare una data finale o un intervallo di date nella clausolaWHERE
. I campi specificati nelle clausoleSELECT
eWHERE
non devono corrispondere.Questa query di esempio restituisce le metriche
clicks
per nome della campagna, segmentate per mese per tutti i giorni dell'intervallo di date.SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Date ISO 8601
Puoi utilizzare il formato YYYY-MM-DD
(ISO 8601) per specificare date e intervalli di date,
ad esempio:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
Per i segmenti di data principali che richiedono un periodo di tempo (segments.week
, segments.month
, segments.quarter
), puoi utilizzare l'operatore =
con il primo giorno del periodo di tempo, ad esempio:
WHERE segments.month = '2022-06-01'
Date predefinite
Puoi anche utilizzare i seguenti intervalli di date e date predefiniti:
Date predefinite | |
---|---|
TODAY |
Solo per oggi. |
YESTERDAY |
Solo ieri. |
LAST_7_DAYS |
7 giorni precedenti escluso oggi. |
LAST_BUSINESS_WEEK |
La settimana lavorativa di 5 giorni precedente (dal lunedì al venerdì). |
THIS_MONTH |
Tutti i giorni del mese corrente. |
LAST_MONTH |
Tutti i giorni del mese precedente. |
LAST_14_DAYS |
Nei 14 giorni precedenti, escluso oggi. |
LAST_30_DAYS |
30 giorni precedenti escluso oggi. |
THIS_WEEK_SUN_TODAY |
Periodo tra la domenica precedente e il giorno corrente. |
THIS_WEEK_MON_TODAY |
Periodo tra il lunedì precedente e il giorno corrente. |
LAST_WEEK_SUN_SAT |
Periodo di 7 giorni a partire dalla domenica precedente. |
LAST_WEEK_MON_SUN |
Periodo di 7 giorni a partire dal lunedì precedente. |
Esempio:
WHERE segments.date DURING LAST_30_DAYS
Nessuna metrica
Quando esegui una query, potresti incontrare metriche con un valore pari a zero per alcune entità. Scopri come gestire zero metriche nelle query.
Tipi di enumerazione SCONOSCIUTA
Se una risorsa viene restituita con il tipo di dati enum UNKNOWN
, significa che il tipo non è completamente supportato nella versione dell'API. Queste risorse potrebbero essere state create
tramite altre interfacce. Ad esempio, una nuova campagna o un nuovo annuncio viene introdotto nell'interfaccia utente di Search Ads 360, ma non è ancora supportato nella versione dell'API su cui esegui le query.
Puoi comunque selezionare le metriche se una risorsa è di tipo UNKNOWN
, ma tieni presente quanto segue:
- Una risorsa con un tipo
UNKNOWN
potrebbe essere supportata in un secondo momento, ma potrebbe rimanereUNKNOWN
a tempo indeterminato. - I nuovi oggetti di tipo
UNKNOWN
possono essere visualizzati in qualsiasi momento. Questi oggetti sono compatibili con le versioni precedenti perché il valore di enumerazione è già disponibile. Introduciamo le risorse associate a questa modifica non appena sono disponibili, in modo da avere una visione accurata dell'account. La risorsaUNKNOWN
potrebbe essere visualizzata a causa di nuove attività nel tuo account tramite altre interfacce o perché una risorsa non è più formalmente supportata. - Alle risorse
UNKNOWN
potrebbero essere associate metriche dettagliate su cui puoi eseguire query. UNKNOWN
risorse sono generalmente completamente visibili nell'interfaccia utente di Search Ads 360.