Struttura della query

Le query per i campi di risorse, segmenti e metriche possono essere inviate ai metodi GoogleAdsService Search o SearchStream. Per creare una query in Google Ads Query Language, devi crearla utilizzando la grammatica del linguaggio. Una query è composta da una serie di clausole:

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

Le clausole utilizzano nomi dei campi, nomi delle risorse, operatori, condizioni e ordinamenti per aiutarti a selezionare i dati corretti. Se combinate in un'unica query, è possibile effettuare una richiesta utilizzando l'API Google Ads.

Clausole

ondemand_video Video: GAQL Field Compatibility

SELEZIONA

La clausola SELECT specifica un insieme di campi da recuperare nella richiesta. SELECT accetta un elenco separato da virgole di campi risorsa, campi segmento e metriche, restituendo i valori nella risposta. La clausola SELECT è obbligatoria in una query.

La query di esempio riportata di seguito mostra un esempio di selezione degli attributi per una determinata risorsa:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Puoi richiedere diversi tipi di campi in un'unica richiesta, ad esempio:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

• Campi delle risorse

  • campaign.id
  • campaign.name

• Campi delle risorse

  • bidding_strategy.id
  • bidding_strategy.name

• Campi segmento

  • segments.device
  • segments.date

• Metriche

  • metrics.impressions
  • metrics.clicks

Alcuni campi potrebbero non essere consentiti nella clausola SELECT a causa delle seguenti limitazioni:

• Eseguire query sui campi non selezionabili. Questi campi avranno l'attributo dei metadati Selectable contrassegnato come false.
• Selezionare gli attributi dei campi ripetuti. Questi campi avranno l'attributo dei metadati isRepeated contrassegnato come true.
• Selezione di campi non disponibili per la risorsa specificata nella clausola FROM. Gli attributi di alcune risorse non possono essere selezionati insieme e solo un sottoinsieme di tutte le metriche e i segmenti sarà disponibile per la risorsa nella clausola FROM.
• Selezione di segmenti o metriche non compatibili tra loro. Per maggiori informazioni, consulta la sezione sulla segmentazione.

Le informazioni relative alle condizioni sopra indicate sono disponibili nella nostra documentazione di riferimento o su GoogleAdsFieldService.

FROM

La clausola FROM specifica la risorsa principale che verrà restituita. La risorsa nella clausola FROM definisce quali campi possono essere utilizzati in tutte le altre clausole per la query specificata. È possibile specificare una sola risorsa nella clausola FROM. La clausola FROM è obbligatoria in una query per i metodi GoogleAdsService Search o SearchStream. Tuttavia, la clausola FROM non deve essere specificata quando si utilizza GoogleAdsFieldService.

Anche se nella clausola FROM può esistere una sola risorsa per una determinata query, potrebbero essere disponibili anche i campi delle risorse attribuite. Queste risorse vengono unite implicitamente alla risorsa nella clausola FROM, quindi devi solo aggiungere i relativi attributi alla clausola SELECT per restituire i relativi valori. Non tutte le risorse hanno risorse attribuite. Nell'esempio seguente puoi richiedere sia l'ID gruppo di annunci sia l'ID campagna dai gruppi di annunci:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Il campo resource_name della risorsa principale viene sempre restituito. Nel seguente esempio, ad_group.resource_name verrà incluso nella risposta anche se non è stato selezionato esplicitamente nella query:

SELECT ad_group.id
FROM ad_group

Lo stesso vale per le altre risorse quando è selezionato almeno un campo. Ad esempio, campaign.resource_name verrà incluso nella risposta per la seguente query:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

La clausola WHERE specifica le condizioni da applicare durante il filtraggio dei dati per la richiesta. Quando utilizzi la clausola WHERE, puoi specificare una o più condizioni utilizzando AND per separarle. Ogni condizione deve seguire il pattern field_name Operator value. La clausola WHERE è facoltativa in una query.

Di seguito è riportato un esempio di utilizzo di WHERE per restituire le metriche di un determinato periodo di tempo:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Puoi combinare più condizioni per filtrare i dati. Questo esempio richiederà il numero di clic per tutte le campagne con impressioni sui dispositivi mobili negli ultimi 30 giorni.

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

I segmenti nella clausola WHERE devono essere nella clausola SELECT, con i seguenti segmenti di date, denominati segmenti di date principali, che fanno eccezione:

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

Nella query seguente, nota che è selezionato segments.date. Poiché questo segmento è un segmento di date principale, richiede un intervallo di date finito composto da segmenti di date principali nella clausola WHERE.

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Tutti i segmenti che soddisfano la condizione precedente sono: segments.date, segments.week, segments.month, segments.quarter e segments.year. Se uno di questi segmenti è selezionato, almeno uno deve essere utilizzato nella clausola WHERE.

Quando filtri, è importante tenere presente la sensibilità alle maiuscole e minuscole dell'operatore. Per ulteriori dettagli, consulta la sezione Distinzione tra maiuscole e minuscole.

Per un elenco completo degli operatori, consulta la grammatica del linguaggio.

ORDER BY

La clausola ORDER BY specifica l'ordine in cui devono essere restituiti i risultati. In questo modo, puoi disporre i dati in ordine crescente o decrescente in base a un nome di campo. Ogni ordinamento è specificato come field_name seguito da ASC o DESC. Se non vengono specificati né ASC né DESC, l'ordine è ASC per impostazione predefinita. La clausola ORDER BY è facoltativa in una query.

La seguente query ordina le campagne restituite in base al numero di clic dal più alto al più basso:

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

Puoi specificare più campi nella clausola ORDER BY utilizzando un elenco separato da virgole. L'ordinamento avverrà nella stessa sequenza specificata nella query. Ad esempio, in questa query che seleziona i dati del gruppo di annunci, i risultati verranno ordinati in ordine crescente in base al nome della campagna, poi in ordine decrescente in base al numero di impressioni e poi in ordine decrescente in base al numero di clic:

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

La clausola LIMIT consente di specificare il numero di risultati da restituire. Questa opzione è utile se ti interessa solo un riepilogo.

Ad esempio, LIMIT può essere utilizzato per limitare il numero totale di risultati per la seguente query:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

PARAMETRI

La clausola PARAMETERS consente di specificare i metadati per la richiesta. Questi parametri possono influire sui tipi di righe restituite.

Sono supportati i seguenti parametri meta:

include_drafts

Imposta include_drafts su true per consentire la restituzione delle entità bozza. Il valore predefinito è false.

Ad esempio, la seguente query recupera le bozze delle campagne insieme alle campagne normali:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

Imposta omit_unselected_resource_names su true per impedire la restituzione del nome della risorsa di ogni tipo di risorsa nella risposta, a meno che non venga richiesto esplicitamente nella clausola SELECT. Il valore predefinito è false.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Regole aggiuntive per le lingue

Oltre agli esempi per ogni clausola, il linguaggio di query di Google Ads presenta i seguenti comportamenti che possono essere utilizzati:

• Non è necessario che il campo della risorsa principale si trovi nella clausola SELECT per una query. Ad esempio, potresti voler utilizzare solo uno o più campi delle risorse principali per filtrare i dati:

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• Le metriche possono essere selezionate esclusivamente per una determinata risorsa; nella query non sono richiesti altri campi della risorsa:

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• I campi di segmentazione possono essere selezionati senza campi di risorse o metriche di accompagnamento:

  SELECT segments.device FROM campaign
  

• Il campo resource_name (ad esempio campaign.resource_name) può essere utilizzato per filtrare o ordinare i dati:

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'