Criar relatórios de pesquisa na API Search Ads 360 Reporting

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 relatórios.

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:

• Extrair atributos específicos de objetos.
• Extrair métricas de desempenho de objetos com base em um período
• Ordenar objetos com base nos atributos deles.
• Filtrar os resultados usando condições que especificam quais objetos serão retornados
• Limitar o número de objetos retornados.

Os dois métodos de pesquisa retornam todas as linhas que correspondem à consulta. Por exemplo, quando você extrai 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 persistente com a API Search Ads 360 Reporting, independentemente do tamanho do relatório.

• Os pacotes de dados começam a ser transferidos imediatamente com o resultado completo armazenado em cache em um buffer de dados.
• O código pode começar a ler os dados armazenados em buffer sem precisar esperar que o fluxo inteiro seja concluído.

Search

Envia várias solicitações paginadas para fazer o download de todo o relatório.

O SearchStream geralmente oferece um desempenho melhor porque elimina o tempo de ida e volta da rede necessário para solicitar páginas individuais. Recomendamos o uso de SearchStream para todos os relatórios com mais de 10.000 linhas. Não há diferença significativa no desempenho entre os métodos para relatórios menores (<10.000 linhas).

O método usado não afeta as cotas e os limites da API: uma única consulta ou relatório é contada como uma operação, independentemente de os resultados serem paginados ou transmitidos.

Exemplo de consulta de pesquisa

Este exemplo de consulta retorna dados de performance de uma conta dos últimos 30 dias por campanha, segmentado 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

Observação: a linguagem de consulta do Search Ads 360 fornece informações detalhadas sobre como usar cada cláusula da consulta de pesquisa.

Fazer uma solicitação

Para emitir uma solicitação, é necessário transmitir uma string customer_id e query à interface SearchAds360Service.SearchStream ou SearchAds360Service.Search.

Observação: os exemplos abaixo mostram a solicitação HTTP/JSON. Isso é usado para demonstrar os conceitos. Recomendamos que você use nossas bibliotecas de cliente baseadas em gRPC para enviar solicitações no seu próprio app.

A solicitação consiste em um POST HTTP para o servidor da API de relatórios do Search Ads 360 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

Confira um exemplo completo da definição de relatório para searchStream incluída 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 que não estão incluídos na cláusula SELECT não são preenchidos nos objetos da resposta.

Por exemplo, a consulta abaixo preenche cada objeto SearchAds360Row com apenas 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 juntos, enquanto outros são totalmente compatíveis e se complementam. Cada página de recurso inclui as seguintes informações (se disponíveis e adequadas) e muito mais:

Recursos atribuídos

Para alguns recursos, você pode ter a opção de unir implicitamente recursos relacionados selecionando os campos deles com os campos do recurso na sua cláusula FROM. Por exemplo, o recurso campaign é um recurso atribuído do recurso ad_group. Isso significa que você pode incluir campos como campaign.id e campaign.bidding_strategy_type na consulta ao usar ad_group na cláusula FROM.

A seção Recursos atribuídos lista os recursos atribuídos disponíveis. Nem todos os recursos têm recursos atribuídos.

Coluna de campos de recursos

Todos os campos do recurso são incluídos na coluna Campos do recurso. Cada campo de recurso tem links para mais detalhes sobre o campo, incluindo a descrição, a categoria, o tipo de dados, o URL do tipo e a configuração de filtro, seleção, classificação e repetição.

Coluna "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áusula SELECT que os campos do recurso. Cada campo tem links para detalhes completos sobre ele, incluindo descrição, categoria, tipo de dados, URL do tipo e configurações de filtro, seleção, classificação e repetição. Se você estiver usando o recurso na cláusula FROM, use 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áusula SELECT que os campos do recurso. Cada campo tem links para detalhes completos sobre ele, incluindo descrição, categoria, tipo de dados, URL do tipo e configurações de filtro, seleção, classificação e repetição. Se você estiver usando o recurso na cláusula FROM, use o menu suspenso Sim/Não para filtrar as métricas que não estão disponíveis.

Observação: ao receber métricas relacionadas à moeda (por exemplo, cost_micros) para uma data específica ou um período, inclua segments.date na cláusula SELECT.

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 recurso campaign, como campaign.name, ao usar campaign_budget na cláusula FROM, campaign.resource_name será retornado e segmentado automaticamente, porque campaign é um recurso de segmentação de campaign_budget.

A seção Recursos de segmentação 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 Selecionável com expansível para cada campo segments que lista todos os campos de recursos compatíveis, campos metrics e outros campos segments que podem ser incluídos na cláusula SELECT.

Observação: consulte a Linguagem de consulta do Search Ads 360 para saber como usar cada cláusula de uma consulta.

Segmentação

É possível segmentar os resultados da pesquisa adicionando 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 semelhantes a 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 de campos de segmento disponíveis.

vários segmentos

Atenção: o número de linhas pode aumentar exponencialmente para cada campo segments adicional que você adicionar à consulta.

É possível especificar vários segmentos na cláusula SELECT da 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 vai 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 de forma implícita 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 para cada valor distinto do campo campaign.status.

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

Segmentação implícita

Cada relatório é inicialmente segmentado pelo recurso especificado na cláusula FROM. As métricas são segmentadas pelo campo resource_name deste recurso

Observação: o campo resource_name do recurso na cláusula FROM é sempre retornado, mesmo quando não é especificado na cláusula SELECT. Consulte o campo resource_name para mais informações.

Esta consulta de exemplo retorna ad_group.resource_name automaticamente 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"
      }
    }
  ]
}

Segmentos de data principais

É 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 dos ú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 datas 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 de segmentação de datas:

• É possível usar um campo de data principal na cláusula WHERE sem incluí-lo na cláusula SELECT. Você também pode incluir o campo nas duas cláusulas, se quiser.

  Este exemplo de consulta retorna as métricas clicks por nome da campanha durante o período. segments.date não está incluído na cláusula SELECT.

  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, especifique uma data ou um período de tempo finito na cláusula WHERE. Os campos especificados nas cláusulas SELECT e WHERE não precisam ser correspondentes.

  Este exemplo de consulta retorna as métricas clicks por nome da campanha segmentado por mês para todos os dias no 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 intervalos de datas, 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), use o operador = com o primeiro dia do período, por exemplo:

WHERE segments.month = '2022-06-01'

Observação: se você especificar uma data que não seja o primeiro dia de um período, você receberá um erro MISALIGNED_DATE_FOR_FILTER.

Datas predefinidas

Você também pode usar as seguintes datas e períodos predefinidos:

Datas predefinidas
TODAY	Somente hoje.
YESTERDAY	Somente ontem.
LAST_7_DAYS	Últimos 7 dias, sem incluir o dia de hoje.
LAST_BUSINESS_WEEK	Semana útil anterior (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 domingo anterior e o dia atual.
THIS_WEEK_MON_TODAY	Período entre a segunda-feira anterior 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

Métricas zero

Ao executar uma consulta, você pode encontrar métricas com um valor de zero para algumas entidades. Saiba como lidar com métricas nulas nas consultas.

Tipos de enumeração UNKNOWN

Se um recurso for retornado com o tipo de dados de enumeração UNKNOWN, isso significa que o tipo não tem suporte total na 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 é preciso considerar o seguinte:

• Um recurso com um tipo UNKNOWN pode receber suporte mais tarde, mas pode permanecer UNKNOWN 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. Introduzimos recursos com essa mudança à medida que eles ficam disponíveis para que você tenha uma visão precisa da sua conta. O recurso UNKNOWN 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 que podem ser consultadas.
• Os recursos UNKNOWN geralmente ficam totalmente visíveis na interface do Search Ads 360.