Linguagem de consulta do Google Ads

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

Recursos e atributos, segmentos e métricas relacionados usando

GoogleAdsService Search ou SearchStream

O resultado de uma consulta do GoogleAdsService é uma lista de instâncias GoogleAdsRow, em que cada GoogleAdsRow representa um recurso. Se algum atributo ou métrica for solicitado, a linha também vai incluir esses campos. Se algum segmento for solicitado, a resposta também vai mostrar uma linha extra para cada tupla de recurso de segmento.

Metadados sobre os campos e recursos disponíveis em

GoogleAdsFieldService

Esse serviço fornece um catálogo de campos pesquisáveis com detalhes sobre a compatibilidade e o tipo deles.

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

Consultar atributos de recursos

Confira abaixo uma consulta básica para atributos do recurso de 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 da campanha.

Para descobrir quais outros campos estão disponíveis para consultas de campanhas, consulte a 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 mais de 1.000 impressões, ordenando por ID da campanha. Cada GoogleAdsRow resultante teria um campo metrics preenchido com as métricas selecionadas.

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

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

Assim como as consultas de métricas, essa consulta filtra apenas as campanhas que têm um status de PAUSED e mais de 1.000 impressões. No entanto, essa consulta segmenta os dados por data. Isso leva a cada GoogleAdsRow resultante a representar uma tupla de uma campanha e a data Segment. A segmentação divide as métricas selecionadas, agrupando-as por cada segmento na cláusula SELECT.

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

Consultar atributos de um recurso relacionado

Em uma consulta para um determinado recurso, talvez seja possível fazer uma mesclagem com outros recursos relacionados, se disponíveis. Esses recursos relacionados são conhecidos como "recursos atribuídos". É possível fazer uma mesclagem implícita com recursos atribuídos 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 de campanha, mas também extrai atributos relacionados de cada campanha selecionada. Cada GoogleAdsRow resultante representa um objeto campaign preenchido com os atributos da campanha selecionados, além do atributo bidding_strategy.name da estratégia de lances selecionada.

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

Mutar com base nos resultados da consulta

Ao consultar um determinado recurso, é possível usar os resultados retornados como objetos, modificá-los e enviá-los de volta ao método de mutação no serviço desse recurso. Confira um exemplo de fluxo de trabalho:

1. Execute uma consulta para todas as campanhas que estão atualmente PAUSED e têm mais de 1.000 impressões.
2. Receba 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 do campo

As consultas enviadas para GoogleAdsFieldService são destinadas à recuperação de 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, os desenvolvedores podem fazer isso de forma programática. Confira uma consulta típica de 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 campo (como campaign.id, metrics.impressions ou ad_group.id).

Importante: não há uma cláusula FROM nesta consulta.

Para uma lista de campos pesquisá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 em GoogleAdsService. A pasta Operações básicas tem exemplos como GetCampaigns, GetKeywords e SearchForGoogleAdsFields.