YouTube Reporting API - Get Bulk Data Reports

YouTube genera automaticamente una serie di report sulle entrate pubblicitarie gestiti dal sistema per i proprietari dei contenuti che hanno accesso ai report corrispondenti in Creator Studio. Questi report sono progettati per fornire l'accesso programmatico ai dati disponibili anche nei report scaricabili manualmente accessibili nel menu Report di YouTube Creator Studio.

Nota:l'API fornisce l'accesso a un insieme di report diverso da Creator Studio, anche se i report contengono dati simili. I report API potrebbero avere campi diversi e utilizzare anche nomi di campi diversi rispetto ai report di Creator Studio.

Poiché YouTube genera automaticamente i report gestiti dal sistema, la procedura per recuperare questi report è diversa da quella per i report sui dati collettivi di YouTube Analytics disponibili tramite l'API.

Recupero dei report

I passaggi seguenti spiegano come recuperare i report gestiti dal sistema tramite l'API.

Passaggio 1: recupera le credenziali di autorizzazione

Tutte le richieste all'API YouTube Reporting devono essere autorizzate. La guida all'autorizzazione spiega come utilizzare il protocollo OAuth 2.0 per recuperare i token di autorizzazione.

Le richieste all'API YouTube Reporting utilizzano i seguenti ambiti di autorizzazione:

Passaggio 2: recupera l'ID job per il report desiderato

Chiama il metodo jobs.list per recuperare un elenco di job gestiti dal sistema. Imposta il parametro includeSystemManaged su true.

La proprietà reportTypeId in ogni risorsa Job restituita identifica il tipo di report gestito dal sistema associato a quel job. Nel passaggio successivo, l'applicazione ha bisogno del valore della proprietà id della stessa risorsa.

Il documento Report elenca i report disponibili, i relativi ID tipo di report e i campi che contengono. Puoi anche utilizzare il metodo reportTypes.list per recuperare un elenco dei tipi di report supportati.

Passaggio 3: recupera l'URL di download del report

Chiama il metodo jobs.reports.list per recuperare un elenco di report creati per il job. Nella richiesta, imposta il parametro jobId sull'ID job del report che vuoi recuperare.

Puoi filtrare l'elenco dei report utilizzando uno o tutti i seguenti parametri:

• Utilizza il parametro createdAfter per indicare che l'API deve restituire solo i report creati dopo un determinato orario. Questo parametro può essere utilizzato per garantire che l'API restituisca solo i report che non hai ancora elaborato.

• Utilizza il parametro startTimeBefore per indicare che la risposta dell'API deve contenere report solo se i dati meno recenti del report sono precedenti alla data specificata. Mentre il parametro createdAfter si riferisce al momento della creazione del report, questa data si riferisce ai dati nel report.

• Utilizza il parametro startTimeAtOrAfter per indicare che la risposta dell'API deve contenere report solo se i dati meno recenti del report sono stati registrati a partire dalla data specificata. Come il parametro startTimeBefore, questo valore del parametro corrisponde ai dati nel report e non all'ora in cui è stato creato.

La risposta dell'API contiene un elenco di risorse Report per il job. Ogni risorsa si riferisce a un report che contiene dati per un periodo univoco.

• Le proprietà startTime e endTime della risorsa identificano il periodo di tempo coperto dai dati del report.
• La proprietà downloadUrl della risorsa identifica l'URL da cui è possibile recuperare il report.
• La proprietà createTime della risorsa specifica la data e l'ora in cui è stato generato il report. La tua applicazione deve memorizzare questo valore e utilizzarlo per determinare se i report scaricati in precedenza sono stati modificati.

Passaggio 4: scarica il report

Invia una richiesta HTTP GET all'downloadUrl ottenuto nel passaggio 4 per recuperare il report.

Elaborazione dei report

Best practice

Le applicazioni che utilizzano l'API YouTube Reporting devono sempre seguire queste pratiche:

• Utilizza la riga di intestazione di un report per determinare l'ordine delle colonne del report. Ad esempio, non dare per scontato che le visualizzazioni saranno la prima metrica restituita in un report solo perché è la prima metrica elencata nella descrizione di un report. Utilizza invece la riga di intestazione del report per determinare la colonna contenente i dati.

• Tieni un registro dei report che hai scaricato per evitare di elaborare ripetutamente lo stesso report. Il seguente elenco suggerisce un paio di modi per farlo.

  • Quando chiami il metodo reports.list, utilizza il parametro createdAfter per recuperare solo i report creati dopo una determinata data. (Ometti il parametro createdAfter la prima volta che recuperi i report.)

    Ogni volta che recuperi ed elabori correttamente i report, memorizza il timestamp corrispondente alla data e all'ora in cui è stato creato il più recente. Poi, aggiorna il valore del parametro createdAfter a ogni chiamata successiva al metodo reports.list per assicurarti di recuperare solo i nuovi report, inclusi quelli con dati di riempimento, ogni volta che chiami l'API.

    Come misura di sicurezza, prima di recuperare un report, verifica anche che il relativo ID non sia già presente nel tuo database.

  • Memorizza l'ID di ogni report che hai scaricato ed elaborato. Puoi anche memorizzare informazioni aggiuntive come la data e l'ora in cui è stato generato ogni report o il startTime e il endTime del report, che insieme identificano il periodo per il quale il report contiene dati. Per i report che recuperano dati collettivi per YouTube Analytics, ogni job avrà probabilmente molti report, poiché ogni report contiene dati per un periodo di 24 ore. I job gestiti dal sistema che coprono periodi di tempo più lunghi avranno meno report.

    Utilizza l'ID report per identificare i report che devi ancora scaricare e importare. Tuttavia, se due nuovi report hanno gli stessi valori delle proprietà startTime e endTime, importa solo il report con il valore createTime più recente.

Caratteristiche del report

I report API sono file .csv (valori separati da virgola) con controllo delle versioni e con le seguenti caratteristiche:

• Ogni report contiene dati per un periodo univoco che va dalle ore 00:00 del fuso orario del Pacifico del giorno di inizio del report alle ore 23:59 del fuso orario del Pacifico del giorno di fine del report.

• I dati del report non sono ordinati.