Linguaggio di query di Google Ads

Suggerimento: utilizza Interactive Query Builder per creare e convalidare le query GAQL.

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, queste ultime vengono suddivise per segmento.

Metrica

Una misura del rendimento, ad esempio metrics.impressions o metrics.clicks.

Risorsa attribuita

Una risorsa che viene unita implicitamente alla risorsa principale nella clausola FROM, consentendoti di selezionare i suoi attributi insieme a quelli della risorsa principale.

Esegui query per informazioni su risorse o metadati

Il linguaggio di query di Google Ads 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 istanze GoogleAdsRow, con ogni GoogleAdsRow che 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 di risorsa del segmento.

• Metadati sui campi e sulle risorse disponibili in GoogleAdsFieldService: questo servizio fornisce un catalogo di campi su cui è possibile eseguire query con specifiche relative alla loro compatibilità e al loro tipo.

  Il risultato di una query GoogleAdsFieldService è un elenco di istanze GoogleAdsField, ognuna delle quali GoogleAdsField contiene i dettagli del campo richiesto.

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

Esegui 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, il nome e lo stato della campagna:

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

Questa query ordina i risultati in base all'ID campagna. Ogni GoogleAdsRow risultante rappresenta un oggetto campaign compilato con i campi selezionati, incluso resource_name della campagna.

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

Esegui 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 con più di 1000 impressioni, ordinandole in base all'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 documentazione di Metrics.

Esegui 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 alla query per le metriche, questa query filtra solo le campagne con stato PAUSED e con più di 1000 impressioni. Tuttavia, questa query segmenta i dati per data. In questo modo, ogni GoogleAdsRow risultante rappresenta una tupla di una campagna e del segmento di data. La segmentazione suddivide le metriche selezionate, raggruppandole in base a ciascun segmento nella clausola SELECT.

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

Esegui query sugli attributi di una risorsa correlata

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 unire le risorse attribuite in modo implicito 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 estrae 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 selezionato 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 necessari 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 di 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 della query.

Mutazione in base ai risultati della query

Quando esegui una query per una determinata risorsa, puoi utilizzare immediatamente i risultati restituiti come oggetti, modificarli e inviarli nuovamente al metodo mutate nel servizio della risorsa. Ecco un esempio di flusso di lavoro:

1. Esegui una query per tutte le campagne PAUSED con più di 1000 impressioni.
2. Recupera l'oggetto Campaign dal campo campaign di ogni GoogleAdsRow nella risposta.
3. Modifica lo stato di ogni campagna da PAUSED a ENABLED.
4. Chiama CampaignService.MutateCampaigns con le campagne modificate e un FieldMask corrispondente per aggiornarle.

Nota: quando aggiorni le risorse recuperate da una query, specifica un FieldMask (o utilizza l'utilità di maschera di campo integrata della libreria client) in modo che vengano aggiornati solo i campi modificati, evitando errori READ_ONLY_FIELD o IMMUTABLE_FIELD o la sovrascrittura involontaria di altri attributi.

Metadati dei campi

Le query inviate a GoogleAdsFieldService hanno lo scopo di recuperare i 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 in modo programmatico. 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>"

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

Punto chiave: tieni presente che in questa query non è presente una clausola FROM.

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

Differenze specifiche per versione

Sebbene la sintassi, le clausole e gli operatori di Google Ads Query Language siano identici in tutte le versioni supportate dell'API Google Ads (v23, v24, v25 e v26), il catalogo di risorse, segmenti, metriche e comportamenti dei report su cui è possibile eseguire query varia in base alla versione principale. Esegui una query su GoogleAdsFieldService nell'endpoint della versione API di destinazione per esaminare i campi e le regole di compatibilità per quella versione:

• Visualizzazione degli asset di espansione dell'URL finale:
  • Supporto delle campagne Shopping (v26 e versioni successive): final_url_expansion_asset_view supporta le campagne Shopping (campaign.advertising_channel_type = 'SHOPPING') oltre alle campagne Performance Max e sulla rete di ricerca. Per le campagne Shopping, puoi selezionare e filtrare in base ai campi ad_group, ma non puoi selezionare i campi asset_group.
  • Metriche selezionabili (v25 e versioni successive): l'esecuzione di query su final_url_expansion_asset_view restituisce tutte le metriche selezionabili per la visualizzazione. Nella versione 24 e precedenti, le risposte includono solo metrics.conversions e metrics.conversions_value per le campagne Performance Max e metrics.impressions per le campagne sulla rete di ricerca.
• Risorse degli obiettivi basati sul ciclo di vita: nella versione 25 e successive, tutti gli obiettivi basati sul ciclo di vita (acquisizione di nuovi clienti, customer retention e obiettivo di fidelizzazione) vengono interrogati dalle risorse unificate goal e campaign_goal_config, che sostituiscono customer_lifecycle_goal e campaign_lifecycle_goal (utilizzate per gli obiettivi di acquisizione di nuovi clienti nella versione 24 e precedenti, insieme a goal e campaign_goal_config per gli obiettivi di customer retention).
• Report sui prodotti Shopping per le campagne per app: nella versione 24 e successive, la risorsa shopping_product restituisce le righe dei prodotti per le campagne per app, oltre alle campagne Shopping, Performance Max, Demand Gen e video (nella versione 23, le campagne per app sono escluse dai risultati di shopping_product).
• Risorse, segmenti e metriche specifici per la versione:
  • v26 e versioni successive: include la risorsa search_lift_keyword_bundle, campaign.lift_measurement_config, local_services_lead.campaign, segments.search_lift_keyword_bundle, segments.search_property e le metriche di search lift (come metrics.relative_search_lift, metrics.normalized_incremental_searches, metrics.search_lift_cost_micros e metrics.search_lift_impressions).
  • v25 e versioni successive: include risorse di misurazione del lift (come lift_measurement_config), segmenti come segments.ad_sub_format_type e segments.loyalty_membership e metriche sul coinvolgimento di YouTube (metrics.youtube_likes, metrics.youtube_comments e metrics.youtube_shares). Rimuove local_services_lead.contact_details.email (selezionabile nella v24 e versioni precedenti).
  • v24 e versioni successive: include la risorsa cart_data_sales_view, segments.conversion_attribution_event_type su shopping_performance_view, segments.mobile_device_platform e segments.ad_network_type su performance_max_placement_view. Rimuove campaign.video_brand_safety_suitability (sostituito da customer.video_brand_safety_suitability), segments.ad_sub_network_type su campaign_budget e segments.click_type su ad_group_asset, campaign_asset e customer_asset (selezionabili solo nella versione v23).
• Codice di errore della finestra temporale con data granulare: le query che segmentano in base a segments.date, segments.week o segments.hour (o filtrano in base a un intervallo di date inferiore a un mese) oltre la finestra temporale di 37 mesi restituiscono DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED nella versione 24 e successive (o DateRangeError.UNKNOWN nella versione 23). Per maggiori dettagli, consulta Intervalli di date.

Esempi di codice

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