Estrutura da consulta

As consultas para os campos de recurso, segmento e métrica podem ser enviadas ao GoogleAdsService Pesquisa ou SearchStream métodos. Para criar uma consulta na Linguagem de consulta do Google Ads, você precisará criá-la usando o gramática do idioma. Uma consulta é composta por uma série de cláusulas:

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

Elas usam nomes de campos, nomes de recursos, operadores, condições e orderings para ajudar a selecionar os dados corretos. Depois de combinados em um único uma solicitação pode ser feita usando a API Google Ads.

Importante: o GoogleAdsFieldService fornece um catálogo para clientes da Linguagem de consulta do Google Ads com metadados sobre todos os recursos campos de segmento, campos de segmento e métricas, bem como seus relacionamentos com cada e a disponibilidade em cada cláusula, conforme definido abaixo. Para mais detalhes, consulte a documentação de GoogleAdsField.

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 recurso, campos de segmento e métricas, retornando os valores na resposta. A cláusula SELECT é obrigatório em uma consulta.

A amostra 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 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 aos seguintes restrições:

• Consulta de campos que não são selecionáveis. Esses campos terão O atributo de metadados Selectable foi marcado como false.
• Seleção de atributos de campos repetidos. Esses campos terão O atributo de metadados isRepeated foi marcado como true.
• Selecionar campos que não estão disponíveis para o recurso especificado no 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 no cláusula FROM.
• Selecionar segmentos ou métricas que não são compatíveis entre si. Para mais informações sobre isso, consulte a seção de segmentação.

Informações relacionadas às condições acima podem ser encontradas em nossos documentos de referência ou de GoogleAdsFieldService.

FROM

A cláusula FROM especifica o recurso principal que será retornado. A na cláusula FROM define quais campos podem ser usados todos os outros para a consulta em questão. Somente um recurso pode ser especificado no cláusula FROM. A cláusula FROM é obrigatória em uma consulta para o GoogleAdsService Pesquisa ou Stream de pesquisa métodos, no entanto, ele não deve ser especificado 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 associadas ao recurso na cláusula FROM, então você só precisa adicionam os atributos à cláusula SELECT para retornar os valores. Nem todas recursos têm recursos atribuídos. No exemplo a seguir, é possível 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 no apesar de não terem sido explicitamente selecionados 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 do seguinte consulta:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Ponto-chave: se o recurso na cláusula FROM listar outro recurso como um segment. Depois, a seleção de qualquer atributo desse recurso funcionará como um segmento.

WHERE

A cláusula WHERE especifica as condições a serem aplicadas ao filtrar dados para os solicitação. Ao usar a cláusula WHERE, é possível especificar uma ou mais condições usando AND para separá-los. Cada condição deve seguir o padrão field_name Operator value: A cláusula WHERE é opcional em uma consulta.

Este é um exemplo de como usar WHERE para retornar métricas de um determinado período 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. Neste exemplo, solicitar o número de cliques para todas as campanhas com impressões em dispositivos móveis no 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 o segmentos de data seguintes, 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 este segmento é de data principal, ele requer uma data finita período composto por segmentos de datas principais na cláusula WHERE a ser 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, segmentos.mês, segmentos.semestre e segmentos.ano. Se algum desses segmentos forem selecionadas, pelo menos uma delas precisa ser usada na cláusula WHERE.

Importante: o separador AND só pode ser usado entre as condições do operador (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), e não em uma única condição de operador (WHERE segments.device != "DESKTOP" AND "MOBILE"),

Ao filtrar, é importante ter em mente a diferenciação entre maiúsculas e minúsculas do operador em mente. Consulte mais detalhes em Diferenciação entre maiúsculas e minúsculas.

Para obter uma lista completa de operadores, consulte a seção language gramática.

ORDER BY

A cláusula ORDER BY especifica a ordem em que os resultados serão retornados. Assim, é possível organizar os dados em ordem crescente ou decrescente. com base em um nome de campo. Cada ordenação é especificada como uma field_name seguida por ASC ou DESC. Se ASC e DESC não forem especificados, a ordem será padronizada para ASC. A cláusula ORDER BY é opcional em uma consulta.

A consulta a seguir ordena as campanhas retornadas pelo número de cliques de maior para 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 string separada por vírgulas lista. A ordenação ocorrerá na mesma sequência especificada na consulta. Por exemplo, na consulta que seleciona dados do grupo de anúncios, os resultados serão classificados em ordem crescente pelo nome da campanha e, em seguida, em ordem decrescente pelo número de impressões e, em seguida, 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ê estiver interessado apenas em um resumo.

Por exemplo, LIMIT pode ser usado para restringir o número total de resultados para o seguinte consulta:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

Importante: LIMIT permite truncar os resultados. Use o campo page_size do GoogleAdsService.Search para lidar com longas listas de resultados.

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. O valor padrão é false.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

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

Observação: se você planeja usar qualquer um dos objetos retornados para atualizar ou remover de serviço, recomendamos definir essa opção como false, pois Recursos sem nomes não podem ser usados em operações mutate. Se você definir esta opção para true, solicite explicitamente os nomes dos recursos de ambos o recurso principal e todos os recursos de atributo buscados usando a consulta.

Exemplos de omit_unselected_resource_names
SELECT campaign.name, customer.id FROM campaign	Returned resources: e campaign.resource_name customer.resource_name O padrão de omit_unselected_resource_names é false. Portanto, todos os campos resource_name serão retornados.
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: e Nenhum. omit_unselected_resource_names foi 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: e campaign.resource_name omit_unselected_resource_names é especificado como true. e campaign.resource_name solicitados como parte do SELECT.

Outras regras de linguagem

Além dos exemplos de cada cláusula, a Linguagem de consulta do Google Ads tem as seguintes que podem ser usados:

• Não é obrigatório que o campo de recurso principal esteja em SELECT. para uma consulta. Por exemplo, talvez você queira usar apenas um ou mais campos de recurso 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 são necessárias 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 complementar ou métricas:

  SELECT segments.device FROM campaign
  

• O campo resource_name (campaign.resource_name, por exemplo) pode ser usados para filtrar ou ordenar dados:

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