Crea report di ricerca nell'API Search Ads 360 Reporting

Leggi le sezioni di seguito per scoprire come creare report di ricerca nell'API Search Ads 360 Reporting.

Servizio di ricerca

L'API Search Ads 360 Reporting fornisce un servizio speciale per la ricerca e la generazione di report.

SearchAds360Service è un servizio unificato di recupero e report di oggetti che fornisce due metodi di ricerca: SearchStream e Search. Le ricerche vengono trasmesse in una stringa di query scritta nel linguaggio di query di Search Ads 360. Puoi definire query per:

• Recuperare attributi specifici degli oggetti.
• Recuperare le metriche sul rendimento degli oggetti in base a un intervallo di date.
• Ordinare gli oggetti in base ai relativi attributi.
• Filtrare i risultati utilizzando le condizioni che specificano gli oggetti da restituire
• Limitare il numero di oggetti restituiti.

Entrambi i metodi di ricerca restituiscono tutte le righe che corrispondono alla query. Ad esempio, quando recuperi campaign.id, campaign.name, e metrics.clicks, l'API restituisce un SearchAds360Row contenente un oggetto campagna con i campi id e name impostati e un metrics oggetto con il campo clicks impostato.

Metodi di ricerca

SearchStream

Invia una singola richiesta e avvia una connessione persistente con l'API Search Ads 360 Reporting indipendentemente dalle dimensioni del report.

• I pacchetti di dati iniziano a essere scaricati immediatamente con l'intero risultato memorizzato nella cache in un buffer di dati.
• Il codice può iniziare a leggere i dati memorizzati nel buffer senza dover attendere il completamento dell'intero stream.

Search

Invia più richieste paginate per scaricare l'intero report.

SearchStream in genere offre prestazioni migliori perché elimina il tempo di andata e ritorno della rete necessario per richiedere singole pagine. Ti consigliamo di utilizzare SearchStream per tutti i report con più di 10.000 righe. Non esiste una differenza di prestazioni significativa tra i metodi per i report più piccoli (< 10.000 righe).

Il metodo che utilizzi non influisce sulle quote e sui limiti dell'API : una singola query o un singolo report viene conteggiato come un'operazione, indipendentemente dal fatto che i risultati siano paginati o trasmessi in streaming.

Query di ricerca di esempio

Questa query di esempio restituisce i dati sul rendimento di un account negli 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

Nota: il linguaggio di query di Search Ads 360 fornisce informazioni dettagliate su come utilizzare ogni clausola della query di ricerca.

Fai una richiesta

Per inviare una richiesta, devi passare una customer_id e una stringa query all'interfaccia SearchAds360Service.SearchStream o SearchAds360Service.Search.

Nota: gli esempi riportati di seguito mostrano la richiesta HTTP/JSON sottostante. Viene utilizzata per illustrare i concetti. Ti consigliamo di utilizzare le nostre librerie client basate su gRPC per inviare le richieste nella tua app.

La richiesta è costituita da un POST HTTP al server dell'API Search Ads 360 Reporting a 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

Di seguito è riportato un esempio completo della definizione del report per 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"
}

Elabora una risposta

SearchAds360Service restituisce un elenco di SearchAds360Row oggetti.

Ogni SearchAds360Row rappresenta un oggetto restituito dalla query. Ogni oggetto è costituito da un insieme di attributi compilati in base ai campi richiesti nella clausola SELECT della query. Gli attributi non inclusi nella clausola SELECT non vengono compilati negli oggetti della risposta.

Ad esempio, la query riportata di seguito compila 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 ogni artefatto. Esiste una pagina per ogni risorsa, ad esempio ad_group e campaign. Le pagine segments e metrics elencano tutti i campi di segmenti e metriche disponibili.

Alcune risorse, alcuni segmenti e alcune metriche sono incompatibili e non possono essere utilizzati insieme, mentre altri sono completamente compatibili e si completano 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 relativi campi insieme ai campi della risorsa nella clausola FROM. Ad esempio, la campaign risorsa è una risorsa attribuita della ad_group risorsa. Ciò significa che puoi includere campi come campaign.id e campaign.bidding_strategy_type nella query quando utilizzi ad_group nella clausola FROM.

La sezione Risorse attribuite elenca le risorse attribuite disponibili. Non tutte le risorse hanno risorse attribuite.

Colonna dei 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 di filtraggio, selezione, ordinamento e ripetizione.

Colonna Segmenti

Non tutti i campi dei segmenti sono selezionabili con una determinata risorsa.

La colonna Segmenti elenca i campi segments che puoi utilizzare nella stessa clausola SELECT dei campi della risorsa. Ogni campo rimanda a tutti i dettagli sul campo, tra cui descrizione, categoria, tipo di dati, URL del tipo e impostazione di filtraggio, selezione, ordinamento e ripetizione. Se utilizzi la risorsa nella clausola FROM, 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 clausola SELECT dei campi della risorsa. Ogni campo rimanda a tutti i dettagli sul campo, tra cui descrizione, categoria, tipo di dati, URL del tipo e impostazione di filtraggio, selezione, ordinamento e ripetizione. Se utilizzi la risorsa nella clausola FROM, utilizza il menu a discesa Sì/No per filtrare le metriche non disponibili.

Nota: quando recuperi le metriche correlate alla valuta (ad es. cost_micros) per una data o un intervallo di date specifici, assicurati di includere segments.date nella clausola SELECT.

Segmentazione delle risorse

Alcune risorse hanno campi di risorse di segmentazione che puoi selezionare quando la risorsa è nella clausola FROM. Ad esempio, se selezioni un campo della risorsa campaign, come campaign.name, quando utilizzi campaign_budget nella clausola FROM, campaign.resource_name verrà restituito e segmentato automaticamente, perché campaign è una risorsa di segmentazione di campaign_budget.

La sezione Risorse di segmentazione elenca le risorse di segmentazione disponibili. Non tutte le risorse hanno risorse di segmentazione.

Selezionabile con

Alcuni campi segments sono incompatibili con altre risorse, altri segmenti e altre metriche.

La pagina segments include un elemento espandibile Selezionabile con per ogni campo segments che elenca tutti i campi delle risorse , i campi metrics e gli altri campi segments compatibili che puoi includere nella clausola SELECT.

Nota: consulta il linguaggio di query di Search Ads 360 per scoprire come utilizzare ogni clausola di una query.

Segmentazione

Puoi segmentare i risultati di ricerca aggiungendo un segments.FIELD_NAME campo alla SELECT clausola 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 FROM clausola.

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

I risultati restituiti da SearchAds360Service.SearchStream sono simili a questa 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

**Attenzione:** il numero di righe può aumentare in modo esponenziale per ogni campo segments aggiuntivo che aggiungi alla query.

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 del 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 da ogni istanza della risorsa principale, ma non dai valori dei singoli campi selezionati.

La seguente query di esempio genera una riga per campagna, non una riga per ogni 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 vengono segmentate in base al campo resource_name di questa risorsa.

Nota: Il campo resource_name della risorsa nella clausola FROM viene sempre restituito, anche se non è specificato nella clausola SELECT. Per saperne di più, consulta il campo resource_name per maggiori informazioni.

Questa query di esempio restituisce automaticamente ad_group.resource_name e implicitamente lo utilizza per segmentare le metriche a livello di ad_group

SELECT metrics.impressions
FROM ad_group

La stringa JSON restituita è simile alla seguente:

{
  "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 date principali

Puoi utilizzare i segmenti di date principali nella WHERE clausola per specificare una data o un periodo di tempo.

I seguenti campi dei segmenti sono noti come segmenti di date principali: segments.date, segments.week, segments.month, segments.quarter, e segments.year.

Questa query di esempio restituisce le metriche clicks della campagna negli 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 date principali sono un'eccezione alla regola generale secondo cui non puoi utilizzare un campo dei segmenti nella clausola WHERE, a meno che non includi anche il campo nella clausola SELECT. Per saperne di più, consulta la sezione Filtri vietati.

Regole dei segmenti di date principali:

• Puoi utilizzare un campo di date principale nella clausola WHERE senza includerlo nella clausola SELECT. Se preferisci, puoi 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 che segments.date non è incluso nella clausola SELECT.

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

• Se includi un campo di date principale nella clausola SELECT, devi specificare una data o un intervallo di date finito nella clausola WHERE. I campi specificati nelle clausole SELECT e WHERE non devono necessariamente 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 date 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'

Nota: se specifichi una data che non è il primo giorno di un periodo, riceverai un errore MISALIGNED_DATE_FOR_FILTER.

Date predefinite

Puoi anche utilizzare le seguenti date e intervalli di date predefiniti:

Date predefinite
TODAY	Solo oggi.
YESTERDAY	Solo ieri.
LAST_7_DAYS	Gli ultimi 7 giorni, escluso oggi.
LAST_BUSINESS_WEEK	La settimana lavorativa precedente di 5 giorni (da lunedì a venerdì).
THIS_MONTH	Tutti i giorni del mese corrente.
LAST_MONTH	Tutti i giorni del mese precedente.
LAST_14_DAYS	Gli ultimi 14 giorni, escluso oggi.
LAST_30_DAYS	Gli ultimi 30 giorni, escluso oggi.
THIS_WEEK_SUN_TODAY	Il periodo compreso tra la domenica precedente e il giorno corrente.
THIS_WEEK_MON_TODAY	Il periodo compreso tra il lunedì precedente e il giorno corrente.
LAST_WEEK_SUN_SAT	Il periodo di 7 giorni a partire dalla domenica precedente.
LAST_WEEK_MON_SUN	Il periodo di 7 giorni a partire dal lunedì precedente.

Esempio:

WHERE segments.date DURING LAST_30_DAYS

Metriche zero

Quando esegui una query, potresti riscontrare metriche con un valore pari a zero per alcune entità. Scopri come gestire le metriche zero nelle query.

Tipi di enumerazione UNKNOWN

Se viene restituita una risorsa con il tipo di dati di enumerazione UNKNOWN, significa che il tipo non è completamente supportato nella versione dell'API. Queste risorse potrebbero essere state create tramite altre interfacce. Ad esempio, nell'interfaccia utente di Search Ads 360 viene introdotta una nuova campagna o un nuovo annuncio, ma non è ancora supportato nella versione dell'API su cui stai eseguendo la query.

Puoi comunque selezionare le metriche quando una risorsa ha il tipo UNKNOWN, ma devi tenere presente quanto segue:

• Una risorsa con un tipo UNKNOWN potrebbe essere supportata in un secondo momento, ma potrebbe rimanere UNKNOWN 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 con questa modifica man mano che sono disponibili, in modo che tu possa avere una visione accurata del tuo account. La risorsa UNKNOWN potrebbe essere visualizzata a causa di una nuova attività nel tuo account tramite altre interfacce o perché una risorsa non è più supportata formalmente.

• Le risorse UNKNOWN potrebbero avere metriche dettagliate associate a cui puoi eseguire query.

• Le risorse UNKNOWN sono in genere completamente visibili nell'interfaccia utente di Search Ads 360.