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

Leia as seções abaixo para aprender a criar relatórios de pesquisa no Search Ads 360 API 360 Reporting.

SearchService

A API de relatórios do Search Ads 360 oferece um serviço especial para pesquisar e geração de relatórios.

O SearchAds360Service é um serviço unificado de geração de relatórios e recuperação de objetos que fornece dois métodos de pesquisa: SearchStream e Search. As pesquisas são transmitidos em uma string de consulta escrita na Linguagem de consulta do Search Ads 360. Você pode definir consultas para:

• Recupere atributos específicos de objetos.
• Recuperar métricas de desempenho de objetos com base em um período.
• Ordenar objetos com base nos atributos.
• Filtre os resultados usando condições que especificam quais objetos retornar
• Limite o número de objetos retornados.

Os dois métodos de pesquisa retornam todas as linhas que correspondem à sua consulta. Por exemplo, quando você recuperar campaign.id, campaign.name e metrics.clicks, a API retornará uma SearchAds360Row contendo um objeto de campanha com os campos id e name 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.

• O download dos pacotes de dados começa imediatamente com todo o resultado armazenadas em cache em um buffer de dados.
• O código pode começar a ler os dados em buffer sem precisar esperar todo o stream seja concluído.

Search

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

O SearchStream normalmente oferece um desempenho melhor porque elimina a tempo de rede de ida e volta necessário para solicitar páginas individuais. Recomendamos usar SearchStream para todos os relatórios de mais de 10.000 linhas. Não há diferença 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 limites da API: uma única consulta ou relatório é contados 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, 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 oferece informações detalhadas. sobre como usar cada cláusula da consulta de pesquisa.

Fazer uma solicitação

Para emitir uma solicitação, você precisa transmitir as strings customer_id e query. SearchAds360Service.SearchStream ou SearchAds360Service.Search interface gráfica do usuário.

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

A solicitação consiste em um POST HTTP para a API Search Ads 360 Reporting servidor 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í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. Atributos não incluídos no SELECT não serão preenchidos nos objetos na resposta.

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

Recursos atribuídos

Em alguns recursos, é possível mesclar implicitamente os recursos selecionando seus campos junto com os campos do recurso no sua cláusula FROM. Por exemplo, o recurso campaign é uma recurso atribuído do recurso ad_group. Isso significa que é possível inclua campos como campaign.id e campaign.bidding_strategy_type no seu ao usar ad_group na cláusula FROM.

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

Coluna de campos de recurso

Todos os campos do recurso estão incluídos na coluna Campos de recurso. Cada campo de recurso contém links para mais detalhes sobre o campo, incluindo o descrição, categoria, tipo de dados, tipo de URL e filtrável, selecionável, "classificável" e "repetido".

Coluna de segmentos

Nem todos os campos de segmento podem ser selecionados com um determinado recurso.

A coluna Segmentos lista os campos segments que você pode usar no mesma cláusula SELECT que os campos do recurso. Cada campo está vinculado a detalhes sobre o campo, incluindo descrição, categoria, tipo de dados, tipo e a configuração filtrável, selecionável, classificável e repetida. Se você for Com o recurso na cláusula FROM, use o menu suspenso Sim/Não para filtrar 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 você pode usar na mesma cláusula SELECT que os campos do recurso. Cada campo está vinculado a detalhes sobre o campo, incluindo descrição, categoria, tipo de dados, tipo e a configuração filtrável, selecionável, classificável e repetida. Se você for usando o recurso na cláusula FROM, use o menu suspenso Sim/Não para as métricas que não estão disponíveis.

.

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

Segmentação de recursos

Alguns recursos têm campos de segmentação que podem ser selecionados ao o recurso está na cláusula FROM. Por exemplo, se você selecionar um campo de recurso campaign, como campaign.name, quando usando campaign_budget na cláusula FROM, campaign.resource_name será automaticamente retornado e segmentado, porque campaign é uma segmentação de recurso de campaign_budget.

A seção Como segmentar recursos lista os recursos de segmentação disponíveis. Não 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 item Selecionável com expansível para cada campo segments que lista todos os campos de recursos compatíveis, campos metrics e outros segments campos 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

Você pode segmentar seus resultados de pesquisa adicionando um segments.FIELD_NAME à cláusula SELECT da consulta.

Por exemplo, segments.device na abaixo, resulta em um relatório com uma linha para a 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 parecem algo como 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 lista de campos de segmento disponíveis que você pode usar.

vários segmentos

Cuidado: o número de linhas pode aumentar exponencialmente para cada segments que você adiciona à consulta.

É possível especificar vários segmentos na cláusula SELECT da sua consulta. A contém um objeto SearchAds360Row para cada combinação dos instance do recurso principal especificado na cláusula FROM e o value 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 por instância dos principais recurso, mas não pelos valores dos campos individuais selecionados.

A consulta do exemplo a seguir resulta em uma linha por campanha, não em uma linha por um 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 é segmentado inicialmente pelo recurso especificado no 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 está sempre retornados, mesmo quando não estão especificados na cláusula SELECT. Consulte campo resource_name para mais informações.

Esta consulta de exemplo retorna automaticamente ad_group.resource_name e implicitamente o usa para segmentar métricas no nível do 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 os segmentos de data principal na cláusula WHERE para especificar uma data ou período.

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

Esta consulta de exemplo 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 data principais são uma exceção à regra geral que você não pode usar um campo de segmentos na sua cláusula WHERE, a menos que você também inclua o na cláusula SELECT. Consulte Filtragem proibida para mais informações informações imprecisas ou inadequadas.

Regras principais de segmento de data:

• Você pode usar um campo de data principal na cláusula WHERE sem incluí-lo no seu cláusula SELECT. Se quiser, você também pode incluir o campo em ambas as cláusulas.

  Esta consulta de exemplo retorna clicks métricas por nome de campanha durante a data do intervalo 10.240.0.0/16. 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 um data ou período finito na cláusula WHERE. Os campos especificados no As cláusulas SELECT e WHERE não precisam ser correspondentes.

  Este exemplo de consulta retorna clicks métricas por nome de campanha segmentada 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), você pode 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, 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	Os 7 dias anteriores não incluindo hoje.
LAST_BUSINESS_WEEK	Semana útil dos cinco dias anteriores (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	30 dias anteriores, excluindo hoje.
THIS_WEEK_SUN_TODAY	Período entre o último domingo e o dia de hoje.
THIS_WEEK_MON_TODAY	Período entre a última segunda-feira e o dia de hoje.
LAST_WEEK_SUN_SAT	Período de sete dias a partir do último domingo.
LAST_WEEK_MON_SUN	Período de sete dias que começa na segunda-feira anterior.

Exemplo:

WHERE segments.date DURING LAST_30_DAYS

Nenhuma métrica

Quando você executa uma consulta, pode encontrar métricas com valor zero para algumas entidades. Saiba como lidar com métricas inexistentes nas suas consultas.

Tipos de tipo enumerado UNKNOWN

Se um recurso for retornado com o tipo de dados de tipo enumerado UNKNOWN, isso significa que o tipo não é totalmente suportado na versão da API. Esses recursos podem ter 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 será possível selecionar métricas quando um recurso tiver o tipo UNKNOWN, mas você lembre-se:

• Um recurso com o 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ível com versões anteriores porque o valor da enumeração já está disponível. Apresentamos recursos com essa mudança à medida que eles são disponibilizados, para que você tenha uma ideia precisa visualização da sua conta. O recurso UNKNOWN pode aparecer devido aos novos atividade na sua conta por outras interfaces ou porque um recurso não recebe mais suporte formal.
• UNKNOWN recursos podem ter métricas detalhadas anexadas a eles que você pode consulta.
• Normalmente, os recursos UNKNOWN ficam totalmente visíveis na interface do Search Ads 360.