Leia as seções abaixo para saber como criar relatórios de pesquisa na API Search Ads 360 Reporting.
SearchService
A API Search Ads 360 Reporting oferece um serviço especial para pesquisa e geração de relatórios.
O SearchAds360Service
é um serviço unificado de geração de relatórios e recuperação de objetos
que oferece dois métodos de pesquisa: SearchStream
e Search
. As pesquisas são transmitidas em uma string de consulta escrita na Linguagem de consulta do Search Ads 360. É possível definir consultas para:
- Recuperar atributos específicos de objetos.
- Recupere métricas de desempenho de objetos com base em um período.
- Ordenar objetos com base em seus atributos.
- Filtrar seus resultados usando condições que especificam quais objetos retornar
- Limite o número de objetos retornados.
Ambos os métodos de pesquisa retornam todas as linhas que correspondem à sua consulta. Por exemplo, quando você recupera campaign.id
, campaign.name
e metrics.clicks
, a API retorna um SearchAds360Row
contendo um objeto de campanha com os campos id
e name
definidos e um objeto metrics
com o campo clicks
definido.
Métodos de pesquisa
SearchStream
Envia uma única solicitação e inicia uma conexão permanente com a API Search Ads 360 Reporting, independentemente do tamanho do relatório.
- O download dos pacotes de dados é iniciado imediatamente, com todo o resultado armazenado em cache em um buffer de dados.
- O código pode começar a ler os dados armazenados em buffer sem precisar esperar a conclusão de todo o stream.
Search
Envia várias solicitações paginadas para fazer o download do relatório inteiro.
SearchStream
normalmente oferece melhor desempenho porque elimina o
tempo de ida e volta da rede necessário para solicitar páginas individuais. Recomendamos usar
SearchStream
para todos os relatórios com mais de 10.000 linhas. Não há diferença de desempenho significativa entre os métodos para relatórios menores (<10.000 linhas).
O método usado não afeta as cotas e limites da API: uma única consulta ou relatório é contabilizado como uma operação, independentemente de os resultados serem paginados ou transmitidos.
Exemplo de consulta de pesquisa
Esta consulta de exemplo retorna dados de performance de uma conta nos últimos 30 dias por campanha, segmentados por dispositivo:
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.average_cpc,
metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Fazer uma solicitação
Para emitir uma solicitação, é necessário transmitir uma string customer_id
e query
à interface SearchAds360Service.SearchStream
ou
SearchAds360Service.Search
.
A solicitação consiste em um POST
HTTP para o servidor da API Search Ads 360 Reporting em um dos seguintes URLs:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search
Veja um exemplo completo da definição de relatório para searchStream
incluído em uma solicitação HTTP POST
:
POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1 Host: searchads360.googleapis.com User-Agent: curl Content-Type: application/json Accept: application/json Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN] Parameters: { "query" : "SELECT campaign.name, campaign.status, segments.device, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS" }
Processar uma resposta
SearchAds360Service
retorna uma lista de objetos SearchAds360Row
.
Cada SearchAds360Row
representa um objeto retornado pela consulta. Cada objeto consiste em um conjunto de atributos preenchidos com base nos campos solicitados na cláusula SELECT
da consulta. Os atributos não incluídos na cláusula SELECT
não são preenchidos nos objetos na resposta.
Por exemplo, a consulta abaixo preenche cada objeto SearchAds360Row
apenas com
campaign.id
, campaign.name
e campaign.status
. Outros atributos, como
campaign.engine_id
ou campaign.bidding_strategy_type
, são omitidos.
SELECT
campaign.id,
campaign.name,
campaign.status
FROM campaign
Documentação de referência
A seção Referência
inclui todas as informações necessárias para usar corretamente cada artefato. Há
uma página para cada recurso, por exemplo, ad_group
e
campaign
.
As páginas segments
e metrics
listam todos os segmentos e campos de métricas disponíveis.
Alguns recursos, segmentos e métricas são incompatíveis e não podem ser usados em conjunto, enquanto outros são totalmente compatíveis e se complementam. Cada página de recursos inclui as seguintes informações (se disponíveis e apropriadas), entre outras:
- Recursos atribuídos
Em alguns recursos, você tem a opção de mesclar implicitamente recursos relacionados selecionando os campos deles com os campos do recurso na cláusula
FROM
. Por exemplo, o recursocampaign
é um recurso atribuído do recursoad_group
. Isso significa que é possível incluir campos comocampaign.id
ecampaign.bidding_strategy_type
na consulta ao usarad_group
na cláusulaFROM
.A seção Recursos atribuídos lista os recursos atribuídos disponíveis. Nem todos os recursos têm recursos atribuídos.
- Coluna "Campos de recursos"
Todos os campos do recurso estão incluídos na coluna Campos do recurso. Cada campo de recurso tem links para mais detalhes sobre o campo, incluindo descrição, categoria, tipo de dados, URL do tipo e configuração filtrável, selecionável, classificável e repetida.
- Coluna de segmentos
Nem todos os campos de segmento podem ser selecionados com um determinado recurso.
A coluna Segmentos lista os campos
segments
que podem ser usados na mesma cláusulaSELECT
que os campos do recurso. Cada campo tem links para detalhes completos, incluindo descrição, categoria, tipo de dados, tipo de URL e configuração filtrável, selecionável, classificável e repetida. Se você estiver usando o recurso na cláusulaFROM
, poderá usar o menu suspenso Sim/Não para filtrar os segmentos que não estão disponíveis.- Coluna de métricas
Nem todos os campos de métricas podem ser selecionados com um determinado recurso.
A coluna Métricas lista os campos
metrics
que podem ser usados na mesma cláusulaSELECT
que os campos do recurso. Cada campo tem links para detalhes completos, incluindo descrição, categoria, tipo de dados, tipo de URL e configuração filtrável, selecionável, classificável e repetida. Se você estiver usando o recurso na cláusulaFROM
, use o menu suspenso Sim/Não para filtrar as métricas que não estão disponíveis.
- Como segmentar recursos
Alguns recursos têm campos de segmentação que podem ser selecionados quando o recurso está na cláusula
FROM
. Por exemplo, se você selecionar um campo de recursocampaign
, comocampaign.name
, ao usarcampaign_budget
na cláusulaFROM
,campaign.resource_name
será retornado e segmentado automaticamente, porquecampaign
é um recurso de segmentação decampaign_budget
.A seção Como segmentar recursos lista os recursos de segmentação disponíveis. Nem todos os recursos têm recursos de segmentação.
- Selecionável com
Alguns campos
segments
são incompatíveis com outros recursos, segmentos e métricas.A página
segments
inclui um campo Selecionável com expansível para cada camposegments
que lista todos os campos de recursos compatíveis, camposmetrics
e outros campossegments
que podem ser incluídos na cláusulaSELECT
.
Segmentação
Para segmentar os resultados da pesquisa, adicione um campo segments.FIELD_NAME
à cláusula SELECT
da consulta.
Por exemplo, segments.device
na
consulta abaixo, resulta em um relatório com uma linha para o impressions
de cada
dispositivo para o recurso especificado na cláusula FROM
.
SELECT
campaign.name,
campaign.status,
segments.device,
metrics.impressions
FROM campaign
Os resultados retornados por SearchAds360Service.SearchStream
são parecidos com esta string JSON:
{
"results":[
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"10922"
},
"segments":{
"device":"MOBILE"
}
},
{
"campaign":{
"resourceName":"customers/1234567890/campaigns/111111111",
"name":"Test campaign",
"status":"ENABLED"
},
"metrics":{
"impressions":"28297"
},
"segments":{
"device":"DESKTOP"
}
},
...
]
}
Consulte segments
para ver uma lista dos campos de segmento disponíveis que podem ser usados.
vários segmentos
É possível especificar vários segmentos na cláusula SELECT
da sua consulta. A resposta contém um objeto SearchAds360Row
para cada combinação da instância do recurso principal especificado na cláusula FROM
e o valor de cada campo segment
selecionado.
Por exemplo, a consulta a seguir retornará uma linha para cada combinação de campaign
, segments.ad_network_type
e segments.date
.
SELECT
segments.ad_network_type
segments.date
FROM campaign
Os resultados são segmentados implicitamente para cada instância do recurso principal, mas não pelos valores dos campos individuais selecionados.
O exemplo de consulta a seguir resulta em uma linha por campanha, não em uma linha por valor distinto do campo campaign.status
.
SELECT
campaign.status,
metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS
Segmentação implícita
Todo relatório é inicialmente segmentado pelo recurso especificado na cláusula FROM
. As métricas são segmentadas pelo campo resource_name
deste recurso
Esta consulta de exemplo retorna automaticamente ad_group.resource_name
e a usa implicitamente para segmentar métricas no nível ad_group
.
SELECT metrics.impressions
FROM ad_group
A string JSON retornada é semelhante a esta:
{
"results":[
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/2222222222"
},
"metrics":{
"impressions":"237"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/33333333333"
},
"metrics":{
"impressions":"15"
}
},
{
"adGroup":{
"resourceName":"customers/1234567890/adGroups/44444444444"
},
"metrics":{
"impressions":"0"
}
}
]
}
Principais segmentos de data
É possível usar segmentos de data principais na cláusula WHERE
para especificar uma data
ou período.
Os campos de segmentos a seguir são conhecidos como segmentos de data principais: segments.date
, segments.week
, segments.month
, segments.quarter
e segments.year
.
Este exemplo de consulta retorna as métricas clicks
da campanha nos últimos 30 dias.
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
Os campos de segmentos de data principais são uma exceção à regra geral de que não é possível usar um campo de segmentos na cláusula WHERE
, a menos que você também inclua o campo na cláusula SELECT
. Consulte Filtragem proibida para mais
informações.
Regras principais do segmento de data:
É possível usar um campo de data principal na cláusula
WHERE
sem incluí-lo na cláusulaSELECT
. Você também pode incluir o campo em ambas as cláusulas, se quiser.Esta consulta de exemplo retorna métricas
clicks
por nome de campanha durante o período. Observe quesegments.date
não está incluído na cláusulaSELECT
.SELECT campaign.name, metrics.clicks FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Se você incluir um campo de data principal na cláusula
SELECT
, precisará especificar uma data ou período finito na cláusulaWHERE
. Os campos especificados nas cláusulasSELECT
eWHERE
não precisam ser correspondentes.Este exemplo de consulta retorna métricas
clicks
por nome de campanha segmentadas por mês para todos os dias do período.SELECT campaign.name, metrics.clicks, segments.month FROM campaign WHERE segments.date > '2022-02-01' AND segments.date < '2022-03-01'
Datas ISO 8601
Você pode usar o formato YYYY-MM-DD
(ISO 8601) para especificar datas e períodos,
por exemplo:
WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'
WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'
Para segmentos de data principais que exigem um período (segments.week
, segments.month
, segments.quarter
), é possível usar o operador =
com o primeiro dia do período. Por exemplo:
WHERE segments.month = '2022-06-01'
Datas predefinidas
Também é possível usar as seguintes datas e períodos predefinidos:
Datas predefinidas | |
---|---|
TODAY |
Somente hoje. |
YESTERDAY |
Somente ontem. |
LAST_7_DAYS |
Os sete dias anteriores não estão incluindo hoje. |
LAST_BUSINESS_WEEK |
Semana útil de cinco dias anteriores (de segunda a sexta-feira) |
THIS_MONTH |
Todos os dias do mês atual. |
LAST_MONTH |
Todos os dias do último mês. |
LAST_14_DAYS |
Últimos 14 dias, excluindo hoje. |
LAST_30_DAYS |
Últimos 30 dias, excluindo hoje. |
THIS_WEEK_SUN_TODAY |
Período entre o último domingo e o dia atual. |
THIS_WEEK_MON_TODAY |
Período entre a última segunda-feira e o dia atual. |
LAST_WEEK_SUN_SAT |
Período de sete dias a partir do domingo anterior. |
LAST_WEEK_MON_SUN |
Período de sete dias a partir da segunda-feira anterior. |
Exemplo:
WHERE segments.date DURING LAST_30_DAYS
Nenhuma métrica
Ao executar uma consulta, você pode encontrar métricas com valor zero para algumas entidades. Saiba como lidar com métricas sem métricas nas suas consultas.
Tipos de tipo enumerado UNKNOWN
Se um recurso for retornado com o tipo de dados de enumeração UNKNOWN
, isso significa que
o tipo não é totalmente compatível com a versão da API. Esses recursos podem ter sido criados por outras interfaces. Por exemplo, uma nova campanha ou anúncio é introduzido na interface do Search Ads 360, mas ainda não é compatível com a versão da API que você está consultando.
Ainda é possível selecionar métricas quando um recurso tem o tipo UNKNOWN
, mas é
necessário ter em mente o seguinte:
- Um recurso com um tipo
UNKNOWN
pode receber suporte mais tarde, mas pode permanecerUNKNOWN
indefinidamente. - Novos objetos com o tipo
UNKNOWN
podem aparecer a qualquer momento. Esses objetos são compatíveis com versões anteriores, porque o valor do tipo enumerado já está disponível. Apresentaremos os recursos com essa mudança à medida que estiverem disponíveis para que você tenha uma visão precisa da sua conta. O recursoUNKNOWN
pode aparecer devido a uma nova atividade na sua conta por outras interfaces ou porque um recurso não tem mais suporte formal. - Os recursos
UNKNOWN
podem ter métricas detalhadas anexadas a eles que podem ser consultadas. - Os recursos
UNKNOWN
normalmente são totalmente visíveis na interface do Search Ads 360.