Estrutura da consulta

As consultas para campos de recurso, segmento e métrica podem ser enviadas para os métodos GoogleAdsService de Pesquisa ou SearchStream. Para criar uma consulta na linguagem de consulta do Google Ads, você precisa criá-la usando a gramática da linguagem. Ela é composta por várias cláusulas:

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

As cláusulas usam nomes de campo, nomes de recursos, operadores, condições e ordens para ajudar você a selecionar os dados corretos. Uma vez combinada com uma única consulta, é possível fazer uma solicitação usando a API Google Ads.

Cláusulas

ondemand_video Vídeo: compatibilidade com o campo GAQL

SELECIONAR

A cláusula SELECT especifica um conjunto de campos a serem buscados na solicitação. SELECT pega uma lista separada por vírgulas de campos de recurso, campos de segmento e métricas, retornando os valores na resposta. A cláusula SELECT é obrigatória em uma consulta.

O exemplo de consulta abaixo mostra 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 recurso

  • campaign.id
  • campaign.name

• Campos de recurso

  • bidding_strategy.id
  • bidding_strategy.name

• Campos de segmento

  • 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:

• Consultar campos que não são selecionáveis. Esses campos terão o atributo de metadados Selectable marcado como false.
• Seleção de atributos de campos repetidos. Esses campos terão o atributo de metadados isRepeated marcado como true.
• Seleção de 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, apenas um subconjunto de todas as métricas e segmentos estará disponível para o recurso na cláusula FROM.
• Selecionar segmentos ou métricas nã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 com todas as outras cláusulas para a consulta especificada. Somente um único 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 precisa ser especificada ao usar a GoogleAdsFieldService.

Apenas um recurso pode existir na cláusula FROM para uma determinada consulta, mas campos de recursos atribuídos também podem estar disponíveis. Esses recursos são mesclados implicitamente ao recurso na cláusula FROM. Assim, você só precisa adicionar os atributos à cláusula SELECT para retornar os valores deles. Nem todos os recursos têm recursos atribuídos. No exemplo a seguir, você pode solicitar o ID do grupo de anúncios e o ID 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 que não seja selecionado explicitamente na consulta:

SELECT ad_group.id
FROM ad_group

O mesmo acontece em outros recursos quando pelo menos um campo está selecionado. Por exemplo: campaign.resource_name será incluído na resposta para a 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. Esse exemplo solicitará 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 principais, sendo as exceções:

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

Na consulta a seguir, observe que segments.date está selecionado. Por ser um segmento de data principal, ele precisa de um período finito composto de segmentos de datas principais na cláusula WHERE.

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: segmentos.data, segmentos.semana, segmentos.mês, segmentos.trimestre e segmentos.ano. Se qualquer um desses segmentos for selecionado, pelo menos um deles precisará ser usado na cláusula WHERE.

Ao filtrar, a distinção entre maiúsculas e minúsculas do operador é importante. Consulte Diferenciação entre maiúsculas e minúsculas para mais detalhes.

Para ver uma lista completa de operadores, consulte o grammar de linguagem.

ORDER BY

A cláusula ORDER BY especifica a ordem em que os resultados serão retornados. Isso permite organizar os dados em ordem crescente ou decrescente com base no nome do campo. Cada ordenação é especificada como um field_name seguido por ASC ou DESC. Se nem ASC nem DESC forem especificados, a ordem será definida como 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 da maior para a 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 ordem vai ocorrer na mesma sequência especificada na consulta. Por exemplo, nesta consulta selecionando dados do grupo de anúncios, os resultados serão classificados em ordem crescente por nome da campanha, em ordem decrescente por número de impressões e em ordem decrescente por 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ê tem interesse 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 metaparâmetros para a solicitação. Esses parâmetros podem afetar os tipos de linhas retornados.

Atualmente, os seguintes parâmetros meta são suportados:

include_rascunhos

Defina include_drafts como true para permitir que entidades de rascunho sejam retornadas. O valor padrão é false.

Por exemplo, a consulta a seguir busca campanhas de rascunho com campanhas normais:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselect_resource_names

Defina omit_unselected_resource_names como true para evitar que o nome do recurso de cada tipo de recurso na resposta seja retornado, a menos que explicitamente solicitado na cláusula SELECT. O padrão é false.

SELECT
  campaign.name,
  customer.id
FROM campaign

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

Outras regras de idioma

Além dos exemplos para cada cláusula, a linguagem de consulta do Google Ads tem os seguintes comportamentos que podem ser utilizados:

• O campo principal de recurso não precisa estar na cláusula SELECT de uma consulta. Por exemplo, talvez você queira usar apenas um ou mais campos de recursos 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.costMicros
  FROM campaign
  

• Os campos de segmentação podem ser selecionados sem os campos ou métricas de recurso acompanhados:

  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'