Relatório de impressões inexistentes e Relatório de estrutura

Além de recuperar estatísticas de desempenho, os desenvolvedores da AdWords API usam com frequência o sistema de relatórios para ver informações estruturais sobre as contas.

Este guia explica como interpretar e gerenciar estatísticas de impressões inexistentes em relatórios e como usá-las na criação da estrutura de uma conta.

Estatísticas de impressões inexistentes em relatórios

Nos relatórios, é possível encontrar estatísticas de impressões inexistentes para entidades que não foram visualizadas. Pode haver várias razões para isso: as entidades não se qualificaram para exibição ou foram pausadas durante o período do relatório.

Essas impressões inexistentes são pouco úteis ao calcular o desempenho, mas são necessárias para fazer o download do conteúdo completo da conta.

Os Relatórios de impressões inexistentes são usados para descobrir estruturas de entidades em uma conta ou para sincronizar rapidamente um banco de dados local sem ter que fazer uma série de chamadas get() caras para a API. Ao incluir as impressões inexistentes nos resultados, é possível descobrir a estrutura de qualquer entidade da conta em uma única chamada.

Como incluir e excluir impressões inexistentes

Dados de impressões inexistentes podem ser retornados em todos os relatórios de desempenho normais. Assim, você deve sempre incluir ou excluir explicitamente as impressões inexistentes, de acordo com o caso de uso. Com isso, qualquer ambiguidade será removida das suas solicitações, e a API poderá indicar um erro significativo se sua solicitação apresentar uma combinação inválida de campos de relatório e comportamento de impressões inexistentes.

Quando incluir impressões inexistentes

As impressões inexistentes são úteis para expor estruturas de entidades em uma conta, em uma única chamada. A alternativa é fazer inúmeras solicitações de API, o que pode acionar limites de taxa.

Por exemplo, consultar o Relatório de desempenho por palavra-chave para Id e Criteria, excluindo as impressões inexistentes, pode recuperar apenas resultados mínimos. No entanto, incluir impressões inexistentes e adicionar campos como CampaignId e AdGroupId possibilita o processamento e a criação de uma estrutura das palavras-chave atualmente conhecidas.

Quando excluir impressões inexistentes

As impressões inexistentes são úteis para descobrir estruturas de entidades, mas, de modo geral, devem ser excluídas dos relatórios de desempenho. Convém excluir impressões inexistentes para reduzir o tamanho da resposta ou para focar apenas nas estatísticas de desempenho significativas de um determinado período. Isso é especificamente vantajoso se houver muitas campanhas pausadas em um determinado relatório, já que as impressões inexistentes podem ocasionar o aumento desnecessário do conjunto de resultados.

Como incluir impressões inexistentes

Para incluir impressões inexistentes nos resultados do relatório, defina o cabeçalho HTTP includeZeroImpressions como true.

Quando ele é definido como true, os relatórios não excluem nenhuma linha com base nos valores de métrica. Além disso, eles incluem as linhas com impressões inexistentes.

Como excluir impressões inexistentes

Há duas formas de excluir explicitamente as impressões inexistentes dos relatórios:

  • definir o cabeçalho HTTP includeZeroImpressions como false;
  • usar um predicado.

Como definir o cabeçalho HTTP includeZeroImpression como "false"

A maneira mais simples de excluir as impressões inexistentes é definir o cabeçalho HTTP includeZeroImpressions como false.

Quando ele é definido como false, os relatórios retornam somente as linhas nas quais pelo menos um dos campos Metric solicitados apresenta um valor diferente de zero.

Como excluir impressões inexistentes com um predicado

Você pode excluir impressões inexistentes adicionando um predicado para o campo Impressions com um operador GREATER_THAN e um valor 0.

O XML desse predicado ficaria da seguinte forma:

<predicates>
  <field>Impressions</field>
  <operator>GREATER_THAN</operator>
  <values>0</values>
</predicates>

e a declaração de AWQL, assim:

WHERE Impressions > 0

Como excluir implicitamente impressões inexistentes

As linhas de impressões inexistentes são implicitamente excluídas quando uma solicitação de relatório contém qualquer campo que não seja compatível com as impressões inexistentes. É possível ver o comportamento de impressões inexistentes de cada campo no atributo Compatível com impressões inexistentes das páginas Tipos de relatório.

No entanto, o melhor é não confiar nas exclusões implícitas, pois adicionar ou remover um campo da sua solicitação pode mudar o comportamento do relatório.

Relatórios de estrutura

Usar os serviços da API para coletar dados abrangentes sobre sua conta pode demorar, principalmente à medida que sua conta cresce.

Com os relatórios do Google AdWords, fica mais fácil ver informações estruturais básicas da sua conta e das entidades relacionadas a ela. Você pode usar os relatórios para retornar dados de forma rápida, incluindo códigos de objetos, nomes e valores, e reproduzir o esqueleto básico da sua conta. Em seguida, você poderá identificar elementos sobre os quais deseja saber mais e usar os códigos de objeto desses elementos para recuperar detalhes da API.

A documentação Tipos de relatório indica quais entradas da coluna podem ser recuperadas para cada objeto da conta. Também é possível conseguir esses títulos de colunas por meio de programação, usando o método getReportFields() do ReportDefinitionService. Ao selecionar cuidadosamente as colunas do relatório, é possível ver informações suficientes para criar a estrutura da sua conta.

Exemplos de campanhas

Este exemplo demonstra como coletar alguns dados relevantes sobre cada campanha em uma conta. Use uma solicitação de AWQL para coletar os dados e insira os dados retornados em um banco de dados local. Em seguida, você poderá fazer solicitações SELECT locais para criar a tabela estrutural na qual tem interesse.

As etapas e os snippets de código a seguir mostram como criar uma tabela de campanhas:

  1. Consulte os dados da campanha contidos nos relatórios ao criar uma string de solicitação de AWQL, especificando todos os títulos de coluna obrigatórios do Relatório de desempenho de campanhas. Você também precisa indicar o tipo de relatório e um período para a consulta. Em seguida, use essa consulta para criar o relatório e especifique CSV como formato de download.

    SELECT CampaignStatus, CampaignId, CampaignName, ExternalCustomerId,
        CustomerDescriptiveName, Amount, BiddingStrategyId, Impressions
    FROM CAMPAIGN_PERFORMANCE_REPORT
    DURING YESTERDAY
    

  2. Crie uma tabela de campanhas local. A instrução a seguir cria a tabela, inserindo os tipos e títulos de colunas na nossa tabela SQLite:

    CREATE TABLE campaigns (Status STRING, id LONG, name STRING, extCID LONG,
        custName STRING, amount FLOAT, biddingStrategyId LONG, impressions INTEGER)
    

  3. Preencha a tabela de campanhas. A instrução SQL abaixo insere entradas na tabela campaigns. Defina um valor de parâmetro para cada "?" usando os valores recebidos no download do relatório.

    INSERT INTO campaigns (Status, id, name, extCID, custName, amount,
        biddingStrategyId, impressions) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
    

Formatos de relatório

Os relatórios estão disponíveis em vários formatos (como CSV ou XML). No entanto, com o formato CSV, é possível simplesmente alimentar o fluxo de respostas por meio de bibliotecas já disponíveis para filtrar cada entrada no formato de objeto da sua escolha. O arquivo CSV também é mais conciso, logo, o processamento é geralmente mais rápido.

Por padrão, os relatórios CSV apresentam o cabeçalho do relatório na primeira linha, os cabeçalhos das colunas na segunda linha seguidos dos resultados e, finalmente, uma linha Total de resumo. Veja a seguir um exemplo de resposta do Relatório de desempenho de campanhas que ilustra o formato padrão:

"CAMPAIGN_PERFORMANCE_REPORT (Apr 1, 2015-Apr 6, 2015)"
Campaign state,Campaign ID,Campaign,Customer ID,Account,Cost,Bid Strategy Name,Impressions
paused,143072203,Search + DSAs,1234567890,My AdWords Account,0, --,0
paused,168682400,Interplanetary Cruise 1396462861759,1234567890,My AdWords Account,0, --,0
paused,168682099,Interplanetary Cruise 1396462699054,1234567890,My AdWords Account,0, --,0
enabled,238539688,Campaign 1234,1234567890,My AdWords Account,5970000, --,902
Total, --, --, --, --,5970000, --,902

Nesse formato padrão, a linha de cabeçalho do relatório é seguida pelos nomes das colunas solicitadas na segunda linha. As colunas retornadas ficam na mesma ordem especificada na solicitação, a menos que você solicite colunas duplicadas. Nesse caso, a segunda ocorrência é omitida. A linha de resumo conclui o relatório.

Ao analisar e inserir os dados em um banco de dados, ignore as duas primeiras linhas e insira as demais até chegar na linha Total, que também deverá ser ignorada. Se preferir, você pode definir cabeçalhos opcionais na solicitação. Assim, o cabeçalho do relatório, os cabeçalhos das colunas e o resumo são omitidos na resposta, restando somente os dados.

É possível repetir essas tarefas para grupos de anúncios, anúncios e critérios, e usar o SQL para consultar o banco de dados local que você acabou preencher. Você pode fazer modificações para utilizar os dados coletados como desejar, por exemplo:

SELECT * FROM campaigns
LEFT OUTER JOIN adGroups ON campaigns.id=adGroups.campaignId
LEFT OUTER JOIN ads ON ads.adAdGroupId=adGroups.adGroupId

ou

SELECT * FROM criteria
JOIN keywords
WHERE criteria.critType='Keyword' AND keywords.keywordId=criteria.critId

Sugestões e dicas

Ao usar essa abordagem para recuperar dados da conta, lembre-se das dicas a seguir:

  • Ao solicitar determinados relatórios, a inclusão de colunas que impedem o retorno de linhas com impressões inexistentes fará com que nenhum resultado seja gerado. O campo KeywordId no Relatório de desempenho de anúncios é um exemplo disso. Ele é indicado na coluna Observações e pelo valor False na respectiva coluna Compatível com impressões inexistentes. Outras colunas podem ser mutuamente exclusivas, por exemplo, ConversionTypeName e Clicks. Evite esses títulos de coluna ao fazer o download de dados estruturais. No lugar deles, use os títulos listados como Atributos na coluna Comportamento.

  • Além disso, evite solicitar colunas duplicadas, pois elas são removidas da resposta e podem causar confusão na análise dos dados. Consulte a coluna Observações na página Tipos de relatório para ver especificações sobre como as colunas são formatadas.

  • Se você optar por não usar cabeçalhos opcionais para suprimir a linha Total de resumo e, em vez disso, indicar o fim da sua análise por meio da palavra Total, tenha cuidado ao selecionar a primeira coluna na consulta da AWQL para que a palavra Total não seja exibida como um dos valores dessa coluna. Isso encerraria sua análise prematuramente. Por exemplo, você pode tranquilamente usar códigos como a primeira coluna, que será "Longos". No exemplo, selecionamos a coluna Status, que contém strings com um conjunto limitado de valores.

  • Certifique-se de que o tipo de cada coluna esteja certo, já que a divisão desses valores nos valores corretos das strings gerará exceções se você receber algo inesperado e depois chamar um analisador de strings específico para cada tipo.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.