A nova API Search Ads 360 Reporting já está disponível. Participe do grupo do Google searchads-api-announcements para ficar por dentro das próximas melhorias e versões.

Esta página foi traduzida pela API Cloud Translation.

Estrutura e cláusulas de consulta

Uma consulta é composta por uma série de cláusulas: SELECT, FROM, WHERE, ORDER BY, LIMIT, e PARAMETERS.

As cláusulas usam nomes de campos, nomes de recursos, operadores, condições, e orderings, que se combinam em uma única solicitação de consulta.

Em termos básicos, para criar uma consulta:

Especifique um recurso a partir do qual os dados serão recuperados.
Adicione campos e métricas para definir os dados que você quer retornar.
Adicione segmentos para agrupar seus resultados.
Adicione recursos atribuídos para mesclar implicitamente dados de recursos relacionados.
Filtre, ordene e limite os resultados.

Cláusula `SELECT`

A cláusula SELECT:

é uma cláusula obrigatória em uma consulta;
Especifica um conjunto de campos a serem buscados na solicitação.
Usa uma lista separada por vírgulas de campos de recursos, colunas personalizadas, variáveis do Floodlight, campos de segmento e métricas e retorna os valores na resposta.

Esta consulta de exemplo mostra como selecionar atributos do campaign recurso:

SELECT
  campaign.id,
  campaign.name
FROM campaign

Vários tipos de campo

É possível pedir diferentes tipos de campo na mesma solicitação.

O exemplo de consulta abaixo mostra uma única consulta com uma combinação de:

Campos de recurso: campaign.id, campaign.name, bidding_strategy.id e bidding_strategy.name.
Campos de segmento: segments.device e segments.date.
Campos de métricas: metrics.impressions e metrics.clicks.

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

Consulte Segmentação. para saber mais sobre como segmentar seus relatórios de pesquisa.

Campo de recurso principal

Normalmente, o campo de recurso principal é incluído no SELECT mas isso é opcional (não é obrigatório).

Esta consulta de exemplo usa um campo de recurso principal (ad_group.status) para filtrar apenas os resultados.

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

Variáveis personalizadas do Floodlight

É possível incluir variáveis personalizadas do Floodlight na cláusula SELECT usando IDs.

Neste exemplo, a consulta inclui uma variável personalizada com ID 123454321 para o recurso de campanha.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

Colunas personalizadas

É possível incluir colunas personalizadas na cláusula SELECT usando seus IDs.

Neste exemplo, a consulta inclui uma coluna personalizada withID 12345678 para o recurso de campanha.

SELECT
  custom_columns.id[12345678]
FROM campaign

Saiba como conseguir IDs de colunas personalizadas.

Campos de métricas

É possível selecionar campos de métricas para um determinado recurso sem incluir nenhum outro campos do recurso na cláusula SELECT.

Esta consulta de exemplo seleciona as métricas impressions e clicks para a campaign recurso.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

Consulte metrics para lista de campos de métricas que você pode usar em suas consultas.

Campos de segmentos

É possível selecionar campos de segmentos sem especificar os campos de recursos correspondentes ou métricas na cláusula SELECT.

Esta consulta de exemplo segmenta os resultados por dispositivo.

SELECT segments.device
FROM campaign

Consulte segments para lista de campos de segmentos que você pode usar em suas consultas.

Campos proibidos

Não é possível usar os seguintes campos na cláusula SELECT:

Campos não selecionáveis, ou seja, campos com os metadados Selectable marcado como false.
Campos repetidos, ou seja, campos com o atributo de metadados Repeated marcado como true.
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 alguns recursos disponibilizar um subconjunto de todas as métricas e segmentos.
Segmentos ou métricas incompatíveis. Consulte Segmentação para mais informações informações imprecisas ou inadequadas.

Consulte a Documentação de referência para detalhes sobre onde encontrar essas informações para cada recurso.

Cláusula FROM

A cláusula FROM:

É uma cláusula obrigatória para consultas a SearchAds360Service (ambos os métodos Search e SearchStream).
Não deve ser incluído em consultas a SearchAds360FieldService.
Especifica o recurso principal que a consulta retorna.
Só é possível especificar um recurso.
Define os campos que você pode usar em todas as outras cláusulas na consulta.

Recursos atribuídos

Se os recursos atribuídos estiverem disponíveis, eles serão implicitamente combinados com o o recurso especificado na cláusula FROM. Você só precisa adicionar os atributos à cláusula SELECT para retornar os valores.

Este exemplo de consulta retorna o ID do grupo de anúncios e o ID da campanha, porque campaign é um recurso atribuído do ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Campo `resource_name`

O campo resource_name do recurso principal na cláusula FROM é sempre retornados.

Nesta consulta de exemplo, ad_group.resource_name será incluído na resposta mesmo que não esteja explicitamente selecionado na consulta:

SELECT ad_group.id
FROM ad_group

O campo resource_name de um recurso atribuído é retornado quando pelo menos um campo é selecionado.

Nesta consulta de exemplo, campaign.resource_name será incluído no resposta porque campaign.id está selecionado:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

Cláusula WHERE

A cláusula WHERE:

é uma cláusula opcional em uma consulta;
Especifica condições para filtrar e segmentar os dados da solicitação. As condições seguem este padrão: FIELD_NAME OPERATOR VALUE (separados por ou espaços em branco).
Pode incluir várias condições separadas pelo separador AND.

Esta consulta de exemplo mostra como usar a cláusula WHERE para retornar impressions métricas de um determinado período:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Consulte Segmentação. para saber mais sobre como segmentar seus relatórios de pesquisa.

Consulte Períodos para saber mais sobre como especificar datas intervalos nas suas consultas.

Filtrar por campo `resource_name`

Use o campo resource_name para filtrar ou ordenar dados.

Esta consulta de exemplo usa o campo campaign.resource_name para filtrar os resultados por uma determinada campanha:

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

Várias condições

Você pode combinar várias condições para filtrar os dados.

Esta consulta de exemplo solicita o número de métricas clicks para todas as campanhas com métricas de impressions 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

Consulte Segmentação. para saber mais sobre a segmentação dos seus relatórios.

Diferenciação entre maiúsculas e minúsculas

Ao filtrar por valores de string, a diferenciação de maiúsculas e minúsculas padrão de cada operador desempenha um papel importante na filtragem correta dos resultados.

A tabela a seguir mostra a diferenciação de maiúsculas e minúsculas padrão de cada operador.

Diferenciação de maiúsculas e minúsculas padrão
`=/!=`	`Case sensitive`
`IN/NOT IN`	`Case sensitive`
`LIKE/NOT LIKE`	`Case insensitive`
`CONTAINS (...)`	`Case sensitive`
`REGEXP_MATCH/NOT REGEXP_MATCH`	`Case sensitive`

Você pode usar o modificador (?i) para mudar a sensibilidade padrão de REGEXP_MATCH e NOT REGEXP_MATCH para não diferenciar maiúsculas de minúsculas, por exemplo:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

Consulte Referência de gramática de consulta para uma lista completa de operadores que podem ser usados para filtrar os dados.

Principais segmentos de data

Os campos de segmentos a seguir são conhecidos como segmentos de data principal: segments.date, segments.week, segments.month, segments.quarter e segments.year.

É possível usar segmentos de data principais na cláusula WHERE para especificar uma data ou hora. período

Esta consulta de exemplo especifica DURING LAST_30_DAYS para o campo segments.date. na cláusula WHERE:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

Consulte Segmentação > Principais segmentos de data para detalhes informações sobre o uso de segmentos de data principais.

Filtragem proibida

A filtragem não é permitida:

Em campos de segmento não selecionados, exceto para segmentos de data principal
Em campos de qualquer tipo de mensagem, exceto primitivos (por exemplo, Int64Value, StringValue etc.).
Em atributos de campos repetidos de qualquer tipo de mensagem, exceto primitivos Por exemplo, Int64Value, StringValue etc.

Cláusula ORDER BY

A cláusula ORDER BY:

é uma cláusula opcional em uma consulta;
Especifica a ordem em que os resultados são retornados. A ordem segue esta estampa: FIELD_NAME ORDERING_OPTION (separados por um espaço em branco).
Permite duas opções: ASC (crescente) ou DESC (decrescente). O padrão é crescente.

Esta consulta de exemplo ordena as campanhas por número de cliques em ordem decrescente (do maior para o menor):

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

Vários pedidos

É possível especificar vários campos na cláusula ORDER BY usando uma string separada por vírgulas lista. Os resultados serão ordenados na mesma sequência que você especificar no consulta.

Essa consulta de exemplo seleciona os dados do grupo de anúncios e classifica os resultados em ordem crescente classificar por nome de campanha, em ordem decrescente por número de impressões, e e depois 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

Combinar ordem e limite

É possível usar a cláusula ORDER BY com a cláusula LIMIT para e refinar seus resultados.

Esta consulta de exemplo retorna as cinco campanhas com o maior número de impressões nos últimos 30 dias:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

Pedidos proibidos

Não é permitido ordenar:

Por atributos de recursos não selecionados.
Por métricas não selecionadas.
Por segmentos não selecionados.
Para esses tipos de campo:
- MESSAGE
- Campos repetidos
- Atributos de campos repetidos.

Cláusula LIMIT

A cláusula LIMIT:

é uma cláusula opcional em uma consulta;
Permite limitar o número de resultados retornados pela consulta.

Essa cláusula é útil, por exemplo, se você só está interessado em uma amostra ou resumo dos resultados.

Esta consulta de exemplo limita o número total de resultados a 50:

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

Cláusula PARAMETERS

A cláusula PARAMETERS permite especificar parâmetros meta para a solicitação.

Incluir rascunhos

O parâmetro include_drafts controla se as entidades de rascunho são incluídas na os resultados. O padrão é false. Defina-o como true para incluir entidades de rascunho.

Esta consulta de exemplo retorna campanhas de rascunho e campanhas normais:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

Omitir `resource_name` não selecionado

O parâmetro omit_unselected_resource_names permite excluir a resource_name de todos os recursos que não são explicitamente solicitados no seu cláusula SELECT. O padrão é false. Se você definir esse parâmetro como true, é recomendado solicitar explicitamente o nome do recurso principal e todos os recursos atribuídos na cláusula SELECT.

Esta consulta de exemplo não retorna campaign.resource_name nem o customer.resource_name, porque não estão incluídos no SELECT cláusula:

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

Esta consulta de exemplo retorna o campo campaign.resource_name, porque ele é explicitamente solicitado na cláusula SELECT:

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

Mudar a moeda usada nas métricas

O parâmetro metrics_currency permite especificar a moeda a ser usada. ao calcular uma métrica incluída na cláusula SELECT. O padrão é usar a moeda local da conta. Se você definir isso é preciso usar o código de moeda de três caracteres ISO 4217. Por exemplo: USD, EUR.

Esta consulta de exemplo retorna a métrica cost_micros na moeda local do do Compute Engine.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

Esta consulta de exemplo retorna a métrica cost_micros em pesos chilenos (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

Saiba mais

Gramática das consultas