Struttura della query

Le query per i campi di risorse, segmenti e metriche possono essere inviate GoogleAdsService Ricerca o SearchStream di machine learning. Per creare una query nel Linguaggio di query di Google Ads, devi crearla utilizzando grammatica della lingua. Una query è composta da una serie :

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

Le clausole utilizzano nomi campo, nomi di risorse, operatori, condizioni e ordering per aiutarti a selezionare i dati corretti. Una volta combinati in un'unica una richiesta può essere effettuata utilizzando l'API Google Ads.

Punto chiave: la GoogleAdsFieldService offre un catalogo per i clienti del linguaggio di query di Google Ads con metadati su tutte le risorse di segmenti e metriche, nonché le rispettive relazioni e la disponibilità in ogni clausola come definito di seguito. Per ulteriori dettagli, consulta la documentazione di GoogleAdsField.

Clausole

Video: compatibilità sul campo GAQL

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 è obbligatorio in una query.

La seguente query di esempio mostra un esempio di selezione degli attributi per un determinato 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 per i seguenti motivi restrizioni:

• Campi di query non selezionabili. Questi campi avranno i loro Attributo di metadati Selectable contrassegnato come false.
• Selezione degli attributi dei campi ripetuti. Questi campi avranno i loro Attributo di metadati isRepeated contrassegnato come true.
• Selezione dei campi non disponibili per la risorsa specificata in FROM una clausola. Gli attributi di alcune risorse non possono essere selezionati insieme, inoltre viene selezionato il sottoinsieme di tutte le metriche e i segmenti sarà disponibile per la risorsa nel FROM.
• Selezione di segmenti o metriche non compatibili tra loro. Per ulteriori informazioni al riguardo, consulta di segmentazione.

Le informazioni relative alle condizioni di cui sopra sono disponibili nei nostri documenti di riferimento o da GoogleAdsFieldService.

FROM

La clausola FROM specifica la risorsa principale che verrà restituita. La della clausola FROM definisce quali campi possono essere utilizzati tutti per una determinata query. È possibile specificare una sola risorsa nel FROM. La clausola FROM è obbligatoria in una query per GoogleAdsService Ricerca o Stream di ricerca ma non deve essere specificato quando si utilizza il metodo GoogleAdsFieldService

Sebbene nella clausola FROM possa esistere una sola risorsa per una determinata query, i campi da Risorse attribuite. Queste risorse sono unito implicitamente alla risorsa nella clausola FROM, quindi devi solo aggiungere i propri attributi alla clausola SELECT per restituire i valori corrispondenti. Non tutte risorse hanno Risorse attribuite. Nell'esempio seguente puoi richiedere sia l'ID gruppo di annunci sia l'ID campagna dei 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 nel risposta nonostante non sia stata selezionata 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 il 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 agirà come un segmento.

WHERE

La clausola WHERE specifica le condizioni da applicare quando si filtrano i dati per l'elemento richiesta. Quando utilizzi la clausola WHERE, è possibile specificare una o più condizioni utilizzando AND per separarli. 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 periodo:

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 richiedere il numero di clic per tutte le campagne con impressioni su dispositivi mobili in gli 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 il valore-chiave i seguenti segmenti di data, chiamati segmenti di data principali, essendo un'eccezione:

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

Nella query seguente, nota che è selezionata l'opzione segments.date. Poiché questo segmento è un segmento di data principale, richiede una data limitata composto da segmenti di date principali da fornire 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 sopra indicata sono: segments.date, segments.week, segmenti.mese, segmenti.quarto e segmenti.anno. Se uno di questi segmenti almeno uno di questi valori deve essere utilizzato 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 in una condizione di singolo operatore (WHERE segments.device != "DESKTOP" AND "MOBILE"),

Quando filtri, è importante tenere presente la sensibilità alle maiuscole dell'operatore mente. Per ulteriori dettagli, consulta Sensibilità alle maiuscole.

Per un elenco completo degli operatori, consulta le language grammaticale.

ORDER BY

La clausola ORDER BY specifica l'ordine in cui devono essere visualizzati i risultati restituito. Questa opzione ti consente di 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 vengono specificati né ASC né DESC, i valori predefiniti dell'ordine a ASC. La clausola ORDER BY è facoltativa in una query.

La seguente query ordina le campagne restituite in base al numero di clic da cui in ordine decrescente:

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

Puoi specificare più campi nella clausola ORDER BY utilizzando una virgola dall'elenco di lettura. L'ordinamento verrà applicato nella stessa sequenza specificata nella query. Ad esempio, se selezioni i dati del gruppo di annunci in questa query, i risultati verranno ordinati in ordine crescente per nome della campagna, poi in ordine decrescente per numero di impressioni e, 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. È utile se sei interessato solo a un riepilogo.

Ad esempio, LIMIT può essere utilizzato per limitare il numero totale di risultati per 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 delle GoogleAdsService.Search a gestire lunghi elenchi di risultati.

PARAMETRI

La clausola PARAMETERS consente di specificare 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 bozze di entità. Il valore predefinito è false.

Ad esempio, la seguente query recupera le bozze di campagna insieme alle campagne:

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 ogni tipo di risorsa nella risposta non 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 l'aggiornamento o la rimozione operazioni, ti consigliamo di impostare questa opzione su false risorse senza nomi di risorse non possono essere utilizzate nelle operazioni di modifica. Se imposti questa opzione per true, assicurati di richiedere esplicitamente i nomi delle risorse la risorsa principale e tutte le risorse degli attributi recuperate mediante la query.

Esempi di omit_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name Per impostazione predefinita di omit_unselected_resource_names è impostato il valore false, quindi vengono restituiti tutti i campi resource_name.
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 richiesti nell'ambito SELECT.

Regole lingua aggiuntive

Oltre agli esempi per ogni clausola, il linguaggio di query di Google Ads prevede le seguenti comportamenti utilizzabili:

• Non è necessario che il campo della risorsa principale si trovi nel campo SELECT. una clausola per una query. Ad esempio, potresti voler utilizzare solo uno o più campi delle risorse 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. nessun altro campo dalla risorsa sono obbligatori nella query:

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

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

  SELECT segments.device FROM campaign
  

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

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