YouTube Reporting API - System-Managed Reports

YouTube genera automaticamente una serie di report sulle entrate pubblicitarie gestite 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, che sono disponibili anche nei report scaricabili manualmente accessibili dal menu Report di YouTube Creator Studio.

Nota:l'API consente di accedere a un insieme di report diverso rispetto a Creator Studio, sebbene i report contengano dati simili. I report API potrebbero avere campi diversi e utilizzare nomi di campo diversi rispetto ai report di Creator Studio.

Dal momento che YouTube genera automaticamente report gestiti dal sistema, la procedura per il recupero di questi report è diversa da quella per i report 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 di reporting di YouTube 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 di reporting di YouTube utilizzano i seguenti ambiti di autorizzazione:

Ambiti
https://www.googleapis.com/auth/yt-analytics.readonly Visualizzare i report Analytics su YouTube per i tuoi contenuti di YouTube. Questo ambito consente di accedere alle metriche relative all'attività utente, come il numero di visualizzazioni e di valutazioni.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Visualizzare i report di YouTube Analytics relativi al valore monetario per i tuoi contenuti di YouTube. Questo ambito consente di accedere alle metriche relative all'attività utente e alle metriche sul rendimento degli annunci e sulle entrate stimate.

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 al job. La tua applicazione richiede il valore della proprietà id della stessa risorsa nel passaggio successivo.

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 periodo di tempo. Questo parametro può essere utilizzato per garantire che l'API restituisca solo i report che non hai già elaborato.

  • Utilizza il parametro startTimeBefore per indicare che la risposta API deve contenere report solo se i primi dati del report sono precedenti alla data specificata. Il parametro createdAfter riguarda il momento in cui è stato creato il report, mentre questa data si riferisce ai dati del report.

  • Utilizza il parametro startTimeAtOrAfter per indicare che la risposta dell'API deve contenere report solo se i primi dati del report sono corrispondenti o successivi alla data specificata. Come il parametro startTimeBefore, questo valore corrisponde ai dati del report e non all'ora di creazione del report.

La risposta API contiene un elenco di risorse Report per quel job. Ogni risorsa fa riferimento a un report contenente dati relativi a un periodo unico.

  • Le proprietà startTime e endTime della risorsa identificano il periodo di tempo relativo ai 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. L'applicazione deve archiviare questo valore e utilizzarlo per determinare se i report scaricati in precedenza sono cambiati.

Passaggio 4: scarica il report

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

Elaborazione dei report

best practice

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

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

  • Tieni traccia dei report scaricati 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 i report, archivia il timestamp corrispondente alla data e all'ora di creazione del report più recente. Successivamente, aggiorna il valore del parametro createdAfter su ogni chiamata successiva al metodo reports.list per assicurarti di recuperare solo i nuovi report, inclusi quelli con dati di backfill, ogni volta che chiami l'API.

      A titolo di salvaguardia, prima di recuperare un report, verifica anche che l'ID del report non sia già presente nel database.

    • Memorizza l'ID per ogni report che hai scaricato ed elaborato. Puoi anche memorizzare informazioni aggiuntive come data e ora di generazione di ciascun report o startTime e endTime del report, che insieme identificano il periodo per il quale il report contiene dati. Per i report che recuperano i dati collettivi per YouTube Analytics, ogni lavoro avrà probabilmente molti report poiché ogni report contiene dati relativi a 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 il controllo delle versioni che hanno le seguenti caratteristiche:

  • Ogni report contiene dati relativi a un unico periodo che dura dalle 00:00 (fuso orario del Pacifico - della data di inizio del rapporto alle 23:59 (fuso orario del Pacifico) della data di fine del rapporto).

  • I dati del report non sono ordinati.