Linguagem de consulta do Google Ads

A linguagem de consulta do Google Ads pode consultar a API do Google Ads para

Recursos e seus atributos, segmentos e métricas relacionados usando o
GoogleAdsService Pesquisa ou SearchStream
O resultado de uma consulta do GoogleAdsService é uma lista de instâncias de GoogleAdsRow, com cada GoogleAdsRow que representam um recurso. Se algum atributo ou métrica for solicitado, o também inclui esses campos. Se algum segmento for solicitado, o a resposta também mostra uma linha adicional para cada tupla de recurso de segmento.
Metadados sobre campos e recursos disponíveis em
GoogleAdsFieldService

Esse serviço oferece um catálogo de campos para consulta com detalhes sobre a compatibilidade e o tipo.

O resultado de uma consulta GoogleAdsFieldService é uma lista de instâncias de GoogleAdsField, com cada GoogleAdsField contendo detalhes sobre o campo solicitado.

Consultar atributos de um recurso

Veja abaixo uma consulta básica para atributos do recurso de campanha, ilustrando como para retornar o ID, o nome e o status da campanha:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

Essa consulta ordena pelo ID da campanha. Cada GoogleAdsRow resultante representaria um objeto campaign preenchido com os campos selecionados (incluindo o resource_name da campanha).

Para descobrir quais outros campos estão disponíveis para consultas de campanha, consulte o Documentação de referência do Campaign.

Consultar métricas

Além dos atributos selecionados para um determinado recurso, também é possível consultar métricas relacionadas:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

Essa consulta filtra apenas as campanhas com status PAUSED e tiveram mais de 1.000 impressões, enquanto faz a ordenação por ID da campanha. Cada O GoogleAdsRow resultante teria um campo metrics preenchido com o métricas selecionadas.

Para uma lista de métricas consultáveis, acesse a Metrics na documentação do Google.

Consultar segmentos

Além dos atributos selecionados para um determinado recurso, também é possível consultar segmentos relacionados:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

Semelhante à consulta de métricas, essa consulta filtra somente as campanhas que ter o status PAUSED e ter recebido mais de 1.000 impressões; No entanto, essa consulta segmenta os dados por data. Isso leva a cada resultado GoogleAdsRow, que representa uma tupla de uma campanha e a data Segment. Está é importante observar que a segmentação divide as métricas selecionadas, segmento na cláusula SELECT.

Para ver uma lista de segmentos que podem ser consultados, consulte a Segments na documentação do Google.

Na consulta de um determinado recurso, é possível mesclar com outros se disponíveis. Esses recursos relacionados são conhecidos como recursos". É possível mesclar com recursos atribuídos implicitamente selecionando um na consulta.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

Essa consulta não apenas seleciona atributos de campanha, mas também extrai informações de cada campanha selecionada. Cada GoogleAdsRow resultante representa um objeto campaign preenchido com os atributos de campanha selecionados, bem como o atributo de estratégia de lances bidding_strategy.name selecionado.

Para descobrir quais recursos atribuídos estão disponíveis para consultas de campanha, consulte a documentação de referência do Campaign.

Mutação com base nos resultados da consulta

Ao consultar um determinado recurso, você pode pegar imediatamente aqueles retornados resultados como objetos, modificá-los e enviá-los de volta ao método mutate serviço do recurso. Confira abaixo um exemplo de fluxo de trabalho:

  1. Execute uma consulta para todas as campanhas que atualmente estão PAUSED e têm impressões acima de 1.000.
  2. Consiga o objeto Campaign do campo campaign de cada GoogleAdsRow em a resposta.
  3. Altere o status de cada campanha de PAUSED para ENABLED.
  4. Chamar CampaignService.MutateCampaigns com as campanhas modificadas para atualizá-las.

Metadados de campo

As consultas enviadas a GoogleAdsFieldService servem para recuperar metadados do campo. Essas informações podem ser usadas para entender como os campos podem ser usados juntos em uma consulta. Como os dados são disponibilizados na API e fornecem as metadados necessários para validar ou criar uma consulta, isso permite que os desenvolvedores façam de forma programática. Confira consulta típica para metadados:

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

É possível substituir <INSERT_RESOURCE_OR_FIELD> nessa consulta por uma recurso (como customer ou campaign) ou campo (como campaign.id, metrics.impressions ou ad_group.id).

Para ver uma lista de campos consultáveis, consulte a GoogleAdsField na documentação do Google.

Exemplos de código

As bibliotecas de cliente têm exemplos de como usar a Linguagem de consulta do Google Ads em GoogleAdsService. A pasta de operações básicas como GetCampaigns, GetKeywords e SearchForGoogleAdsFields. A pasta reporting tem um exemplo de GetKeywordStats.

Próxima
Gramática das consultas