Le query per i campi delle risorse, dei segmenti e delle metriche possono essere inviate ai metodi Search o SearchStream di GoogleAdsService
. Per creare una query nel linguaggio di query di Google Ads, devi utilizzarla
grammatica del linguaggio. Una query è composta da una serie di
clausole:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
Le clausole utilizzano nomi di campi, nomi di risorse, operatori, condizioni e ordinamenti per aiutarti a selezionare i dati corretti. Una volta combinate in un'unica query, è possibile effettuare una richiesta utilizzando l'API Google Ads.
Clausole
Video: compatibilità dei campi GAQL
SELEZIONA
La clausola SELECT
specifica un insieme di campi da recuperare nella richiesta.
SELECT
accetta un elenco separato da virgole di campi delle risorse, campi dei segmenti 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 una singola 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 su campi non selezionabili. L'attributo dei metadati
Selectable
di questi campi sarà contrassegnato comefalse
. - Selezionare gli attributi dei campi ripetuti. L'attributo dei metadati
isRepeated
di questi campi sarà contrassegnato cometrue
. - Selezionare campi non disponibili per la risorsa specificata nella clausola
FROM
. Gli attributi di alcune risorse non possono essere selezionati insieme. Inoltre, per la risorsa nella clausolaFROM
sarà disponibile solo un sottoinsieme di tutte le metriche e di tutti i segmenti. - Selezionare 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 documentazione di riferimento o su GoogleAdsFieldService
.
FROM
La clausola FROM
specifica la risorsa principale che verrà restituita. La risorsa nella clausola FROM
definisce i campi che possono essere utilizzati in tutte le altre clausole per la query specificata. Nella clausola FROM
è possibile specificare una sola risorsa. La clausola FROM
è obbligatoria in una query ai metodi GoogleAdsService
Search o SearchStream, ma non deve essere specificata quando si utilizza GoogleAdsFieldService
.
Sebbene nella clausola FROM
per una determinata query possa esistere una sola risorsa, 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 restituirne i valori. Non tutte le risorse hanno risorse attribuite. Nel seguente esempio 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 nonostante non sia 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 alla
seguente query:
SELECT
campaign.id,
ad_group.id
FROM ad_group
WHERE
La clausola WHERE
specifica le condizioni da applicare durante il filtro 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 richiede il numero di clic per tutte le campagne con impressioni su 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 trovarsi nella clausola SELECT
, con le seguenti eccezioni per i segmenti di date, denominati segmenti di date principali:
segments.date
segments.week
segments.month
segments.quarter
segments.year
Nella query seguente, tieni presente che è selezionato segments.date
.
Poiché si tratta di un segmento di date principale, è necessario fornire un intervallo di date limitato 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 viene selezionato, almeno uno deve essere utilizzato nella clausola WHERE
.
Quando applichi i filtri, è importante tenere presente la sensibilità alle maiuscole dell'operatore. Per ulteriori dettagli, consulta la sezione Sensibilità alle maiuscole.
Per un elenco completo degli operatori, consulta la grammatica della lingua.
ORDER BY
La clausola ORDER BY
specifica l'ordine in cui devono essere
restituito i risultati. In questo modo, puoi organizzare i dati in ordine crescente o decrescente in base al nome di un campo. Ogni ordinamento è specificato come field_name
seguito da
ASC
o DESC
. Se non viene specificato né ASC
né DESC
, l'ordine predefinito è ASC
. 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 delimitato da virgole. L'ordinamento verrà eseguito nella stessa sequenza specificata nella query.
Ad esempio, in questa query che seleziona i dati dei gruppi di annunci, i risultati verranno ordinati in ordine crescente per nome della campagna, in ordine decrescente per numero di impressioni e in ordine decrescente per 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
LIMITE
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 metaparametri per la richiesta.
Questi parametri possono influire sui tipi di righe restituite.
Attualmente sono supportati i seguenti meta parametri:
include_drafts
Imposta include_drafts
su true
per consentire il ritorno delle entità in bozza.
Il valore predefinito è false
.
Ad esempio, la seguente query recupera le campagne in bozza 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 che il nome della risorsa di ogni tipo di risorsa nella risposta venga restituito, a meno che non sia esplicitamente richiesto nella clausola SELECT
. Il valore predefinito è false
.
Esempi di omit_unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.resource_name
omit_unselected_resource_names ha il valore predefinito false , quindi tutti i campi resource_name vengono restituiti.
|
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: Nessuna. omit_unselected_resource_names è specificato come true
e campaign.resource_name e customer.resource_name
non fanno parte della clausola SELECT .
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource:campaign.resource_name
omit_unselected_resource_names è specificato come true
e campaign.resource_name richiesto nell'ambito della
clausola SELECT .
|
Regole linguistiche aggiuntive
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 sia presente nella clausola
SELECT
per una query. Ad esempio, potresti voler utilizzare solo uno o più campi della risorsa principale 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 aggiuntivi:
SELECT segments.device FROM campaign
Il campo
resource_name
(ad es.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'