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.

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 os atributos específicos dos objetos.
• Recuperar métricas de desempenho para objetos com base em um período.
• Ordenar objetos com base nos atributos deles.
• Filtrar os resultados usando condições que especificam quais objetos retornar.
• Limitar o número de objetos retornados.

Os dois métodos de pesquisa retornam todas as linhas que correspondem à consulta. Por exemplo, ao recuperar campaign.id, campaign.name e metrics.clicks, a API retorna um SearchAds360Row que contém 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 baixados 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 que todo o stream termine.

Search

Envia várias solicitações paginadas para baixar o relatório completo.

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

O método usado não afeta as cotas e os 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 desempenho 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 para a interface SearchAds360Service.SearchStream ou SearchAds360Service.Search.

A solicitação consiste em um HTTP POST 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

Confira 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 SearchAds360Row objetos.

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 da 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 que você precisa 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 campos de segmentos e 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 recursos 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 junto com os campos do recurso na cláusula FROM. Por exemplo, o campaign recurso é um recurso atribuído do ad_group recurso. 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 "Campos de recursos"

Todos os campos do recurso estão incluídos na coluna Campos de recursos. Cada campo de recurso tem um link para mais detalhes sobre ele, incluindo descrição, categoria, tipo de dados, URL de tipo e configuração filtrável, selecionável, classificável e repetida.

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 um link para detalhes completos sobre ele, incluindo descrição, categoria, tipo de dados, URL de tipo 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 segmentos que não estão disponíveis.

Coluna "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 um link para detalhes completos sobre ele, incluindo descrição, categoria, tipo de dados, URL de tipo 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 métricas que não estão disponíveis.

Segmentação de recursos

Alguns recursos têm campos de recursos de segmentação que podem ser selecionados quando o recurso está na cláusula FROM. Por exemplo, se você selecionar um campaign campo de recurso, como campaign.name, ao usar campaign_budget na sua 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.

Segmentação

É possível segmentar os resultados da pesquisa adicionando um segments.FIELD_NAME campo à SELECT cláusula da consulta.

Por exemplo, segments.device na consulta abaixo resulta em um relatório com uma linha para as impressions de cada dispositivo para o recurso especificado na FROM cláusula.

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 uma lista de campos de segmento disponíveis que você pode usar.

Vários segmentos

É 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 retorna 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 por cada instância do recurso principal, mas não pelos valores dos campos selecionados individuais.

A consulta de exemplo 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 desse recurso.

Esta consulta de exemplo retorna automaticamente ad_group.resource_name e implicitamente o usa 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 WHERE cláusula para especificar um período.

Os seguintes campos de segmentos são conhecidos como segmentos de data principais: segments.date, segments.week, segments.month, segments.quarter, e segments.year.

Esta consulta de exemplo retorna métricas de 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 de segmento de data principais:

• É 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.

  Esta consulta de exemplo retorna métricas de clicks por nome da 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, especifique uma data ou um período finito na cláusula WHERE. Os campos especificados nas cláusulas SELECT e WHERE não precisam corresponder.

  Esta consulta de exemplo retorna métricas de clicks por nome da 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

É possível 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:

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 zero 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 é 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 o seguinte em mente:

• Um recurso com um tipo UNKNOWN pode ser compatível 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 de enumeração 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 é mais oficialmente compatível.

• Os recursos UNKNOWN podem ter métricas detalhadas anexadas a eles que podem ser consultadas.

• Os recursos UNKNOWN geralmente são totalmente visíveis na interface do Search Ads 360.