Struttura della query

Suggerimento: utilizza Interactive Query Builder per creare e convalidare le query Google Ads Query Language.

Le query per i campi di risorse, segmenti e metriche possono essere inviate al metodo GoogleAdsService Search o SearchStream. Per creare una query in Google Ads Query Language, utilizza la grammatica del linguaggio. Per una panoramica generale di Google Ads Query Language, consulta la panoramica di Google Ads Query Language. 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, puoi inviare la richiesta all'API Google Ads.

Punto chiave: GoogleAdsFieldService fornisce un catalogo per i client Google Ads Query Language con metadati su tutti i campi delle risorse, i campi dei segmenti e le metriche, le loro relazioni reciproche e la loro disponibilità in ogni clausola. Poiché l'insieme di risorse, campi, segmenti e metriche su cui è possibile eseguire query varia a seconda delle versioni principali dell'API, esegui una query su GoogleAdsFieldService nell'endpoint per la versione dell'API che stai scegliendo come target. Per ulteriori dettagli, consulta la documentazione relativa a GoogleAdsField e Differenze specifiche della versione.

Clausole

Le sezioni seguenti descrivono lo scopo e la sintassi di ogni clausola di Google Ads Query Language.

SELEZIONA

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

La seguente query di esempio 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 principali
  • campaign.id
  • campaign.name
• Campi delle risorse attribuiti
  • bidding_strategy.id
  • bidding_strategy.name
• Campi di segmentazione
  • segments.device
  • segments.date
• Metriche
  • metrics.impressions
  • metrics.clicks

Nota: alcuni campi non possono essere selezionati nella clausola SELECT a causa delle seguenti limitazioni:

• Esecuzione di query su campi non selezionabili. Questi campi hanno l'attributo dei metadati selectable contrassegnato come false.
• Selezione degli attributi dei campi ripetuti. Questi campi hanno l'attributo dei metadati is_repeated contrassegnato come true.
• Selezionare 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 è disponibile per la risorsa nella clausola FROM.
• Selezionare segmenti o metriche non compatibili tra loro. Per saperne di più, consulta Segmentazione.

Le informazioni relative alle condizioni precedenti sono disponibili nella nostra documentazione di riferimento o tramite GoogleAdsFieldService.

FROM

La clausola FROM specifica la risorsa principale da restituire. 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 al metodo GoogleAdsService Search o SearchStream. Tuttavia, la clausola FROM non deve essere specificata quando utilizzi 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 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

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

SELECT ad_group.id
FROM ad_group

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Punto chiave: se la risorsa nella clausola FROM elenca un'altra risorsa come segment, la selezione di qualsiasi attributo di quella risorsa funge da segmento.

WHERE

La clausola WHERE specifica le condizioni da applicare durante il filtro dei dati per la richiesta. Quando utilizzi la clausola WHERE, specifica una o più condizioni separate da AND. In genere, le condizioni seguono il pattern field_name Operator value (o utilizzano BETWEEN value AND value, IS NULL o IS NOT NULL). La clausola WHERE è facoltativa in una query.

L'esempio seguente utilizza 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 essere presenti anche nella clausola SELECT, ad eccezione dei seguenti segmenti di data, denominati segmenti di data principali:

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

Nella query seguente, viene selezionato segments.date. Poiché questo segmento è un segmento di data principale, devi fornire un intervallo di date finito nella clausola WHERE composto da segmenti di data principali:

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 vengono selezionati questi segmenti, almeno uno deve essere utilizzato nella clausola WHERE.

Per maggiori dettagli sui filtri per data, consulta Intervalli di date.

Punto chiave: il separatore AND può essere utilizzato solo tra le condizioni dell'operatore (WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE') e non all'interno di una singola condizione dell'operatore (WHERE segments.device != 'DESKTOP' AND 'MOBILE').

Durante l'applicazione dei filtri, tieni presente la sensibilità alle maiuscole dell'operatore. Per saperne di più, consulta Sensibilità alle maiuscole.

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

ORDER BY

La clausola ORDER BY specifica l'ordine in cui vengono restituiti i risultati. In questo modo, puoi disporre 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 separato da virgole. L'ordinamento avviene nella stessa sequenza specificata nella query. Ad esempio, in questa query che seleziona i dati dei gruppi di annunci, i risultati vengono ordinati in ordine crescente in base al nome della campagna, poi in ordine decrescente in base al numero di impressioni e infine 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 hai bisogno solo di un sottoinsieme di risultati.

Ad esempio, LIMIT può 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

Punto chiave: LIMIT consente di troncare i risultati. Per recuperare set di risultati di grandi dimensioni senza troncamento, utilizza GoogleAdsService.SearchStream per trasmettere in streaming le righe o impaginare con GoogleAdsService.Search.

PARAMETRI

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

Sono supportati i seguenti meta parametri:

include_drafts

Imposta include_drafts su true per restituire le entità bozza. Il valore predefinito è false.

Ad esempio, la seguente query recupera le bozze di 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 omettere il nome della risorsa di ogni tipo di risorsa nella risposta, a meno che non sia richiesto esplicitamente nella clausola SELECT. Il valore predefinito è false.

Nota: se prevedi di utilizzare uno degli oggetti restituiti per le operazioni di aggiornamento o rimozione, ti consigliamo di impostare questa opzione su false perché le risorse senza nomi non possono essere utilizzate nelle operazioni di mutazione. Se imposti questa opzione su true, assicurati di richiedere esplicitamente i nomi delle risorse sia della risorsa principale sia di quelle attribuite che recuperi utilizzando la query.

Query	Risorse restituite
SELECT campaign.name, customer.id FROM campaign	campaign.resource_name customer.resource_name Il valore predefinito di omit_unselected_resource_names è false, quindi vengono restituiti tutti i campi resource_name.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Nessuno omit_unselected_resource_names è specificato come true e né campaign.resource_name né customer.resource_name fanno parte della clausola SELECT.
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	campaign.resource_name omit_unselected_resource_names è specificato come true e campaign.resource_name è richiesto come parte della clausola SELECT.

Regole aggiuntive per le lingue

Oltre agli esempi per ogni clausola, Google Ads Query Language supporta i seguenti comportamenti:

• Il campo della risorsa principale non è obbligatorio nella clausola SELECT per una query. Ad esempio, puoi utilizzare uno o più campi della risorsa principale per filtrare i dati senza selezionarli:

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

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

  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'