Consulta datos del informe

El método reportData.query proporciona una forma síncrona de recuperar datos de informes. A diferencia del servicio Reports estándar, que genera informes basados en archivos (CSV o Excel), este método muestra datos JSON estructurados directamente en la respuesta. Elimina la necesidad de definir, crear y guardar un recurso Report de antemano, lo que lo hace ideal para la exploración y la recuperación de datos en tiempo real.

Descripción general

Consulta esta guía para familiarizarte con el uso de este extremo para consultar los datos de informes de Campaign Manager 360.

Prepara la solicitud

Crea un ReportDataQueryRequest en el que se especifiquen las dimensiones, las métricas, el período, los filtros y los criterios de ordenamiento.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Un objeto DateRange que especifica el período de la consulta. Puede ser un período personalizado o relativo.
dimensionNames
Una lista de nombres de dimensiones estándar para agrupar.
metricNames
Obligatorio. Una lista de nombres de métricas estándar para incluir.
dimensionFilters
Una lista de DimensionValue que se usan para filtrar los datos del informe. Úsala para restringir los resultados de la consulta a valores específicos de una dimensión.
sortBys
Configuraciones de ordenamiento para dimensiones o métricas. Cada configuración incluye el nombre del campo y un orden de ordenamiento.
maxResults
La cantidad máxima de filas que se mostrarán por página (predeterminado: 100, máximo: 1000).

Paginación

El campo maxResults controla la cantidad de resultados que se muestran en una sola respuesta. Por ejemplo, si configuras maxResults como 10, la API mostrará como máximo 10 resultados. Es posible que la API muestre menos de 10 resultados si hay menos de 10 resultados que coincidan con tu solicitud.

Si hay resultados adicionales disponibles, la respuesta incluye un nextPageToken. Para recuperar la siguiente página de resultados, vuelve a enviar la misma solicitud con el campo pageToken configurado en este token. No cambies los demás parámetros de solicitud.

Envía la solicitud

Envía una solicitud HTTP POST al reportdata/query extremo:

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

Asegúrate de que tu solicitud esté autenticada con las credenciales estándar de OAuth 2.0 y los permisos necesarios. Consulta Autoriza solicitudes para obtener más información.

Respuesta correcta

Una consulta correcta muestra una respuesta HTTP 200 OK con una carga útil de JSON que contiene columnHeaders, rows y 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
El nombre y los tipos (DIMENSION o METRIC) de los campos que se muestran.
rows
Una lista de ReportDataRow objetos que contienen los resultados de la consulta. Los valores de cadena de cada fila se alinean por posición con los columnHeaders.
totalRow
Una sola fila agregada que representa la suma de todas las métricas coincidentes. Los campos de dimensión y las métricas que no se pueden sumar (por ejemplo, las métricas de alcance como uniqueReachTotalReach) están vacíos ("") en esta fila.
nextPageToken
Un token que se usa en una solicitud posterior para recuperar la siguiente página si existen filas adicionales.

Latencia y tiempos de espera

Como se trata de un extremo síncrono, las consultas se ejecutan de inmediato y los datos se muestran directamente en la respuesta (hasta el límite de paginación de maxResults). Las consultas tienen un tiempo de ejecución máximo de 60 segundos. Si una consulta excede este límite, la API finaliza la operación y muestra un HTTP 503 Service Unavailable error.

Si encuentras este error, intenta acotar el período, acotar los filtros (por ejemplo, filtrar por anunciantes o campañas específicos) o reducir la cantidad de dimensiones y métricas solicitadas. Como alternativa, ejecuta un Report con reports.run para generar un archivo de informe descargable de forma asíncrona.

Límites y restricciones de las consultas

El reportdata.query extremo aplica varios límites para garantizar respuestas confiables. Las solicitudes que incumplen estas restricciones se rechazan con una respuesta HTTP 400 Bad Request.

Límites de períodos

  • Para los períodos personalizados, el startDate debe estar dentro del período de disponibilidad de datos para el tipo de datos del informe solicitado. Para obtener más detalles, consulta Disponibilidad de los datos.

Restricciones de métricas y dimensiones

  • Se debe proporcionar al menos una métrica en metricNames.
  • Las métricas y las dimensiones de las listas metricNames y dimensionNames deben ser únicas.
  • Las métricas y las dimensiones etiquetadas como Solo descarga no se pueden usar en estas consultas.

Límites de cuota

Las solicitudes a este extremo consumen las siguientes cuotas:

  • Límite de frecuencia por usuario: 120 solicitudes por minuto por usuario (2 QPS)
  • Límite diario por proyecto: 10,000 solicitudes por día por proyecto

Las solicitudes que excedan estos límites fallarán con un error HTTP 429 Too Many Requests. Si paginas los resultados, cada solicitud de una página nueva (con el parámetro pageToken) se cuenta como una consulta independiente y consume esta cuota.