A linguagem de consulta do Google Ads pode consultar a API Google Ads para
- Recursos e os atributos, segmentos e métricas relacionados usando
GoogleAdsService
Pesquisa ou SearchStream- O resultado de uma consulta GoogleAdsService é uma lista de instâncias
GoogleAdsRow
, em que cadaGoogleAdsRow
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 de recurso de segmento. - Metadados sobre campos e recursos disponíveis em
GoogleAdsFieldService
Esse serviço fornece um catálogo de campos consultáveis com detalhes sobre a compatibilidade e o tipo.
O resultado de uma consulta
GoogleAdsFieldService
é uma lista de instânciasGoogleAdsField
, em que cadaGoogleAdsField
contém detalhes sobre o campo solicitado.
Consultar atributos de um recurso
Esta é uma consulta básica para os 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 ordena por ID de 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 Campaign
.
Consultar métricas
Além dos atributos selecionados para um determinado recurso, também é possível consultar as 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 que têm um status de PAUSED
e tiveram mais de 1.000 impressões, ao ordenar por ID de 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 do
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
Semelhante à consulta de métricas, essa consulta filtra apenas 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 resultado GoogleAdsRow
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 ver uma lista de segmentos consultáveis, consulte a documentação
do Segments
.
Consultar atributos de um recurso relacionado
Em uma consulta de um determinado recurso, talvez seja possível mesclar com outros recursos relacionados, se disponível. Esses recursos relacionados são conhecidos como "recursos atribuídos" É possível mesclar recursos atribuídos implicitamente selecionando um atributo na sua consulta.
SELECT
campaign.id,
campaign.name,
campaign.status,
bidding_strategy.name
FROM campaign
ORDER BY campaign.id
Essa consulta não só 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 bidding_strategy.name
da estratégia de lances selecionada.
Para descobrir quais recursos atribuídos estão disponíveis para consultas da campanha, consulte a documentação de referência do Campaign
.
Mutação com base nos resultados da consulta
Ao consultar um determinado recurso, é possível usar imediatamente os resultados retornados como objetos, modificá-los e enviá-los de volta ao método mut no serviço desse recurso. Veja abaixo um exemplo de fluxo de trabalho:
- Execute uma consulta para todas as campanhas que estão atualmente
PAUSED
e têm impressões maiores que 1.000. - Consiga o objeto
Campaign
do campocampaign
de cadaGoogleAdsRow
na resposta. - Mude o status de cada campanha de
PAUSED
paraENABLED
. - Chame
CampaignService.MutateCampaigns
com as campanhas modificadas para atualizá-las.
Metadados do campo
As consultas enviadas para GoogleAdsFieldService
foram feitas para recuperar metadados de campo.
Essas informações podem ser utilizadas 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 conseguem fazer isso de maneira programática. Veja a seguir 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 um campo (como campaign.id
, metrics.impressions
ou ad_group.id
).
Para ver uma lista de campos que podem ser consultados, consulte a documentação do
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 de operações básicas tem
exemplos como GetCampaigns
, GetKeywords
e SearchForGoogleAdsFields
.
A pasta reporting tem um exemplo de GetKeywordStats
.