Princípios básicos dos relatórios

Os Relatórios de dados de desempenho são parte integrante da maioria dos aplicativos da AdWords API. Com as opções de relatórios flexíveis da API, é possível receber um relatório com dados de desempenho de uma campanha inteira ou se concentrar de forma mais restrita, por exemplo, nas consultas de pesquisa que acionaram seu anúncio.

Este guia descreve as etapas necessárias para criar e enviar uma solicitação de relatório ao servidor do Google AdWords. Em seguida, ele descreve conceitos de relatórios mais avançados, como segmentação de dados, formatos de dados e atribuição.

Para ver uma lista completa de todos os tipos de relatórios disponíveis na AdWords API, consulte as páginas de referência Tipos de relatórios.

Visão geral

Há duas etapas principais para gerar relatórios da API:

  1. Criar uma definição de relatório. A definição de relatório é um fragmento XML ou AWQL que determina os parâmetros do seu relatório, incluindo o nome do relatório, os tipos de informação a serem incluídos nele, o formato do download e outros detalhes.
  2. Incluir a definição do relatório em uma solicitação de HTTP POST e enviá-la para o servidor do Google AdWords.

Essas duas etapas são descritas abaixo.

Criar uma definição de relatório

A definição de relatório constitui o corpo da solicitação, onde você especifica os elementos a serem incluídos no relatório.

É possível criar definições de relatórios em XML ou em AWQL, a linguagem de consulta do Google AdWords.

The sections below cover XML–based report definitions. Confira a seção de relatórios do guia de AWQL se preferir usar AWQL em vez de XML.

Veja abaixo um exemplo de definição de relatório XML. A tabela abaixo descreve cada elemento da definição de relatório.

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
<fields>CampaignId</fields>
<fields>AdGroupId</fields>
<fields>Impressions</fields>
<fields>Clicks</fields>
<fields>Cost</fields>
<predicates>
  <field>AdGroupStatus</field>
  <operator>IN</operator>
  <values>ENABLED</values>
  <values>PAUSED</values>
</predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost
FROM ADGROUP_PERFORMANCE_REPORT
WHERE AdGroupStatus IN [ENABLED, PAUSED]
DURING LAST_7_DAYS
Elemento de definição de relatório Descrição
<reportDefinition> É o cabeçalho da definição de relatório. Use o mesmo URL mostrado na solicitação, garantindo que a versão correta da API esteja listada.
<selector> A seção do seletor contém uma lista de fields para os elementos de dados que você deseja selecionar e incluir no seu relatório. Consulte a página Tipos de relatório para mais informações sobre os valores possíveis. A lista de campos disponíveis depende do reportType especificado.

Também é possível usar o método ReportDefinitionService.getReportFields() para receber a lista de campos disponíveis de forma programática.

<predicates> Predicados são equivalentes aos filtros na interface do usuário do Google AdWords. Um predicado é composto por um campo de relatório, operadores e valores. Os predicados são tratados como condições inclusivas (AND).
<reportType> Indica o tipo de relatório que você está solicitando. Consulte as páginas de Tipos de relatório para mais informações e a lista completa de tipos de relatório.
<dateRangeType> O período que seu relatório deve incluir. Consulte Períodos abaixo para mais informações.
<downloadFormat> O formato no qual você deseja fazer o download do relatório. Consulte Formatos de download abaixo para mais informações.

Definição do esquema XML

Uma definição de esquema XML (XSD) que define a estrutura do reportDefinition é publicada no seguinte URL:

https://adwords.google.com/api/adwords/reportdownload/v201609/reportDefinition.xsd

Os Tipos de conteúdo application/x-www-form-urlencoded e multipart/form-data são suportados. Para o primeiro, você precisaria codificar o XML enviado em formato de URL.

Períodos

Para especificar o período do relatório, use um ReportDefinition.DateRangeType do XSD de definição de relatório.

Tipos de período válidos Os relatórios são gerados para...
TODAY Somente hoje.
YESTERDAY Somente ontem.
LAST_7_DAYS Os últimos 7 dias não incluindo hoje.
LAST_WEEK O período de sete dias que começa com a última segunda-feira.
LAST_BUSINESS_WEEK A semana útil de 5 dias, de segunda a sexta-feira, da última semana útil.
THIS_MONTH Todos os dias do mês atual.
LAST_MONTH Todos os dias do último mês.
ALL_TIME O período inteiro disponível.
CUSTOM_DATE Um período personalizado. Consulte Períodos personalizados abaixo para mais informações.
LAST_14_DAYS Os últimos 14 dias não incluindo hoje.
LAST_30_DAYS Os últimos 30 dias não incluindo hoje.
THIS_WEEK_SUN_TODAY O período entre o último domingo e o dia de hoje.
THIS_WEEK_MON_TODAY O período entre a última segunda-feira e o dia de hoje.
LAST_WEEK_SUN_SAT O período de sete dias que começa no último domingo.

Para cada ReportDefinition.DateRangeType (exceto CUSTOM_DATE), somente o dateRangeType é obrigatório.

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
    ...
  <dateRangeType>LAST_7_DAYS</dateRangeType>
</reportDefinition>

Períodos personalizados

Para utilizar um período personalizado, você precisa:

  1. especificar CUSTOM_DATE para dateRangeType;
  2. incluir um dateRange com min e max no formato YYYYMMDD no seu selector.

XML

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
...
<dateRange>
  <min>20150201</min>
  <max>20150301</max>
</dateRange>
  </selector>
  <dateRangeType>CUSTOM_DATE</dateRangeType>
</reportDefinition>

AWQL

...
DURING 20150201,20150301

Atualização de dados

Algumas estatísticas mostradas nos seus relatórios podem ser calculadas de forma contínua, enquanto outras podem ser calculadas uma vez por dia. Esse é um aspecto de como a atualização de dados funciona no Google AdWords. Para usar os relatórios com eficácia, consulte a documentação sobre atualização de dados.

Preparar a solicitação

Depois de criar sua definição de relatório, você pode preparar a solicitação de HTTP POST.

É possível fazer solicitações de HTTP simples e síncronas diretamente para o servidor do Google AdWords. Devido aos baixos custos indiretos dessa abordagem, ela é adequada para relatórios de alto volume, especialmente quando implementada usando vários threads (recomendamos começar com 10). A solicitação de HTTP é síncrona porque a chamada é efetivamente bloqueada até que os dados do relatório estejam prontos para o download.

Você provavelmente alcançará o limite de consultas por segundo (QPS, na sigla em inglês) (RateExceededError) antes de exceder o número de conexões em aberto permitidas no servidor. As solicitações de relatório não são contabilizadas na cota de operações diárias, mas há um limite de downloads de relatórios por dia.

Para a definição de relatório XML, o corpo da solicitação POST precisa conter um parâmetro chamado "__rdxml", cujo valor é sua definição de relatório XML.

Cabeçalhos de solicitação

Use os valores normais do cabeçalho HTTP ao fazer o download de relatórios:

Cabeçalho HTTP Descrição
Authorization: Bearer OAUTH2_ACCESS_TOKEN Autorização para fazer o download do relatório. Use o mesmo accessToken usado para o cabeçalho de solicitação SOAP.
developerToken: DEVELOPER_TOKEN Seu token de desenvolvedor, que consiste em uma única string, por exemplo 1a2B3c4D5e_-6v7w8x9y0z.
clientCustomerId: CLIENT_CUSTOMER_ID ID do cliente da conta.

É possível especificar os seguintes cabeçalhos HTTP opcionais se o relatório inclui uma linha de cabeçalho ou de resumo:

Cabeçalho HTTP opcional Descrição
skipReportHeader: true|false Se for true, a saída do relatório não incluirá uma linha de cabeçalho contendo o nome e o período do relatório. Se for false ou não especificado, a saída do relatório incluirá a linha do cabeçalho.
skipColumnHeader: true|false Se for true, a saída do relatório não incluirá uma linha de cabeçalho contendo os nomes dos campos. Se for false ou não especificado, a saída do relatório incluirá os nomes dos campos.
skipReportSummary: true|false Se for true, a saída do relatório não incluirá uma linha de resumo contendo os totais do relatório. Se for false ou não especificado, a saída do relatório incluirá a linha de resumo.
useRawEnumValues: true|false Defina como true se você quiser que o formato retornado seja o valor real enumerado, por exemplo, "IMAGE_AD" em vez de "Image ad". Defina como false ou omita este cabeçalho se você quiser que o formato retornado seja o valor de exibição.
includeZeroImpressions: true|false Se for true, a saída do relatório incluirá linhas em que todos os campos de métricas especificados sejam zero, contanto que os campos e predicados solicitados sejam compatíveis com zero impressões. Se for false, a saída do relatório não incluirá essas linhas. Dessa forma, ainda que esse cabeçalho seja false e as Impressions de uma linha sejam zero, a linha ainda será retornada se algum dos campos de métricas tiver valores diferentes de zero. Se essa opção for omitida, o relatório usará o comportamento padrão descrito no guia de zero impressões.

URL de solicitação de HTTP

A solicitação consiste em um HTTP POST para o servidor do Google AdWords no URL a seguir:

https://adwords.google.com/api/adwords/reportdownload/v201609

Exemplo completo

Veja um exemplo completo que mostra a definição de relatório acima incluída em uma solicitação de HTTP POST.

XML

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: /
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 784
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559

Parameters:
__rdxml: &lt;?xml version="1.0" encoding="UTF-8"?&gt;
<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201609">
  <selector>
    <fields>CampaignId</fields>
    <fields>AdGroupId</fields>
    <fields>Impressions</fields>
    <fields>Clicks</fields>
    <fields>Cost</fields>
    <predicates>
      <field>AdGroupStatus</field>
      <operator>IN</operator>
      <values>ENABLED</values>
      <values>PAUSED</values>
    </predicates>
  </selector>
  <reportName>Custom Adgroup Performance Report</reportName>
  <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
  <dateRangeType>LAST_7_DAYS</dateRangeType>
  <downloadFormat>CSV</downloadFormat>
</reportDefinition>

AWQL

POST /api/adwords/reportdownload/v201609 HTTP/1.1
Host: adwords.google.com
User-Agent: curl, gzip
Accept: */*
Accept-Encoding: gzip
Authorization: Bearer [Enter OAuth 2.0 access token here]
developerToken: [Enter developerToken here]
clientCustomerId: [Enter clientCustomerID here]
Content-Length: 182
Expect: 100-continue
Content-Type: multipart/form-data; boundary=------------------------12d01fae60c7b559
 
Parameters:
__fmt: CSV
__rdquery: SELECT CampaignId, AdGroupId, Impressions, Clicks, Cost \
FROM ADGROUP_PERFORMANCE_REPORT \
WHERE AdGroupStatus IN [ENABLED, PAUSED] DURING LAST_7_DAYS

Códigos de resposta

Se a solicitação de relatório for bem-sucedida, o servidor retornará um código de resposta 200.

Um código de resposta 400 indica um erro de API. Verifique se há problemas com o XML na sua definição de relatório.

Um código de resposta 500 normalmente indica um problema temporário com o servidor. Se esse erro ocorrer, tente a solicitação novamente depois de alguns momentos.

Relatórios de várias contas

Uma determinada solicitação de relatório pode incluir apenas dados de uma única conta do Google AdWords. Se você precisar reunir dados de relatório para várias contas, envie uma outra solicitação de relatório para cada conta definindo o cabeçalho clientCustomerId descrito acima.

Tempo limite

A solicitação de download de relatório pode exceder o tempo limite em conjuntos de dados extremamente grandes. Não há limite de tamanho de dados explícito. No entanto, devido a diversos fatores, o servidor poderá retornar um erro se o relatório for muito grande.

Se você encontrar problemas de tempo limite ou erros, teste um período mais curto ou use predicados para dividir as solicitações de relatório em várias solicitações menores. Por exemplo, em vez de gerar um único relatório para todas as campanhas, você pode enviar várias solicitações, cada uma filtrando um subconjunto de IDs da campanha.

Formatos de download compatíveis

Formato Descrição
CSVFOREXCEL O formato do Excel. Ele usa um formato unicode que é pré-demarcado com um BOM (marcador de ordem de byte) para informar ao Excel que ele é unicode. Quando o unicode está sendo usado, o padrão do Excel é usar tabulações como separador. Se vírgulas são usadas, o Excel coloca todos os dados de cada linha em uma única coluna (por padrão).
CSV O formato de saída CSV (separado por vírgula).
TSV O formato de saída TSV (separado por tabulação).
XML O formato de saída XML.
GZIPPED_CSV O formato de saída CSV (separado por vírgula) compactado com GZIP.
GZIPPED_XML O formato de saída XML compactado com GZIP.

Como escolher o relatório certo

Como existem várias opções de relatórios disponíveis na AdWords API, definir o relatório certo para uma determinada empresa pode ser uma tarefa difícil.

Use a tabela abaixo para determinar o relatório mais adequado e, em seguida, confira os detalhes dele na página Tipos de relatório.

Segmentação

Para estatísticas mais detalhadas, você pode dividir os dados por segmentos. Por exemplo, talvez você queira saber o número de impressões específicas da rede de pesquisa do Google separadamente das impressões da Rede de Display do Google. Nesse caso, convém segmentar seu relatório por rede.

A segmentação, que está disponível na IU como um menu separado, é alcançada na API apenas adicionando o campo certo ao relatório. Por exemplo, a inclusão do campo AdNetworkType1 a um Relatório de desempenho do grupo de anúncios resulta em um relatório com uma linha para cada combinação de grupo de anúncios e rede, com os valores estatísticos (impressões, cliques, conversões etc.) divididos entre eles. Enquanto na IU somente um segmento por vez pode ser usado para a Rede de Display, na API, é possível combinar vários segmentos no mesmo relatório. Tenha em mente que a quantidade de linhas pode aumentar exponencialmente para cada campo de segmento adicional incluído no seu relatório.

Segmentação implícita

Cada relatório é segmentado por uma chave única. Por exemplo, o Relatório de desempenho de palavras-chave é implicitamente segmentado por Id e AdGroupId, mesmo que eles não estejam incluídos nos campos do seletor dessa forma, porque a palavra-chave é identificada por Id e por AdGroupId.

Keyword,MatchType,Impressions
Keyword1,Exact,3
Keyword2,Exact,10
Keyword3,Exact,5
Keyword4,Broad,4

Atribuição única e múltipla

Quando uma impressão ocorre na Rede de Display, os critérios que desempenham um papel nessa ocorrência podem ser registrados de uma maneira (de uma possibilidade de duas): atribuição única ou atribuição múltipla.

Atribuição única

Com a atribuição única, apenas um dos critérios de acionamento (como canal, idade, palavra-chave etc.) é registrado para uma determinada impressão. Uma impressão pode ser acionada por vários critérios, mas em um Relatório de atribuição única a impressão e todas as estatísticas dela são atribuídas a um único critério.

Cada impressão é contabilizada apenas uma vez (em um critério). A soma de todos os critérios resulta em valores que correspondem aos totais nos Relatórios de atribuição múltipla.

Os Relatórios de desempenho de critérios e desempenho de palavras-chave usam esse modelo.

Exemplo de relatório

O exemplo abaixo mostra um Relatório de desempenho de critérios (atribuição única) para uma campanha segmentada apenas para a Rede de Display, e usando apenas indústrias e canais como critérios. O relatório mostra um total de 10 impressões em cinco linhas, uma linha para cada um dos três canais e uma linha para cada uma das duas indústrias que acionaram impressões: cada uma recebendo duas impressões.

Keyword / Placement,Impressions
www.example.com,2
www.example.ca,2
www.example.net,2
Computers & Electronics,2
Sports,2

Atribuição múltipla

Com a atribuição múltipla, até um critério em cada dimensão que acionou a impressão terá a impressão registrada para ele. Vários relatórios de atribuição podem ser vistos como relatórios específicos por tipo de critério: ao contrário dos Relatórios de atribuição única, em que uma linha pode conter tipos de critérios diferentes, cada Relatório de atribuição múltipla contém critérios de somente um tipo.

Por exemplo, o Relatório de desempenho por sexo resume todas as suas impressões por sexo, enquanto o Relatório de desempenho por faixa etária resume as impressões por faixa etária e assim por diante. Os Relatórios de desempenho por tópicos da Rede de Display e de desempenho em canais também seguem esse modelo.

Ao contrário dos Relatórios de atribuição única, os Relatórios de atribuição múltipla NÃO devem ser compilados em conjunto, pois isso pode dobrar a contagem de impressões e cliques.

Exemplo

Topic,Impressions
Computers & Electronics,6
Sports,4

Placement,Impressions
www.example.com,4
www.example.ca,3
www.example.net,3

Se você segmentar apenas a Rede de Display com indústrias (tópicos) e canais e gerar um Relatório de tópicos da Rede de Display, terá uma linha para cada indústria (tópico) que acionou impressões. Da mesma forma, um Relatório de desempenho de canais retorna uma linha por impressões. Esses relatórios estão cobrindo as mesmas impressões, pois até uma indústria e um canal serão atribuídos a cada impressão.

KeywordId=3000000

Nos Relatórios de atribuição única, todas as palavras-chave que acionarem impressões na Rede de Display serão representadas por uma palavra-chave especial (texto: Content) com ID 3000000.

Exemplo
Keyword ID,Impressions
23458623485,2
23655322314,2
23953456345,2
3000000,4

Se você segmentar palavras-chave e canais apenas na Rede de Display e gerar um Relatório de desempenho de anúncios, terá uma linha para cada anúncio e uma combinação de critérios de acionamento para canais, e uma única linha com anúncio e ID 3000000 responsável por todas as palavras-chave da Rede de Display que acionaram esse anúncio (em que a atribuição única escolheu a palavra-chave, em vez de um canal).

KeywordId=3000004

O ID de critérios 3000004 foi usado para um recurso que já foi removido do Google AdWords.

KeywordId=3000006

O ID de critérios 3000006 representa estatísticas associadas ao Otimizador de campanhas da Rede de Display.

Formato de vários campos

Embora todos os campos retornados em relatórios tenham um Type, os valores reais retornados nem sempre corresponderão a esses valores. Você deve sempre verificar a coluna Observações, que geralmente contém informações adicionais sobre o formato esperado dos valores. Por exemplo, na coluna "Observações" de ConversionRate há: Percentage returned as "x.xx%".

Campos de valores em dinheiro em relatórios

Os campos de tipo Money são retornados em microunidades monetárias (micros). No entanto, eles podem receber o prefixo "auto" ou simplesmente ser o string "auto", caso os lances automáticos sejam usados. Por exemplo, R$ 1,23 é retornado como 1230000 (1,23 x 1.000.000). Os valores micro sempre se referem à moeda local da conta.

Ao filtrar pelos campos de valores em dinheiro, você precisa fornecer o valor em micros. Por exemplo, WHERE AverageCpc > 1000000 retorna linhas em que AverageCpc é maior do que R$ 1,00 (uma unidade da moeda da conta).

Índice de qualidade em relatórios

O Índice de qualidade é representado nos Relatórios de desempenho de palavras-chave e desempenho de critérios como uma pontuação de 1 (mais baixa) a 10 (mais alta).

Antes da versão v201607, era retornado um Índice de qualidade 6 para palavras-chave que não tinham impressões ou cliques suficientes para determinar um Índice de qualidade, como palavras-chave novas ou antigas que não acionavam a veiculação de anúncios há muito tempo. Um índice de qualidade 0 era retornado para as palavras-chave excluídas e palavras-chave da Rede de Display cujo Índice de qualidade não podia ser determinado. A partir da versão v201607, um valor de dois traços (--) é usado para indicar que não há um Índice de qualidade disponível para uma palavra-chave. Além disso, uma nova coluna chamada HasQualityScore foi adicionada na versão v201605 para permitir que você filtre com facilidade por palavras-chave que não têm nenhum Índice de qualidade disponível. Por exemplo, a consulta AWQL a seguir seleciona palavras-chave que têm um Índice de qualidade válido.

SELECT CampaignId, AdGroupId, Id, Criteria, CriteriaType, QualityScore FROM
    CRITERIA_PERFORMANCE_REPORT WHERE Status IN [ENABLED, PAUSED] and
    HasQualityScore='TRUE'

Dois traços

Um valor de dois traços (--) indica que não há valor para a célula.

Listas e mapas

Os itens de uma lista serão formatados usando JSON. Por exemplo, um Scheduling no valor PLACEHOLDER_FEED_ITEM_REPORT seria composto por um conjunto de strings:

["Monday, 6:00PM - 9:00PM","Tuesday, 6:00PM - 9:00PM","Wednesday,6:00PM - 9:00PM",
"Thursday, 6:00PM - 9:00PM","Friday, 6:00PM - 9:00PM"]

Do mesmo modo, para um mapa (como UrlCustomParameters):

{"param0":"value0","param1":"value1"}

Enviar comentários sobre…

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