Linguagem de consulta do Google Ads

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

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

Esse serviço fornece 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 GoogleAdsField, com cada GoogleAdsField contendo detalhes sobre o campo solicitado.

Como consultar atributos de um recurso

Confira abaixo uma consulta básica para atributos do recurso da campanha, que ilustra como 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 é ordenada por ID da campanha. Cada GoogleAdsRow resultante representa um objeto campaign preenchido com os campos selecionados, incluindo o resource_name fornecido da campanha.

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

Como 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 somente as campanhas que têm um status de PAUSED e tiveram mais de 1.000 impressões, enquanto organizavam por ID da campanha. Cada GoogleAdsRow resultante teria um campo metrics preenchido com as métricas selecionadas.

Para ver uma lista de métricas consultáveis, consulte a documentação Metrics.

Como consultar segmentos

Além dos atributos selecionados para um determinado recurso, você também pode 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 têm um status de PAUSED e tiveram mais de 1.000 impressões. No entanto, essa consulta segmenta os dados por data. Isso leva a cada GoogleAdsRow resultante que representa uma tupla de uma campanha e a data Segment. É importante observar que a segmentação divide as métricas selecionadas, agrupando por cada segmento na cláusula SELECT.

Para conferir uma lista de segmentos consultáveis, consulte a documentação Segments.

Em uma consulta para um determinado recurso, é possível mesclar com outros recursos relacionados, se disponíveis. Esses recursos relacionados são conhecidos como "recursos atribuídos". É possível mesclar os recursos atribuídos de maneira implícita selecionando um atributo 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 da campanha, mas também extrai atributos relacionados 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 selecionado bidding_strategy.name.

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

Mudança com base nos resultados da consulta

Ao consultar um determinado recurso, você pode utilizar imediatamente os resultados retornados como objetos, modificá-los e enviá-los de volta ao método mutação no serviço desse recurso. Veja abaixo um exemplo de fluxo de trabalho:

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

Metadados de campo

As consultas enviadas para GoogleAdsFieldService têm como objetivo recuperar metadados de campo. Essas informações podem ser usadas para entender como os campos podem ser usados juntos em uma consulta. Como os dados estão disponíveis na API e fornecem os metadados necessários para validar ou criar uma consulta, isso permite que os desenvolvedores façam isso de maneira programática. Veja uma 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 um recurso (como customer ou campaign) ou um campo (como campaign.id, metrics.impressions ou ad_group.id).

Para conferir uma lista de campos consultáveis, consulte a documentação GoogleAdsField.

Exemplos de código

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

Próxima
Gramática das consultas