Consultar dados de relatórios

O método reportData.query oferece uma maneira síncrona de recuperar dados de relatórios. Ao contrário do serviço Reports padrão, que gera relatórios baseados em arquivos (CSV ou Excel), esse método retorna dados JSON estruturados diretamente na resposta. Ele elimina a necessidade de definir, criar e salvar um recurso Report com antecedência, tornando-o ideal para recuperação e exploração de dados em tempo real.

Visão geral

Siga este guia para se familiarizar com o uso desse endpoint para consultar os dados de relatórios do Campaign Manager 360.

Preparar a solicitação

Crie um ReportDataQueryRequest especificando as dimensões, métricas, período, filtros e critérios de classificação.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Um DateRange objeto que especifica o período da consulta. Pode ser um período personalizado ou relativo.
dimensionNames
Uma lista de nomes de dimensões padrão para agrupar.
metricNames
Obrigatório. Uma lista de nomes de métricas padrão a serem incluídos.
dimensionFilters
Uma lista de DimensionValue usados para filtrar os dados do relatório. Use isso para restringir os resultados da consulta a valores específicos de uma dimensão.
sortBys
Configurações de classificação para dimensões ou métricas. Cada configuração inclui o nome do campo e uma ordem de classificação.
maxResults
O número máximo de linhas a serem retornadas por página (padrão: 100, máximo: 1000).

Paginação

O campo maxResults controla o número de resultados retornados em uma única resposta. Por exemplo, se você definir maxResults como 10, a API vai retornar no máximo 10 resultados. É possível que a API retorne menos de 10 resultados se houver menos de 10 resultados que correspondam à sua solicitação.

Se houver mais resultados disponíveis, a resposta vai incluir um nextPageToken. Para recuperar a próxima página de resultados, envie a mesma solicitação novamente com o campo pageToken definido como esse token. Mantenha todos os outros parâmetros de solicitação iguais.

Enviar a solicitação

Envie uma solicitação POST HTTP para o reportdata/query endpoint:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

Verifique se a solicitação está autenticada com as credenciais OAuth 2.0 padrão e os escopos necessários. Consulte Autorizar solicitações para mais informações.

Resposta bem-sucedida

Uma consulta bem-sucedida retorna uma resposta HTTP 200 OK com um payload JSON contendo columnHeaders, rows e totalRow.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}
columnHeaders
O nome e os tipos (DIMENSION ou METRIC) dos campos retornados.
rows
Uma lista de ReportDataRow objetos que contêm os resultados da consulta. Os valores de string em cada linha são alinhados por posição com os columnHeaders.
totalRow
Uma única linha agregada que representa a soma de todas as métricas correspondentes. Os campos de dimensão e as métricas que não podem ser somados (por exemplo, métricas de alcance como uniqueReachTotalReach) estão vazios ("") nessa linha.
nextPageToken
Um token usado em uma solicitação subsequente para recuperar a próxima página, se houver mais linhas.

Latência e tempos limite

Como esse é um endpoint síncrono, as consultas são executadas imediatamente e os dados são retornados diretamente na resposta (até o limite de paginação maxResults). As consultas têm um tempo máximo de execução de 60 segundos. Se uma consulta exceder esse limite, a API vai encerrar a operação e retornar um HTTP 503 Service Unavailable erro.

Se você encontrar esse erro, tente reduzir o período, restringir os filtros (como filtrar por anunciantes ou campanhas específicos) ou reduzir o número de dimensões e métricas solicitadas. Como alternativa, execute um Report usando reports.run para gerar um arquivo de relatório para download de forma assíncrona.

Limites e restrições de consulta

O reportdata.query endpoint aplica vários limites para garantir respostas confiáveis. As solicitações que violam essas restrições são rejeitadas com uma resposta HTTP 400 Bad Request.

Limites de período

  • Para períodos personalizados, o startDate precisa estar dentro do período de disponibilidade de dados para o tipo de dados de relatório solicitado. Para mais detalhes, consulte Disponibilidade de dados.

Restrições de métricas e dimensões

  • Pelo menos uma métrica precisa ser fornecida em metricNames.
  • As métricas e dimensões nas listas metricNames e dimensionNames precisam ser exclusivas.
  • As métricas e dimensões marcadas como "Apenas para download" não podem ser usadas em estas consultas.

Limites de cota

As solicitações para esse endpoint consomem as seguintes cotas:

  • Limite de taxa de usuário:120 solicitações por minuto por usuário (2 QPS)
  • Limite diário por projeto:10.000 solicitações por dia por projeto

As solicitações que excedem esses limites falham com um erro HTTP 429 Too Many Requests. Se você paginar os resultados, cada solicitação de uma nova página (usando o parâmetro pageToken) será contabilizada como uma consulta separada e consumirá essa cota.