Dati del report sulle query

Il metodo reportData.query fornisce un modo sincrono per recuperare i dati dei report. A differenza del servizio Reports standard, che genera report basati su file (CSV o Excel), questo metodo restituisce dati JSON strutturati direttamente nella risposta. Elimina la necessità di definire, creare e salvare in anticipo una risorsa Report, il che lo rende ideale per il recupero e l'esplorazione dei dati in tempo reale.

Panoramica

Segui questa guida per imparare a utilizzare questo endpoint per eseguire query sui dati dei report di Campaign Manager 360.

Prepara la richiesta

Crea un ReportDataQueryRequest specificando le dimensioni, le metriche, l'intervallo di date, i filtri e i criteri di ordinamento.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
Un oggetto DateRange che specifica il periodo di tempo per la query. Può essere un intervallo di date personalizzato o un intervallo di date relativo.
dimensionNames
Un elenco di nomi di dimensioni standard in base a cui raggruppare.
metricNames
Obbligatorio. Un elenco di nomi di metriche standard da includere.
dimensionFilters
Un elenco di DimensionValue utilizzati per filtrare i dati dei report. Utilizzalo per limitare i risultati della query a valori specifici di una dimensione.
sortBys
Configurazioni di ordinamento per dimensioni o metriche. Ogni configurazione include il nome del campo e un ordine di ordinamento.
maxResults
Il numero massimo di righe da restituire per pagina (valore predefinito: 100, massimo: 1000).

Impaginazione

Il campo maxResults controlla il numero di risultati restituiti in una singola risposta. Ad esempio, se imposti maxResults su 10, l'API restituirà al massimo 10 risultati. È possibile che l'API restituisca meno di 10 risultati se sono disponibili meno di 10 risultati che corrispondono alla tua richiesta.

Se sono disponibili altri risultati, la risposta include un nextPageToken. Per recuperare la pagina successiva dei risultati, invia di nuovo la stessa richiesta con il campo pageToken impostato su questo token. Mantieni invariati tutti gli altri parametri della richiesta.

Invia la richiesta

Invia una richiesta HTTP POST all'reportdata/query endpoint:

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

Assicurati che la richiesta sia autenticata con le credenziali OAuth 2.0 standard e gli ambiti necessari. Per saperne di più, consulta Autorizzare le richieste.

Operazione riuscita

Una query riuscita restituisce una risposta HTTP 200 OK con un payload JSON contenente 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
Il nome e i tipi (DIMENSION o METRIC) dei campi restituiti.
rows
Un elenco di ReportDataRow oggetti contenenti i risultati della query. I valori stringa in ogni riga sono allineati per posizione con columnHeaders.
totalRow
Una singola riga di aggregazione che rappresenta la somma di tutte le metriche corrispondenti. I campi delle dimensioni e le metriche che non possono essere sommati (ad esempio, le metriche di copertura come uniqueReachTotalReach) sono vuoti ("") in questa riga.
nextPageToken
Un token utilizzato in una richiesta successiva per recuperare la pagina successiva se esistono altre righe.

Latenza e timeout

Poiché si tratta di un endpoint sincrono, le query vengono eseguite immediatamente e i dati vengono restituiti direttamente nella risposta (fino al limite di impaginazione maxResults). Le query hanno un tempo di esecuzione massimo di 60 secondi. Se una query supera questo limite, l'API termina l'operazione e restituisce un HTTP 503 Service Unavailable errore.

Se riscontri questo errore, prova a restringere l'intervallo di date, i filtri (ad esempio, filtrando in base a inserzionisti o campagne specifici) o a ridurre il numero di dimensioni e metriche richieste. In alternativa, esegui un Report utilizzando reports.run per generare in modo asincrono un file di report scaricabile.

Limiti e vincoli delle query

L'reportdata.query endpoint applica diversi limiti per garantire risposte affidabili. Le richieste che violano questi vincoli vengono rifiutate con una risposta HTTP 400 Bad Request.

Limiti dell'intervallo di date

  • Per gli intervalli di date personalizzati, startDate deve rientrare nel periodo di disponibilità dei dati per il tipo di dati dei report richiesto. Per saperne di più, consulta Disponibilità dei dati.

Vincoli di metriche e dimensioni

  • È necessario fornire almeno una metrica in metricNames.
  • Le metriche e le dimensioni negli elenchi metricNames e dimensionNames devono essere univoche.
  • Le metriche e le dimensioni etichettate come Solo download non possono essere utilizzate in queste query.

Limiti di quota

Le richieste a questo endpoint consumano le seguenti quote:

  • Limite di frequenza per utente: 120 richieste al minuto per utente (2 QPS)
  • Limite giornaliero per progetto: 10.000 richieste al giorno per progetto

Le richieste che superano questi limiti non vanno a buon fine e viene restituito un errore HTTP 429 Too Many Requests. Se esegui la paginazione dei risultati, ogni richiesta di una nuova pagina (utilizzando il parametro pageToken) viene conteggiata come una query separata e consuma questa quota.