As consultas dos campos de recurso, segmento e métrica podem ser enviadas para os métodos GoogleAdsService
Search ou SearchStream. Para criar uma consulta na linguagem de consulta do Google Ads, você precisa criá-la usando a gramática da linguagem. Uma consulta é composta de várias cláusulas:
SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS
As cláusulas usam nomes de campos, nomes de recursos, operadores, condições e ordens para ajudar você a selecionar os dados corretos. Depois de combinada em uma única consulta, é possível fazer uma solicitação usando a API Google Ads.
Cláusulas
Vídeo: compatibilidade de campos da GAQL
SELECT
A cláusula SELECT
especifica um conjunto de campos a serem buscados na solicitação.
SELECT
usa uma lista separada por vírgulas de campos de recursos, campos de segmento e métricas, retornando os valores na resposta. A cláusula SELECT
é obrigatória em uma consulta.
A amostra de consulta abaixo apresenta um exemplo de seleção de atributos para um determinado recurso:
SELECT
campaign.id,
campaign.name
FROM campaign
É possível solicitar diferentes tipos de campo em uma única solicitação, por exemplo:
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
Campos de recursos
campaign.id
campaign.name
Campos de recursos
bidding_strategy.id
bidding_strategy.name
Segmentar campos
segments.device
segments.date
Métricas
metrics.impressions
metrics.clicks
Alguns campos podem não ser permitidos na cláusula SELECT
, devido às seguintes
restrições:
- Consulta de campos que não são selecionáveis. Esses campos terão o atributo de metadados
Selectable
marcado comofalse
. - Seleção de atributos de campos repetidos. Esses campos terão o atributo de metadados
isRepeated
marcado comotrue
. - Selecionar campos que não estão disponíveis para o recurso especificado na cláusula
FROM
. Os atributos de alguns recursos não podem ser selecionados juntos. Além disso, apenas um subconjunto de todas as métricas e segmentos estará disponível para o recurso na cláusulaFROM
. - Selecionar segmentos ou métricas que não são compatíveis entre si. Para mais informações, consulte a seção de segmentação.
Informações relacionadas às condições acima podem ser encontradas em nossos documentos de referência ou em GoogleAdsFieldService
.
FROM
A cláusula FROM
especifica o recurso principal que será retornado. O recurso na cláusula FROM
define quais campos podem ser usados e todas as outras cláusulas da consulta especificada. Apenas um recurso pode ser especificado na cláusula FROM
. A cláusula FROM
é obrigatória em uma consulta para os métodos
GoogleAdsService
Search ou SearchStream.
No entanto, ela não deve ser especificada ao usar o
GoogleAdsFieldService
.
Embora apenas um recurso possa existir na cláusula FROM
para uma determinada consulta, os campos de Recursos atribuídos também podem estar disponíveis. Esses recursos são implicitamente unidos ao recurso na cláusula FROM
. Portanto, você só precisa adicionar os atributos deles à cláusula SELECT
para retornar os valores. Nem todos
os recursos têm recursos atribuídos. No exemplo a seguir, é possível solicitar os IDs do grupo de anúncios e da campanha dos grupos de anúncios:
SELECT
campaign.id,
ad_group.id
FROM ad_group
O campo resource_name
do recurso principal é sempre retornado.
No exemplo a seguir, ad_group.resource_name
será incluído na resposta, mesmo não sendo selecionado explicitamente na consulta:
SELECT ad_group.id
FROM ad_group
O mesmo acontece com outros recursos quando pelo menos um campo é selecionado.
Por exemplo: campaign.resource_name
será incluído na resposta da seguinte consulta:
SELECT
campaign.id,
ad_group.id
FROM ad_group
WHERE
A cláusula WHERE
especifica as condições a serem aplicadas ao filtrar dados para a solicitação. Ao usar a cláusula WHERE
, uma ou mais condições podem ser especificadas usando AND
para separá-las. Cada condição precisa seguir o padrão
field_name Operator value
. A cláusula WHERE
é opcional em uma consulta.
Veja a seguir um exemplo de como usar WHERE
para retornar métricas de um determinado período:
SELECT
campaign.id,
campaign.name,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
É possível combinar várias condições para filtrar os dados. Este exemplo solicita o número de cliques de todas as campanhas com impressões em dispositivos móveis nos últimos 30 dias.
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
Os segmentos na cláusula WHERE
precisam estar na cláusula SELECT
, com os seguintes segmentos de data, chamados de segmentos de data principal, sendo exceções:
segments.date
segments.week
segments.month
segments.quarter
segments.year
Na consulta a seguir, observe que segments.date
está selecionado.
Como esse segmento é um segmento de data principal, ele requer que um período finito composto por segmentos de data principais na cláusula WHERE
seja fornecido.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Todos os segmentos que atendem à condição acima são: segments.date, segments.week,
segments.month, segments.quarter e segments.year. Se algum desses segmentos for selecionado, pelo menos um deles precisará ser usado na cláusula WHERE
.
Ao filtrar, é importante ter em mente a diferenciação entre maiúsculas e minúsculas do operador. Consulte mais detalhes em Diferenciação entre maiúsculas e minúsculas.
Para uma lista completa de operadores, consulte a gramática da linguagem.
ORDER BY
Com a cláusula ORDER BY
, você especifica a ordem em que os resultados serão retornados. Isso permite organizar os dados em ordem crescente ou decrescente
com base no nome de um campo. Cada ordenação é especificada como field_name
seguida por
ASC
ou DESC
. Se ASC
e DESC
não forem especificados, a ordem será ASC
por padrão. A cláusula ORDER BY
é opcional em uma consulta.
A consulta a seguir ordena as campanhas retornadas pelo número de cliques, do maior para o menor:
SELECT
campaign.name,
metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC
É possível especificar vários campos na cláusula ORDER BY
usando uma lista separada por vírgulas. A ordenação ocorrerá na mesma sequência especificada na consulta.
Por exemplo, nesta consulta, ao selecionar dados do grupo de anúncios, os resultados serão classificados em ordem crescente pelo nome da campanha, em ordem decrescente pelo número de impressões e, por fim, em ordem decrescente pelo número de cliques:
SELECT
campaign.name,
ad_group.name,
metrics.impressions,
metrics.clicks
FROM ad_group
ORDER BY
campaign.name,
metrics.impressions DESC,
metrics.clicks DESC
LIMIT
A cláusula LIMIT
permite especificar o número de resultados a serem retornados.
Isso é útil se você estiver interessado apenas em um resumo.
Por exemplo, LIMIT
pode ser usado para restringir o número total de resultados para a seguinte consulta:
SELECT
campaign.name,
ad_group.name,
segments.device,
metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50
PARÂMETROS
A cláusula PARAMETERS
permite especificar parâmetros meta para a solicitação.
Esses parâmetros podem afetar os tipos de linhas retornadas.
Atualmente, há suporte para os seguintes parâmetros meta:
include_drafts
Defina include_drafts
como true
para permitir que entidades de rascunho sejam retornadas.
Por padrão, é configurado como false
.
Por exemplo, a consulta a seguir busca campanhas de rascunho com campanhas normais:
SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true
omit_unselected_resource_names
Defina omit_unselected_resource_names
como true
para evitar que o nome de recurso de cada tipo de recurso na resposta seja retornado, a menos que seja explicitamente solicitado na cláusula SELECT
. O padrão é false
.
Exemplos de omit_unselected_resource_names | |
---|---|
SELECT campaign.name, customer.id FROM campaign |
Returned resources:campaign.resource_name
omit_unselected_resource_names é definido como false por padrão. Portanto, todos os campos "resource_name" são retornados.
|
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resources: Nenhum. omit_unselected_resource_names é especificado como true ,
e campaign.resource_name e customer.resource_name
não fazem parte da cláusula SELECT .
|
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true |
Returned resource:campaign.resource_name
omit_unselected_resource_names é especificado como true e campaign.resource_name solicitados como parte da cláusula SELECT .
|
Outras regras de linguagem
Além dos exemplos de cada cláusula, a linguagem de consulta do Google Ads tem os seguintes comportamentos que podem ser utilizados:
Não é necessário que o campo de recurso principal esteja na cláusula
SELECT
para uma consulta. Por exemplo, você pode querer usar apenas um ou mais campos de recurso principais para filtrar dados:SELECT campaign.id FROM ad_group WHERE ad_group.status = PAUSED
As métricas podem ser selecionadas exclusivamente para um determinado recurso. Nenhum outro campo do recurso é necessário na consulta:
SELECT metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign
Os campos de segmentação podem ser selecionados sem nenhum campo de recurso ou métrica associado:
SELECT segments.device FROM campaign
O campo
resource_name
(campaign.resource_name
, por exemplo) pode ser usado para filtrar ou ordenar dados:SELECT campaign.id, campaign.name FROM campaign WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'