Struttura della query

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 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 di campo, nomi di risorse, operatori, condizioni e ordini per aiutarti a selezionare i dati corretti. Una volta combinata in una singola query, è possibile effettuare una richiesta utilizzando l'API Google Ads.

Punto chiave: GoogleAdsFieldService fornisce un catalogo per i client del linguaggio di query di Google Ads con metadati su tutti i campi delle risorse, i campi dei segmenti e le metriche, nonché le loro relazioni gli uni con gli altri e la disponibilità in ogni clausola, come definito di seguito. Per maggiori dettagli, consulta la documentazione per GoogleAdsField.

Clausole

Video: compatibilità dei campi GAQL

SELECT

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

La query di esempio seguente 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 Segmenta

  • segments.device
  • segments.date

• Metriche

  • metrics.impressions
  • metrics.clicks

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

• Esecuzione di query su campi non selezionabili. L'attributo di metadati Selectable di questi campi sarà contrassegnato come false.
• Selezione degli attributi dei campi ripetuti. L'attributo di metadati isRepeated di questi campi sarà contrassegnato come true.
• La selezione dei campi che non sono disponibili per la risorsa specificata nella clausola FROM. Gli attributi di alcune risorse non possono essere selezionati insieme, inoltre nella clausola FROM sarà disponibile solo un sottoinsieme di tutte le metriche e di tutti i segmenti per la risorsa.
• Selezionare segmenti o metriche non compatibili tra loro. Per ulteriori informazioni in merito, consulta la sezione Segmentazione.

Le informazioni relative alle condizioni precedenti sono disponibili nei nostri documenti di riferimento o in GoogleAdsFieldService.

FROM

La clausola FROM specifica la risorsa principale che verrà restituita. La risorsa nella clausola FROM definisce i campi che possono essere utilizzati per 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, ma non deve essere specificata quando utilizzi GoogleAdsFieldService.

Sebbene nella clausola FROM possa esistere una sola risorsa per una determinata query, potrebbero essere disponibili anche i campi delle risorse attribuite. Queste risorse sono implicitamente unite 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 ai 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 verrà incluso nella risposta nonostante non sia 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

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

WHERE

La clausola WHERE specifica le condizioni da applicare quando filtri i dati per la richiesta. Quando utilizzi la clausola WHERE, è possibile 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 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 i seguenti segmenti di data, denominati segmenti di data principali, a eccezione:

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

Nella query seguente, tieni presente 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: audiences.date, segments.week, segments.month, segments.quarter e segments.year. Se viene selezionato uno qualsiasi di questi segmenti, è necessario utilizzarne almeno uno nella clausola WHERE.

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 applichi un filtro, è importante tenere presente la sensibilità dell'operatore alle maiuscole. Per ulteriori dettagli, vedi 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 i risultati devono essere restituiti. Questo ti consente di 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 sarà 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 avverrà nella stessa sequenza specificata nella query. Ad esempio, in questa query, se selezioni 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, puoi utilizzare LIMIT 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

Punto chiave: LIMIT ti consente di troncare i risultati. Utilizza il campo page_size di GoogleAdsService.Search per gestire lunghi elenchi di risultati.

PARAMETRI

La clausola PARAMETERS consente di specificare i meta-parametri 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 la restituzione delle entità in modalità bozza. Il valore predefinito è false.

Ad esempio, la seguente query recupera le bozze di campagna 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 venga 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, poiché le risorse senza nomi delle risorse non possono essere utilizzate nelle operazioni di modifica. Se imposti questa opzione su true, assicurati di richiedere esplicitamente i nomi delle risorse sia della risorsa principale sia delle risorse degli attributi recuperate usando la query.

esempi omit_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names per impostazione predefinita è false, quindi vengono restituiti tutti i campi resource_name.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: Nessuno. 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 lingua aggiuntive

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

• Non è necessario che il campo delle risorse principali rientri nella clausola SELECT per una query. Ad esempio, potresti voler utilizzare solo uno o più campi risorsa 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.costMicros
  FROM campaign
  

• I campi di segmentazione possono essere selezionati senza alcun campo delle risorse o metrica associati:

  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'