Este guia mapeia os conceitos e as convenções de nomenclatura de relatórios na interface do Google Ads para os relatórios que você pode gerar usando a linguagem de consulta do Google Ads (GAQL, na sigla em inglês) e a API Google Ads.
Termos comuns da interface
A tabela a seguir resume alguns dos termos comuns usados na interface e seus mapeamentos para a Linguagem de consulta do Google Ads (GAQL, na sigla em inglês).
| Interface | GAQL |
|---|---|
| Colunas | Qualquer recurso, campo de segmento ou métrica na cláusula SELECT de uma consulta GAQL. |
| Período | Os períodos são mapeados para uma cláusula WHERE filtrando em segments.date. |
| Filtros | Uma ou mais condições na cláusula WHERE. |
| Segmentar campos | Aplique a segmentação incluindo campos de segmento na consulta GAQL. |
| Paginação | A paginação divide o conjunto de resultados da consulta em várias páginas. |
Coluna
As colunas na IU são equivalentes aos Campos de recurso, Campos de segmento e Métricas no GAQL.
Filtragem
Períodos
A interface do Google Ads tem uma tabela que exibe as estatísticas da conta e um menu suspenso usado para controlar o período dessas estatísticas.
Você tem o mesmo controle na GAQL filtrando segments.date na cláusula WHERE de uma consulta GAQL.
Filtros
Os filtros na IU são equivalentes a uma ou mais condições na cláusula WHERE da GAQL.
Segmentação
Para estatísticas mais detalhadas, você pode dividir os dados por segmentos. Por exemplo, talvez você tenha interesse em saber o número de impressões específicas da rede de pesquisa do Google separadamente da Rede de Display. Nesse caso, você segmentaria seu relatório por rede. Consulte Segmentação para saber como incluir campos de segmento na cláusula SELECT.
Paginação
Navegue pelos relatórios na interface usando os controles disponíveis na parte de baixo de cada tabela de dados. Com eles, é possível mudar de página e selecionar o número de resultados que serão mostrados em um conjunto definido de tamanhos.
A paginação dos resultados está disponível ao recuperar relatórios com
GoogleAdsService.Search a
next_page_token. Para buscar todo o conjunto de resultados
sem paginação, use
GoogleAdsService.SearchStream.
Ordenar resultados
Na interface, você pode ordenar os resultados selecionando uma coluna.
Na GAQL, é possível usar as cláusulas ORDER BY e LIMIT para ordenar o resultado da sua consulta.
Formatos de download
Na interface, é possível fazer o download dos relatórios em vários formatos, como CSV, TSV ou XML.
A API não aceita diretamente formatos diferentes na saída, então seria necessário executar parte do pós-processamento. Veja um exemplo de código que mostra como implementar a formatação CSV em um cliente.
Agendamento e relatórios de e-mail
A programação e o envio de relatórios por e-mail estão disponíveis na interface, mas não são compatíveis com a API.
Relatórios predefinidos
Você pode criar uma lista de relatórios predefinidos na interface do Google Ads.
Veja uma lista dos relatórios predefinidos básicos e o nome do recurso GAQL correspondente.
| Relatórios predefinidos básicos | Nome do recurso GAQL (especifique na cláusula FROM) |
|---|---|
| Conta | cliente |
| Campanha, Detalhes da campanha |
campaign |
| Grupo de anúncios, Detalhes do grupo de anúncios |
ad_group |
|
Anúncio, URL final |
ad_group_ad |
| Pesquisar palavra-chave | keyword_view |
| Termos de pesquisa | search_term_view |
| Pesquisa paga e orgânica | paid_organic_search_term_view |
| Página de destino | landing_page_view |
| Página de destino expandida | expanded_landing_page_view |
Como exemplo da tabela acima, você pode usar a GAQL a seguir para gerar o Relatório da conta:
SELECT
customer.descriptive_name,
customer.id,
metrics.clicks,
metrics.impressions,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros,
metrics.absolute_top_impression_percentage,
metrics.top_impression_percentage,
metrics.average_cpm
FROM customer
WHERE segments.date DURING LAST_7_DAYS
Diferenças comuns
Ao comparar relatórios de interface com relatórios de API, uma das diferenças mais comuns é que a interface filtra implicitamente entidades removidas, enquanto a API não faz isso.
Para replicar uma visualização de interface padrão, é preciso adicionar um filtro, normalmente usando um campo status, para excluir linhas removidas, por exemplo:
SELECT campaign.name
FROM campaign
WHERE campaign.status != "REMOVED"