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 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

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 subjacente. Isso é usado para demonstrar os conceitos. Recomendamos que você use nossas bibliotecas de cliente baseadas no gRPC para enviar solicitações no seu próprio app.

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 recurso campaign é um recurso atribuído do recurso ad_group. Isso significa que é possível 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 "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áusula SELECT 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áusula FROM, 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áusula SELECT 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á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 ou período específico, inclua segmentos.date na cláusula SELECT.

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 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 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 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 Linguagem de consulta do Search Ads 360 para saber como usar cada cláusula de uma consulta.

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

Cuidado :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 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

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

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áusula SELECT. 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 que 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, precisará especificar uma data ou período finito na cláusula WHERE. Os campos especificados nas cláusulas SELECT e WHERE 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'

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

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 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. Apresentaremos os recursos com essa mudança à medida que estiverem 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 a eles que podem ser consultadas.
• Os recursos UNKNOWN normalmente são totalmente visíveis na interface do Search Ads 360.