Struttura della query

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

Le query per i campi di risorse, segmenti e metriche possono essere inviate al GoogleAdsService Search o SearchStream metodo. 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. Quando vengono combinate in una singola 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 query su GoogleAdsFieldService nell'endpoint della versione dell'API di destinazione. 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.

SELECT

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 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 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 principali
  • campaign.id
  • campaign.name
• Campi delle risorse attribuite
  • bidding_strategy.id
  • bidding_strategy.name
• Campi dei segmenti
  • 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.
• 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 è disponibile per la risorsa nella clausola FROM.
• Selezione di segmenti o metriche non compatibili tra loro. Per ulteriori informazioni, consulta la sezione Segmentazione.

Le informazioni relative alle condizioni precedenti sono disponibili nella documentazione di riferimento o in 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 può essere specificata una sola risorsa. La clausola FROM è obbligatoria in una query al GoogleAdsService Search o SearchStream metodo. 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 del gruppo di annunci sia l'ID della campagna dai gruppi di annunci:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Il campo resource_name della risorsa principale viene sempre restituito. Nell'esempio seguente, 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 filtraggio 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 (oppure 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 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 presenti anche nella clausola SELECT, ad eccezione di 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 viene selezionato uno di questi segmenti, almeno uno di essi deve essere utilizzato nella clausola WHERE.

Per ulteriori dettagli sul filtro 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').

Quando filtri, tieni presente la distinzione tra maiuscole e minuscole dell'operatore. Per ulteriori informazioni, 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 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 viene 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 troncarli, utilizza GoogleAdsService.SearchStream per eseguire lo streaming delle righe o la paginazione con GoogleAdsService.Search.

PARAMETERS

La clausola PARAMETERS consente di specificare i parametri meta 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 restituire le entità bozza. Il valore predefinito è false.

Ad esempio, la seguente query recupera le campagne 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 omettere il nome della risorsa di ogni tipo di risorsa nella risposta, a meno che non sia stato 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 di risorse 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 tutte le risorse attribuite che recuperi utilizzando la query.

Query	Risorse restituite
SELECT campaign.name, customer.id FROM campaign	campaign.resource_name customer.resource_name omit_unselected_resource_names ha come valore predefinito false, quindi vengono restituiti tutti i campi resource_name fields are returned.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Nessuna 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 viene richiesto come parte della clausola SELECT.

Regole di lingua aggiuntive

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 delle risorse principali 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; nella query non sono necessari altri campi della risorsa:

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

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

  SELECT segments.device FROM campaign
  

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

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