Linguaggio di query di Google Ads

Il linguaggio di query Google Ads può eseguire query sull'API Google Ads per

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 segmento-risorsa.

Metadati relativi ai campi e alle risorse disponibili in

GoogleAdsFieldService

Questo servizio fornisce un catalogo di campi interrogabili con informazioni dettagliate sulla loro compatibilità e sul loro tipo.

Il risultato di una query GoogleAdsFieldService è un elenco di istanze GoogleAdsField, ciascuna contenente i dettagli del campo richiesto.GoogleAdsField

Eseguire query sugli attributi di una risorsa

Di seguito è riportata una query di base per gli attributi della risorsa campagna che illustra come recuperare 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 in base all'ID campagna. Ogni GoogleAdsRow risultante rappresenta un oggetto campaign compilato con i campi selezionati (incluso il resource_name della campagna in questione).

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

Eseguire query sulle 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 registrato 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.

Eseguire query sui 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. Di conseguenza, ogni GoogleAdsRow risultante rappresenta una tupla di una campagna e della data Segment. È importante tenere presente che il 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.

Eseguire query sugli attributi di una risorsa correlata

In una query per una determinata risorsa, potresti essere in grado di eseguire l'unione con altre risorse correlate, se disponibili. Queste risorse correlate sono note come "risorse attribuite". Puoi eseguire un join con 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 delle campagne, ma estrae anche gli attributi correlati da ogni campagna selezionata. Ogni GoogleAdsRow risultante rappresenta un oggetto campaign compilato con gli attributi della campagna selezionati, nonché con 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.

Mutazione in base ai risultati delle query

Quando esegui una query per una determinata risorsa, puoi acquisire immediatamente i risultati restituiti come oggetti, modificarli e inviarli nuovamente al metodo di mutazione nel servizio della risorsa. Di seguito è riportato un flusso di lavoro di esempio:

1. Esegui una query per tutte le campagne attualmente in stato PAUSED e con impressioni superiori a 1000.
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 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 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>"

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 documentazione di GoogleAdsField.

Esempi di codice

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