Questa pagina è stata tradotta dall'API Cloud Translation.

Panoramica dell'API YouTube Live Streaming

L'API YouTube Live Streaming ti consente di creare, aggiornare e gestire gli eventi dal vivo su YouTube. Utilizzando l'API, puoi pianificare eventi (trasmissioni) e associarli agli stream video, che rappresentano i contenuti effettivi delle trasmissioni.

L'API Live Streaming è in realtà composta dai componenti dell'API di dati di YouTube e dell'API Content ID di YouTube. L'API di dati consente agli utenti di YouTube di gestire i propri account YouTube, mentre l'YouTube Content ID API consente le interazioni con il sistema di gestione dei diritti di YouTube. Tuttavia, tutte le risorse che compongono l'API Live Streaming vengono utilizzate solo per creare e gestire eventi dal vivo.

Questo documento è destinato agli sviluppatori che desiderano scrivere applicazioni per facilitare la trasmissione dal vivo su YouTube. Spiega i concetti di base di YouTube e dell'API stessa. Fornisce inoltre una panoramica delle diverse funzioni supportate dall'API.

Concetti principali

annunci: Una trasmissione rappresenta un evento che può essere guardato su YouTube nel momento in cui si verifica. Le trasmissioni possono anche essere registrate e salvate come video di YouTube, in modo che gli utenti possano guardarle quando si verificano.
ruscelli: Uno stream identifica i contenuti audio-video che vengono comunicati a YouTube. Ogni trasmissione è associata a un video stream.
cue point: Un cue point rappresenta un'interruzione pubblicitaria che può essere inserita in una trasmissione dal vivo.

Casi d'uso delle API

L'elenco riportato di seguito suggerisce diversi modi per utilizzare l'API nella tua applicazione:

Pianifica le trasmissioni e definisci le impostazioni di trasmissione. L'applicazione potrebbe consentire agli utenti di predefinire le impostazioni di trasmissione e quindi di selezionare quelle da applicare a una determinata trasmissione.
Associare video stream e trasmissioni.
Consenti alle emittenti di definire contemporaneamente le informazioni su una trasmissione e sul relativo video (utilizzando l'API di dati di YouTube).
Semplifica le transizioni tra gli stati di trasmissione (testing, live e così via) e consenti agli utenti di inserire cue point.

Prima di iniziare

Devi disporre di un Account Google per accedere al Google API Console, richiedere una chiave API e registrare la tua applicazione.
Registra la tua applicazione su Google in modo da poter inviare le richieste di API.
Dopo aver registrato l'applicazione, seleziona YouTube Data API come uno dei servizi utilizzati dall'applicazione:
1. Vai alla API Console e seleziona il progetto che hai appena registrato.
2. Visita la pagina API abilitate. Nell'elenco delle API, verifica che lo stato sia ON per l'API di dati di YouTube v3 e, se sei un partner per i contenuti di YouTube, per l'API YouTube Content ID.
Acquisisci familiarità con i concetti fondamentali del formato dati JSON (JavaScript Object Notation). JSON è un formato dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture di dati arbitrarie. Per ulteriori informazioni, visita il sito json.org.

Autorizzazione delle richieste API

Come indicato in precedenza, l'API Live Streaming utilizza funzionalità che tecnicamente fanno parte dell'API di dati di YouTube o dell'API Content ID di YouTube. Puoi utilizzare l'API Content ID per fornire a YouTube metadati, informazioni sulla proprietà e informazioni sulle norme relativi alle tue risorse. Una trasmissione video in diretta è un esempio di risorsa. L'API ti consente anche di rivendicare i video e impostare le norme relative agli annunci per i tuoi video.

In questa sezione vengono illustrati i requisiti di autorizzazione per le richieste inviate a Content ID API, che sono diversi da quelli per l'autorizzazione di altre richieste Live Streaming API.

Chiamata al Data API: La richiesta API deve essere autorizzata dall'Account Google proprietario del canale YouTube che trasmette.
Chiamata al Content ID API: La richiesta API deve essere autorizzata da un Account Google collegato al proprietario dei contenuti proprietario del canale YouTube che trasmette.

Risorse e tipi di risorse

Una risorsa è una singola entità di dati con un identificatore univoco. La tabella seguente descrive i diversi tipi di risorse con cui interagirai utilizzando Live Streaming API. Tecnicamente, tutte queste risorse sono in realtà definite come parte di YouTube Data API o YouTube Content ID API. Tuttavia, le risorse liveBroadcast, liveStream e cuepoint vengono utilizzate solo per creare e gestire gli eventi dal vivo.

Risorse
`liveBroadcast`	Contiene informazioni su un evento che stai trasmettendo su YouTube. Una risorsa `liveBroadcast` è un'estensione di una risorsa video di YouTube e imposta i metadati video che sarebbero pertinenti a una trasmissione dal vivo, ma non ad altri video di YouTube. Di conseguenza, una risorsa `liveBroadcast` corrisponde esattamente a una risorsa video di YouTube. Infatti, la risorsa `liveBroadcast` e la risorsa `video` condividono lo stesso ID. Inoltre, dopo aver creato la trasmissione utilizzando l'API Live Streaming, puoi utilizzare l'API di dati di YouTube per fornire metadati aggiuntivi sul video.
`liveStream`	Contiene informazioni sul video stream che stai trasmettendo a YouTube. Lo stream fornisce i contenuti che verranno trasmessi agli utenti di YouTube. Una volta creata, una risorsa `liveStream` può essere associata esattamente a una risorsa `liveBroadcast`. Allo stesso modo, la risorsa `liveBroadcast` può essere associata a una sola risorsa `liveStream`.
`cuepoint`	Inserisce un cue point nello stream video trasmesso in trasmissione, che potrebbe attivare un'interruzione pubblicitaria. Utilizza il metodo `liveBroadcasts.cuepoint` per inserire un cue point durante una trasmissione.
`video`	Rappresenta un singolo video di YouTube. Come indicato sopra, una risorsa `liveBroadcast` è un'estensione di una risorsa `video`. Puoi utilizzare l'API di dati di YouTube per aggiornare i metadati sul video, ad esempio il luogo della registrazione o le regioni in cui la trasmissione sarà visibile.
`videoAdvertisingOptions`	Definisce le impostazioni pubblicitarie per un video (o una trasmissione). Puoi utilizzare l'YouTube Content ID API per impostare le opzioni pubblicitarie.
`asset`	Rappresenta una proprietà intellettuale, come un film o la puntata di un programma. In questo caso, la risorsa è il video trasmesso. Utilizzerai l'YouTube Content ID API per creare e gestire le risorse `asset`.
`claim`	Collega un video a una risorsa corrispondente. Puoi creare una rivendicazione utilizzando YouTube Content ID API per identificarti come proprietario del video trasmesso.
`policy`	Definisce regole che specificano le circostanze in cui vuoi che i tuoi contenuti siano visibili su YouTube o che non vengano mostrati su YouTube. Devi applicare una norma al video trasmesso e puoi anche specificare una norma che YouTube applicherà ai video caricati da utenti che corrispondono al video trasmesso.

Operazioni supportate

La tabella seguente mostra i diversi metodi supportati dall'API:

Suite operativa
`list`	Recupera (`GET`) un elenco di zero o più risorse.
`insert`	Crea una nuova risorsa (`POST`).
`update`	Modifica (`PUT`) una risorsa esistente per riflettere i dati nella richiesta.
`bind`	Collega una risorsa `liveBroadcast` a una risorsa `liveStream` oppure rimuove questo link.
`transition`	Modifica lo stato di una risorsa `liveBroadcast` e avvia tutti i processi associati al nuovo stato. Ad esempio, quando passi allo stato `testing` di una trasmissione, YouTube inizia a trasmettere il video allo stream di monitoraggio di quella trasmissione.
`delete`	Rimuove (`DELETE`) una risorsa specifica.

La tabella seguente identifica le operazioni supportate per i diversi tipi di risorse. Le operazioni che inseriscono, aggiornano o eliminano risorse richiedono sempre l'autorizzazione dell'utente. In alcuni casi, i metodi list supportano sia le richieste autorizzate sia quelle non autorizzate, dove le richieste non autorizzate recuperano solo dati pubblici, mentre le richieste autorizzate possono anche recuperare informazioni limitate all'utente attualmente autenticato.

Operazioni supportate
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Risorse parziali

L'API consente, e richiede di fatto, il recupero di risorse parziali in modo che le applicazioni evitino di trasferire, analizzare e archiviare i dati non necessari. Questo approccio garantisce inoltre che l'API utilizzi risorse di rete, CPU e memoria in modo più efficiente.

Il parametro part è obbligatorio per qualsiasi richiesta API che recupera o restituisce una risorsa YouTube Data API. Il parametro identifica una o più proprietà delle risorse di primo livello (non nidificate) che devono essere incluse in una risposta dell'API. Ad esempio, una risorsa liveStream ha le seguenti parti:

snippet
cdn
status

Tutte queste parti sono oggetti che contengono proprietà nidificate e puoi considerarli come gruppi di campi di metadati che il server API potrebbe (o meno) recuperare. Di conseguenza, il parametro part richiede di selezionare i componenti delle risorse effettivamente utilizzati dall'applicazione. Questo requisito serve a due scopi importanti:

Riduce la latenza impedendo al server API di dedicare tempo al recupero dei campi di metadati che l'applicazione non utilizza.
Riduce l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che l'applicazione potrebbe recuperare.

Nel tempo, man mano che le risorse aggiungono altre parti, questi vantaggi aumenteranno solo perché la tua applicazione non richiederà proprietà introdotte di recente che non supporta.

Suggerimenti e best practice

Rivendicare i tuoi contenuti

Se vuoi mostrare annunci durante la trasmissione, devi rivendicare il video prima dell'inizio dell'evento. Per rivendicare i contenuti, devi essere un partner per i contenuti di YouTube che partecipa al programma Content ID.

La procedura per rivendicare un video trasmesso dal vivo è diversa da quella per la rivendicazione di un video. Quando rivendichi un video pubblicato, devi creare la rivendicazione prima che il video esista effettivamente. L'API supporta questa operazione e il documento sulla durata di una trasmissione spiega le chiamate YouTube Content ID API che ti consentono di creare la richiesta.

Visualizzare in anteprima e testare i contenuti

Una volta ricevuto il video stream in entrata, YouTube può trasmetterlo su due diversi stream in uscita:

Lo stream di monitoraggio ti consente di visualizzare in anteprima (e testare) la trasmissione video. Si tratta di uno stream privato a cui solo tu puoi accedere. Puoi passare alla fase testing di una trasmissione solo se lo stream di monitoraggio della trasmissione è attivo. Lo stream di monitoraggio non mostra le interruzioni pubblicitarie.
Lo stream di trasmissione è lo stream visibile al tuo pubblico. Puoi impostare lo stato della privacy della trasmissione su public, private o unlisted. Una trasmissione privata è visibile soltanto agli utenti che sono stati esplicitamente invitati a guardarla, mentre una trasmissione non in elenco è visibile a chiunque disponga di un link per visualizzarla.

Puoi scegliere di ritardare lo stream della trasmissione in modo che non venga eseguito in contemporanea con lo stream di monitoraggio. Il ritardo dello streaming della trasmissione ti consente di avere un controllo più granulare sul momento in cui inserisci i cue point nella trasmissione.

Tuttavia, se ritardare lo streaming della trasmissione, i presentatori dal vivo hanno difficoltà a interagire con il pubblico che li guarda. Inoltre, ritardare la trasmissione aumenta la probabilità che gli spettatori trovino dettagli chiave sull'evento da fonti diverse dalla tua trasmissione. Ad esempio, se trasmetti un evento sportivo con un ritardo di 60 secondi, gli spettatori potrebbero venire a conoscenza dei momenti critici dell'evento da altre fonti di notizie in tempo reale prima di vederli effettivamente nella trasmissione.

YouTube consiglia di attivare lo stream di monitoraggio per la trasmissione in modo da poter testare i contenuti. Dovresti scegliere se ritardare la trasmissione anche in base al tuo desiderio di controllare la tempistica dei cue point anziché al tuo desiderio di interagire con il pubblico o di fornire la copertura in tempo reale di un evento.

Pubblicare annunci mid-roll durante una trasmissione in streaming

Durante una trasmissione, puoi inserire un cue point per indicare che un'interruzione pubblicitaria deve iniziare nella trasmissione il prima possibile o in un orario specifico. L'interruzione pubblicitaria consente a YouTube di pubblicare annunci mid-roll durante la trasmissione.

Le interruzioni pubblicitarie hanno le seguenti caratteristiche:

Ha un periodo di tempo predefinito, che puoi impostare utilizzando la proprietà durationSecs della risorsa cuepoint. Al termine dell'interruzione pubblicitaria, gli spettatori tornano alla trasmissione in diretta.
Quando si verifica un'interruzione pubblicitaria, l'annuncio viene riprodotto nel video player solo per gli spettatori che guardano la trasmissione quando viene inserito il cue point. Un annuncio non viene pubblicato quando i visitatori aggiornano la pagina in cui è in riproduzione o quando i visitatori iniziano a guardare la trasmissione dopo l'inserimento del cue point.

La sequenza di passaggi riportata di seguito riflette la best practice per l'inserimento di un'interruzione pubblicitaria durante la trasmissione:

Imposta offset temporali

Quando inserisci un cue point, puoi specificare se deve essere inserito subito o in un punto specifico della trasmissione. Le opzioni disponibili dipendono dall'eventuale ritardo nello streaming della trasmissione del video.

Se lo streaming della trasmissione non viene ritardato, puoi inserire immediatamente il cue point o utilizzare la proprietà walltimeMs per avviare l'interruzione pubblicitaria in un momento specifico.
- Per avviare immediatamente l'interruzione pubblicitaria, chiama il metodo liveBroadcasts.cuepoint. Nella risorsa del corpo della richiesta, imposta il valore della proprietà insertionOffsetTimeMs su 0 oppure non specificare un valore per quella proprietà e non specificare un valore per la proprietà walltimeMs.
  
  Importante:tieni presente che gli spettatori non vedono immediatamente i contenuti degli annunci risultanti. Potrebbe verificarsi un ritardo di circa 30 secondi prima che il contenuto dell'annuncio sia visibile agli utenti. Durante questo periodo, lo stream della trasmissione sarà ancora visibile agli spettatori e dovrai guardare lo stream della trasmissione per determinare quando viene effettivamente mostrato il contenuto dell'annuncio anziché lo stream di monitoraggio.
- Per avviare l'interruzione pubblicitaria in un momento specifico, chiama il metodo liveBroadcasts.cuepoint e utilizza la proprietà walltimeMs per specificare il momento desiderato. Il valore della proprietà è un numero intero che rappresenta un timestamp dell'epoca.
Se lo streaming della trasmissione è in ritardo, puoi inserire immediatamente il cue point come descritto in precedenza, specificare l'ora dell'orologio come descritto in precedenza oppure specificare un offset temporale per determinare il momento in cui inizierà l'interruzione pubblicitaria. La differenza temporale specifica il punto della trasmissione in cui gli spettatori dovrebbero vedere un annuncio.

Il valore di offset viene misurato in millisecondi dall'inizio dello stream di monitoraggio della trasmissione. Tieni presente che, se la trasmissione è in fase di test, lo streaming di monitoraggio inizia quando la trasmissione passa allo stato testing. In caso contrario, lo stream di monitoraggio inizia quando la trasmissione passa allo stato live.

Quando inserisci un cue point, imposta la proprietà insertionOffsetTimeMs della risorsa cuepoint sull'offset desiderato.

Calcolare il valore di offset temporale

Per recuperare il valore di offset, chiama la funzione getCurrentTime della YouTube Player API per il player che sta riproducendo lo stream di monitoraggio. Utilizza il valore recuperato per inserire il cue point nello stream della trasmissione in quel momento.

I possibili valori per il tempo di offset possono essere calcolati nel seguente intervallo:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ è un buffer di cinque secondi all'inizio e alla fine dei possibili offset temporali quando YouTube non è in grado di inserire con precisione un cue point. Ad esempio:

Una trasmissione ha una fase di test di cinque minuti.
Lo stream trasmesso viene ritardato di 60 secondi dopo lo streaming in modalità di monitoraggio.
L'autore della trasmissione sta inserendo il cue point quattro minuti dopo che la trasmissione è passata allo stato live. (Questo avviene tre minuti dopo che lo stream della trasmissione diventa visibile).

In questo caso, l'intervallo possibile di tempi di offset è [(485,000), (535,000)].

Questi tempi sono specificati in millisecondi e calcolati utilizzando i seguenti valori:

elapsed_time=540000: il flusso di monitoraggio è stato eseguito per nove minuti (540 secondi, 540.000 millisecondi) quando viene chiamato il metodo liveBroadcasts.cuepoint.
broadcast_delay=60000 - Lo streaming della trasmissione ha un ritardo di 60 secondi, o 60.000 millisecondi.
Δ=5000: il buffer di cinque secondi in cui il cue point non può essere inserito in modo affidabile.

Risoluzione dei problemi e gestione degli errori

Le seguenti linee guida spiegano come risolvere problemi specifici che potrebbero sorgere. Consulta anche la documentazione relativa agli errori per gli elenchi di errori che ogni metodo API potrebbe restituire.

Quando una trasmissione passa da uno stato a un altro, può riceverne temporaneamente un altro mentre YouTube completa le azioni associate alla transizione. Ad esempio, se invii una richiesta liveBroadcasts.transition per modificare lo stato di una trasmissione da ready a testing, YouTube imposterà lo stato della trasmissione su testStarting e completerà le azioni associate alla modifica dello stato. Quando tutte queste azioni sono state completate, YouTube aggiornerà lo stato della trasmissione a testing, per indicare che la transizione è stata completata.

Se una trasmissione si blocca con lo stato testStarting o liveStarting, devi chiamare il metodo liveBroadcasts.delete ed eliminare la trasmissione. Quindi crea una nuova trasmissione, associala al live streaming e continua con la procedura di test.

Come indicato nella documentazione del metodo liveBroadcasts.transition, prima di chiamare questo metodo devi confermare che il valore della proprietà status.streamStatus per lo streaming associato alla tua trasmissione sia active.