Linguaggio di query di Google Ads

Terminologia chiave

Risorsa
Un'entità in Google Ads, ad esempio campaign o ad_group.
Segmento
Una dimensione utilizzata per raggruppare i dati, ad esempio segments.date o segments.device. Quando i segmenti sono inclusi nella clausola SELECT con le metriche, le metriche vengono suddivise per segmento.
Metrica
Una misurazione del rendimento, ad esempio metrics.impressions o metrics.clicks.
Risorsa attribuita
Una risorsa a cui viene eseguito un join implicito alla risorsa principale nella clausola FROM, che ti consente di selezionarne gli attributi insieme agli attributi della risorsa principale.

Eseguire query per informazioni su risorse o metadati

Google Ads Query Language può eseguire query sull'API Google Ads per i seguenti tipi di informazioni:

  • Risorse e relativi attributi, segmenti e metriche utilizzando GoogleAdsService Search o SearchStream: Il risultato di una query GoogleAdsService è un elenco di GoogleAdsRow istanze, in cui ogni GoogleAdsRow rappresenta una risorsa.

    Se vengono richiesti attributi o metriche, la riga include anche questi campi. Se vengono richiesti segmenti, la risposta mostra anche una riga aggiuntiva per ogni tupla segmento-risorsa.

  • Metadati sui campi e sulle risorse disponibili in GoogleAdsFieldService: Questo servizio fornisce un catalogo di campi su cui è possibile eseguire query con dettagli specifici sulla loro compatibilità e sul loro tipo.

    Il risultato di una GoogleAdsFieldService query è un elenco di GoogleAdsField istanze, in cui ogni GoogleAdsField contiene dettagli sul campo richiesto.

Per ulteriori dettagli sulla struttura delle query, consulta Struttura delle query e Grammatica di Google Ads Query Language.

Eseguire query per gli attributi delle risorse

Ecco un esempio di query di base per gli attributi della risorsa della campagna che illustra come restituire l'ID campagna, il nome e lo stato della campagna:

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

Questa query ordina per ID campagna. Ogni GoogleAdsRow risultante rappresenta un oggetto campaign compilato con i campi selezionati, incluso il resource_name della campagna.

Per scoprire quali altri campi sono disponibili per le query sulle campagne, consulta la Campaign documentazione di riferimento.

Eseguire query per le metriche

Oltre agli attributi selezionati per una determinata risorsa, puoi anche eseguire query per le metriche correlate:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Questa query filtra solo le campagne con stato PAUSED e che hanno ricevuto più di 1000 impressioni, ordinando per ID campagna. Ogni GoogleAdsRow risultante avrà un campo metrics compilato con le metriche selezionate.

Per un elenco delle metriche su cui è possibile eseguire query, consulta la Metrics documentazione.

Eseguire query per i segmenti

Oltre agli attributi selezionati per una determinata risorsa, puoi anche eseguire query per i segmenti correlati:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Analogamente all'esecuzione di query per le metriche, questa query filtra solo le campagne con stato PAUSED e che hanno ricevuto più di 1000 impressioni. Tuttavia, questa query segmenta i dati per data. Di conseguenza, ogni GoogleAdsRow risultante rappresenta una tupla di una campagna e della data Segment. La segmentazione suddivide le metriche selezionate, raggruppandole per ogni segmento nella clausola SELECT.

Per un elenco dei segmenti su cui è possibile eseguire query, consulta la Segments documentazione.

In una query per una determinata risorsa, potresti essere in grado di eseguire un join con altre risorse correlate, se disponibili. Queste risorse correlate sono note come "risorse attribuite". Puoi eseguire un join implicito con le risorse attribuite selezionando un attributo nella query.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Questa query non solo seleziona gli attributi della campagna, ma recupera anche gli attributi correlati di ogni campagna selezionata. Ogni GoogleAdsRow risultante rappresenta un oggetto campaign compilato con gli attributi della campagna selezionati, nonché l'attributo della strategia di offerta selezionata bidding_strategy.name.

Per scoprire quali risorse attribuite sono disponibili per le query sulle campagne, consulta la documentazione di riferimento di Campaign.

Best practice

  • Seleziona solo i campi di cui hai bisogno per evitare tempi di risposta lunghi e timeout.
  • Utilizza LIMIT durante lo sviluppo e i test per evitare di elaborare set di risultati di grandi dimensioni.
  • Applica i filtri nella clausola WHERE per ridurre al minimo il trasferimento dei dati e le dimensioni della risposta.
  • Utilizza GoogleAdsFieldService per verificare la compatibilità dei campi e i tipi di dati prima di creare query complesse.
  • Tieni presente che alcuni campi, in particolare quelli che coinvolgono grandi quantità di dati o calcoli complessi, possono aumentare il costo delle query.

Eseguire mutazioni in base ai risultati delle query

Quando esegui una query per una determinata risorsa, puoi utilizzare immediatamente i risultati restituiti come oggetti, modificarli e inviarli di nuovo al metodo di mutazione nel servizio della risorsa. Ecco un flusso di lavoro di esempio: 1. Esegui una query per tutte le campagne attualmente PAUSED e con impressioni maggiori di 1000. 1. Recupera l'oggetto Campaign dal campo campaign di ogni GoogleAdsRow nella risposta. 1. Modifica lo stato di ogni campagna da PAUSED a ENABLED. 1. Chiama CampaignService.MutateCampaigns con le campagne modificate per aggiornarle.

Metadati dei campi

Le query inviate a GoogleAdsFieldService sono destinate al recupero dei metadati dei campi. Queste informazioni possono essere utilizzate per capire come i campi possono essere utilizzati insieme in una query. Poiché i dati sono disponibili dall'API e forniscono i metadati necessari per convalidare o creare una query, gli sviluppatori possono farlo a livello di programmazione. Ecco una query tipica per i metadati:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

Puoi sostituire <INSERT_RESOURCE_OR_FIELD> in questa query con una risorsa (ad esempio customer o campaign) o un campo (ad esempio campaign.id, metrics.impressions, o ad_group.id).

Per un elenco dei campi su cui è possibile eseguire query, consulta la GoogleAdsField documentazione.

Esempi di codice

Le librerie client contengono esempi di utilizzo di Google Ads Query Language in GoogleAdsService. La cartella basic operations contiene esempi come GetCampaigns, GetKeywords e SearchForGoogleAdsFields.

Avanti
Grammatica delle query