Solicitar relatórios

Depois de configurar o app cliente conforme descrito em Meu primeiro app, use a API Search Ads 360 para solicitar e fazer o download de relatórios. É possível fazer um dos seguintes tipos de solicitação:

Síncrono

Requer apenas uma solicitação e retorna o relatório em uma resposta formatada em JSON. Solicitações síncronas:

• Pode retornar somente relatórios de anunciantes e de contas de mecanismo
• Bloquear seu cliente até que o Search Ads 360 gere o relatório

Se você solicitar grandes relatórios de contas de mecanismo ou anunciantes, recomendamos a abordagem assíncrona.

Assíncrono

Exige que você envie uma solicitação inicial que especifique os dados desejados no relatório. Depois, você envia outras solicitações para pesquisar no Search Ads 360. Quando o Search Ads 360 terminar de gerar o relatório, você enviará solicitações para fazer o download dele como um ou mais arquivos. Solicitações assíncronas:

• Pode retornar qualquer tipo de relatório.
• Fragmenta relatórios muito grandes em vários arquivos
• Formata relatórios como CSV ou TSV

Modelo de dados: linhas e colunas

O Search Ads 360 organiza os dados de um relatório em linhas e colunas. O tipo de relatório solicitado determina as linhas retornadas. Por exemplo, se você solicitar um relatório de palavras-chave, cada linha conterá dados sobre uma única palavra-chave. Consulte a referência Tipos de relatório para ver uma lista com todos os tipos de relatório. Para especificar quais colunas quer incluir no relatório, nomeie cada uma na solicitação. Consulte a referência Tipos de relatório para ver a lista de colunas que podem ser retornadas em cada tipo de relatório.

Comportamentos das colunas

O comportamento de uma coluna depende do tipo de dados que ela contém (a referência Tipos de relatório exibe o comportamento de cada coluna):

• Colunas de atributos. Uma coluna de atributos contém dados que configuram ou identificam uma entidade em uma campanha, como o nome da campanha ou um lance de palavra-chave. A API Search Ads 360 sempre retorna o valor atual de uma coluna de atributo, independentemente da data ou do período especificado em uma solicitação. Por exemplo, se você alterou o lance de uma palavra-chave de 2,00 para 1,50 ontem e, em seguida, solicitou um relatório com os dados do mês passado, o relatório retornará um valor de 1,50.

• Colunas de métricas. Uma coluna de métrica contém dados sobre o desempenho da sua campanha, como o número de cliques em um anúncio, o número de visitas conforme registrado por uma tag do Floodlight ou a receita. A menos que você especifique um período de um único dia, a API retornará um valor agregado para as colunas de métricas. Por exemplo, se você solicitar um relatório com os dados do mês passado, a API retornará o número total de cliques do mês passado.

• Segmentar colunas Uma coluna de segmento divide os dados em linhas separadas. Por exemplo, date é uma coluna de segmento que pode ser especificada para diversos tipos de relatórios. Se você especificar a coluna date em um relatório de palavra-chave com o período de 01/01/2013 a 07/01/2013, a API retornará sete linhas para cada palavra-chave, cada uma correspondente a um dia e exibindo as métricas desse dia. Consulte Relatórios segmentados.

Moedas

Sua solicitação de relatório é obrigatória para especificar a moeda dos dados monetários (tanto atributos como dailyBudget quanto métricas como cost). É possível especificar uma das seguintes opções:

• A moeda da agência, se o escopo do relatório for de uma agência, um anunciante ou uma conta de mecanismo.
• A moeda do anunciante, se o escopo do relatório for um anunciante ou uma conta de mecanismo.
• A moeda da conta de mecanismo, se o escopo do relatório for uma conta de mecanismo.
• USD

Use a propriedade de solicitação Reports.request.statisticsCurrency para especificar uma moeda.

O relatório vai indicar a moeda na propriedade Reports.statisticsCurrencyCode.

Fuso horário

As métricas do Search Ads 360 são armazenadas em datas sem fusos horários. Essas datas correspondem ao fuso horário da conta de mecanismo para as métricas de mecanismo (como cliques, impressões e visitas) e ao fuso horário da rede do Campaign Manager para métricas de conversão (como ações, transações e receita). Quando todas as métricas em um relatório vierem do mesmo fuso horário, esse fuso horário será retornado na solicitação. Caso contrário, nenhum fuso horário será retornado. Suas solicitações podem configurar Reports.request.verifySingleTimeZone: true para gerar relatórios de falha que apresentam métricas de mais de um fuso horário.

Se todas as métricas presentes em um relatório forem de um fuso horário, esse fuso horário será retornado em Reports.statisticsTimeZoneReports.