L'API ora supporta la possibilità di contrassegnare le tue trasmissioni
dal vivo come "destinate ai bambini" e la risorsa
liveBroadcast
ora contiene una
proprietà che identifica lo stato "destinato ai bambini" di quella trasmissione dal vivo. Il 10 gennaio 2020 sono stati aggiornati anche i Termini di servizio dei servizi API di YouTube e le Norme per gli sviluppatori. Per saperne di più, consulta le cronologie delle revisioni del servizio API YouTube Live Streaming e i Termini di servizio dei servizi API di YouTube.
Una risorsa liveBroadcast
rappresenta un evento che verrà trasmesso in streaming su YouTube tramite video in diretta.
Metodi
L'API supporta i seguenti metodi per le risorse liveBroadcasts
:
- list
- Restituisci un elenco di trasmissioni di YouTube che corrispondono ai parametri della richiesta API. Prova subito.
- inserisci
- Crea una trasmissione. Prova subito.
- aggiornamento
- Aggiorna una trasmissione. Ad esempio, puoi modificare le impostazioni di trasmissione definite nell'oggetto
contentDetails
della risorsaliveBroadcast
. Prova subito. - elimina
- Elimina una trasmissione. Prova subito.
- associazione
- Associa una trasmissione di YouTube a uno stream o rimuove l'associazione esistente tra una trasmissione e uno stream. Una trasmissione può essere associata a un solo stream video, mentre uno stream video può essere associato a più di una trasmissione. Prova subito.
- transizione
- Modifica lo stato di una trasmissione dal vivo su YouTube e avvia le procedure associate al nuovo stato. Ad esempio, quando passi allo stato
testing
di una trasmissione, YouTube inizia a trasmettere il video allo stream monitor della trasmissione. Prima di chiamare questo metodo, devi confermare che il valore della proprietàstatus.streamStatus
per lo stream associato alla tua trasmissione siaactive
. Prova subito. - cuepoint
- Inserisci un cue point in una trasmissione dal vivo. Il cue point potrebbe attivare un'interruzione pubblicitaria.
Rappresentazione delle risorse
La seguente struttura JSON mostra il formato di una risorsa liveBroadcasts
:
{ "kind": "youtube#liveBroadcast", "etag": etag, "id": string, "snippet": { "publishedAt": datetime, "channelId": string, "title": string, "description": string, "thumbnails": { (key): { "url": string, "width": unsigned integer, "height": unsigned integer } }, "scheduledStartTime": datetime, "scheduledEndTime": datetime, "actualStartTime": datetime, "actualEndTime": datetime, "isDefaultBroadcast": boolean, "liveChatId": string }, "status": { "lifeCycleStatus": string, "privacyStatus": string, "recordingStatus": string, "madeForKids": string, "selfDeclaredMadeForKids": string, }, "contentDetails": { "boundStreamId": string, "boundStreamLastUpdateTimeMs": datetime, "monitorStream": { "enableMonitorStream": boolean, "broadcastStreamDelayMs": unsigned integer, "embedHtml": string }, "enableEmbed": boolean, "enableDvr": boolean, "recordFromStart": boolean, "enableClosedCaptions": boolean, "closedCaptionsType": string, "projection": string, "enableLowLatency": boolean, "latencyPreference": boolean, "enableAutoStart": boolean, "enableAutoStop": boolean }, "statistics": { "totalChatCount": unsigned long }, "monetizationDetails": { "cuepointSchedule": { "enabled": boolean, "pauseAdsUntil": datetime, "scheduleStrategy": string, "repeatIntervalSecs": unsigned integer, } } }
Proprietà
La tabella seguente definisce le proprietà visualizzate in questa risorsa:
Proprietà | |
---|---|
kind |
string Identifica il tipo di risorsa API. Il valore sarà youtube#liveBroadcast . |
etag |
etag L'ETag di questa risorsa. |
id |
string L'ID assegnato da YouTube per identificare in modo univoco la trasmissione. |
snippet |
object L'oggetto snippet contiene i dettagli di base dell'evento, tra cui il titolo, la descrizione, l'ora di inizio e l'ora di fine. |
snippet.publishedAt |
datetime La data e l'ora in cui la trasmissione è stata aggiunta alla programmazione delle trasmissioni dal vivo di YouTube. Il valore è specificato nel formato ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ). |
snippet.channelId |
string L'ID utilizzato da YouTube per identificare in modo univoco il canale che pubblica la trasmissione. |
snippet.title |
string Il titolo della trasmissione. Tieni presente che la trasmissione rappresenta esattamente un video di YouTube. Puoi impostare questo campo modificando la risorsa di trasmissione o impostando il campo title della risorsa video corrispondente. |
snippet.description |
string La descrizione della trasmissione. Come per title , puoi impostare questo campo modificando la risorsa di trasmissione o impostando il campo description della risorsa video corrispondente. |
snippet.thumbnails |
object Una mappa di immagini in miniatura associate alla trasmissione. Per ogni oggetto nidificato in questo oggetto, la chiave è il nome dell'immagine in miniatura, mentre il valore è un oggetto che contiene altre informazioni sulla miniatura. |
snippet.thumbnails.(key) |
object Le coppie chiave-valore valide sono:
|
snippet.thumbnails.(key).url |
string L'URL dell'immagine. |
snippet.thumbnails.(key).width |
unsigned integer La larghezza dell'immagine. |
snippet.thumbnails.(key).height |
unsigned integer L'altezza dell'immagine. |
snippet.scheduledStartTime |
datetime La data e l'ora in cui è programmata l'inizio della trasmissione. Il valore è specificato nel formato ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ). Creator Studio supporta la possibilità di creare una trasmissione senza programmare un'ora di inizio. In questo caso, la trasmissione inizia ogni volta che il proprietario del canale avvia lo streaming. Per queste trasmissioni, il valore datetime corrisponde al tempo UNIX pari a zero e non può essere modificato tramite l'API o in Creator Studio. |
snippet.scheduledEndTime |
datetime La data e l'ora in cui è programmata la fine della trasmissione. Il valore è specificato nel formato ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ). Se una risorsa liveBroadcast non specifica un valore per questa proprietà, la trasmissione è programmata per continuare a tempo indeterminato. Allo stesso modo, se non specifichi un valore per questa proprietà, YouTube tratterà la trasmissione come se andrà avanti a tempo indeterminato. |
snippet.actualStartTime |
datetime La data e l'ora in cui è iniziata la trasmissione. Questa informazione è disponibile solo quando lo stato della trasmissione è live . Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ ). |
snippet.actualEndTime |
datetime La data e l'ora in cui la trasmissione è effettivamente terminata. Questa informazione è disponibile solo quando lo stato della trasmissione è complete . Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ ). |
snippet.isDefaultBroadcast |
boolean
Questa proprietà verrà ritirata a partire dal 1° settembre 2020. Da quel momento, YouTube interromperà la creazione di uno stream e di una trasmissione predefiniti quando un canale è abilitato per il live streaming. Per ulteriori dettagli, consulta l'annuncio relativo al ritiro.
Questa proprietà indica se la trasmissione è la trasmissione predefinita.Come funzionano le trasmissioni predefinite Quando un canale YouTube è abilitato per il live streaming, YouTube crea uno stream e una trasmissione predefiniti per quel canale. Lo stream definisce il modo in cui il proprietario del canale invia il video in diretta a YouTube e la trasmissione è il modo in cui gli spettatori possono visualizzare lo stream predefinito. Il proprietario di un canale può utilizzare i metodi liveStreams.list e liveBroadcasts.list per identificare queste risorse.Quando un canale avvia lo streaming del video per impostazione predefinita, il video è visibile sulla trasmissione predefinita del canale. Al termine dello stream, YouTube converte la trasmissione completata in un video di YouTube e assegna al video un ID video di YouTube. Una volta completata la conversione, il video viene incluso nell'elenco dei video caricati del canale. Il video non è disponibile subito dopo la fine della trasmissione e la durata del ritardo è correlata all'effettiva durata della trasmissione. |
snippet.liveChatId |
string L'ID della chat dal vivo di YouTube della trasmissione. Con questo ID, puoi utilizzare i metodi della risorsa liveChatMessage per recuperare, inserire o eliminare i messaggi di chat. Puoi anche aggiungere o rimuovere moderatori della chat, impedire agli utenti di partecipare alle chat dal vivo o rimuovere le esclusioni esistenti. |
status |
object L'oggetto status contiene informazioni sullo stato dell'evento. |
status.lifeCycleStatus |
string Lo stato della trasmissione. Lo stato può essere aggiornato utilizzando il metodo liveBroadcasts.transition dell'API.I valori validi per questa proprietà sono:
|
status.privacyStatus |
string Lo stato della privacy della trasmissione. Tieni presente che la trasmissione rappresenta esattamente un video di YouTube, pertanto le impostazioni della privacy sono identiche a quelle supportate per i video. Inoltre, puoi impostare questo campo modificando la risorsa di trasmissione o impostando il campo privacyStatus della risorsa video corrispondente.I valori validi per questa proprietà sono:
|
status.recordingStatus |
string Lo stato della registrazione della trasmissione. I valori validi per questa proprietà sono:
|
status.madeForKids |
boolean Questo valore indica se la trasmissione è designata come rivolta ai minori. Il valore di questa proprietà è di sola lettura. |
status.selfDeclaredMadeForKids |
boolean In una richiesta liveBroadcasts.insert , questa proprietà consente al proprietario del canale di designare la trasmissione come
rivolta ai minori. In una richiesta liveBroadcasts.list , il valore della proprietà viene restituito solo se il proprietario del canale ha autorizzato la richiesta API. |
contentDetails |
object L'oggetto contentDetails contiene informazioni sui contenuti video dell'evento, ad esempio se i contenuti possono essere mostrati in un video player incorporato o se saranno archiviati e quindi disponibili per la visualizzazione al termine dell'evento. |
contentDetails.boundStreamId |
string Questo valore identifica in modo univoco il live stream associato alla trasmissione. |
contentDetails.boundStreamLastUpdateTimeMs |
datetime La data e l'ora dell'ultimo aggiornamento del live streaming a cui fa riferimento boundStreamId . |
contentDetails.monitorStream |
object L'oggetto monitorStream contiene informazioni sullo stream monitor, che l'emittente può utilizzare per esaminare i contenuti dell'evento prima che lo streaming della trasmissione venga mostrato pubblicamente. |
contentDetails.monitorStream.enableMonitorStream |
boolean Questo valore determina se lo stream monitor è abilitato per la trasmissione. Se lo stream monitor è abilitato, YouTube trasmetterà i contenuti dell'evento su uno stream speciale destinato esclusivamente alla fruizione da parte dell'emittente. L'autore della trasmissione può utilizzare lo stream per esaminare i contenuti dell'evento e anche per identificare il momento ottimale in cui inserire i cue point. Devi impostare questo valore su true se intendi avere uno stage testing per la trasmissione o se vuoi avere un ritardo di trasmissione dell'evento. Inoltre, se il valore di questa proprietà è true , devi eseguire la transizione della trasmissione allo stato testing prima di poterla passare allo stato live . Se il valore della proprietà è false , la trasmissione non può avere uno stage testing , quindi puoi passare direttamente allo stato live .Quando update a broadcast , è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part . Tuttavia, quando esegui insert a broadcast , la proprietà è facoltativa e ha un valore predefinito di true .Importante:questa proprietà non può essere aggiornata una volta che la trasmissione è nello stato testing o live . |
contentDetails.monitorStream.broadcastStreamDelayMs |
unsigned integer Se hai impostato la proprietà enableMonitorStream su true , questa proprietà determina la durata del ritardo della trasmissione dal vivo.Quando update a broadcast , è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part . Tuttavia, quando esegui insert a broadcast , la proprietà è facoltativa e ha un valore predefinito di 0 . Questo valore indica che la trasmissione non ha un ritardo di trasmissione. Nota:questa proprietà non può essere aggiornata una volta che la trasmissione è in stato testing o live . |
contentDetails.monitorStream.embedHtml |
string Codice HTML che incorpora un player che riproduce lo stream monitor. |
contentDetails.enableEmbed |
boolean Questa impostazione indica se la trasmissione video può essere riprodotta in un player incorporato. Se scegli di archiviare il video (utilizzando la proprietà enableArchive ), questa impostazione verrà applicata anche al video archiviato.Quando update a broadcast , è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part . Tuttavia, quando esegui insert a broadcast , la proprietà è facoltativa e ha un valore predefinito di true .Nota: questa proprietà non può essere aggiornata una volta che la trasmissione è in stato testing o live . |
contentDetails.enableDvr |
boolean Questa impostazione determina se gli spettatori possono accedere ai controlli DVR mentre guardano il video. I controlli DVR consentono allo spettatore di controllare l'esperienza di riproduzione del video mettendo in pausa, riavvolgendo o mandando avanti i contenuti. Il valore predefinito di questa proprietà è true . Quando update a broadcast , è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part . Tuttavia, quando esegui insert a broadcast , la proprietà è facoltativa e ha un valore predefinito di true .Importante: devi impostare il valore su true e anche il valore della proprietà enableArchive su true se vuoi rendere disponibile la riproduzione immediatamente dopo la fine della trasmissione. Inoltre, questa proprietà non può essere aggiornata una volta che la trasmissione è nello stato testing o live . |
contentDetails.recordFromStart |
boolean Questa impostazione indica se YouTube inizia automaticamente a registrare la trasmissione dopo che lo stato dell'evento diventa Dal vivo. Il valore predefinito di questa proprietà è true e può essere impostato su false solo se il canale di trasmissione può disattivare le registrazioni per le trasmissioni dal vivo.Se il tuo canale non dispone dell'autorizzazione per disattivare le registrazioni e provi a inserire una trasmissione con la proprietà recordFromStart impostata su false , l'API restituirà un errore Forbidden . Inoltre, se il tuo canale non dispone di questa autorizzazione e tenti di aggiornare una trasmissione per impostare la proprietà recordFromStart su false , l'API restituirà un errore modificationNotAllowed .Quando update a broadcast , è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part . Tuttavia, quando esegui insert a broadcast , la proprietà è facoltativa e ha un valore predefinito di true .Importante:devi anche impostare il valore della proprietà enableDvr su true se vuoi che la riproduzione sia disponibile immediatamente dopo la fine della trasmissione. Se imposti il valore di questa proprietà su true , ma non imposti anche la proprietà enableDvr su true , potrebbe verificarsi un ritardo di circa un giorno prima che il video archiviato sia disponibile per la riproduzione.Nota: questa proprietà non può essere aggiornata una volta che la trasmissione è in stato testing o live . |
contentDetails.enableClosedCaptions |
boolean Questa proprietà è stata ritirata il 17 dicembre 2015. Utilizza la proprietà contentDetails.closedCaptionsType .Questa impostazione indica se i sottotitoli HTTP POST sono attivi per questa trasmissione. Per i client API che utilizzano già questa proprietà:
|
contentDetails.closedCaptionsType |
string Nota: questa proprietà sostituisce la proprietà contentDetails.enableClosedCaptions .Questa proprietà indica se i sottotitoli sono abilitati per la tua trasmissione e, in questo caso, che tipo di sottotitoli stai fornendo:
|
contentDetails.projection |
string Il formato di proiezione della trasmissione. Il valore predefinito della proprietà è rectangular .I valori validi per questa proprietà sono:
|
contentDetails.enableLowLatency |
boolean Indica se la trasmissione deve essere codificata per lo streaming a bassa latenza. Uno stream a bassa latenza può ridurre il tempo necessario affinché il video sia visibile agli utenti che guardano una trasmissione, ma può anche incidere sulla risoluzione degli spettatori dello stream. |
contentDetails.latencyPreference |
string Indica quale impostazione di latenza utilizzare per questa trasmissione. È possibile utilizzare questa proprietà al posto di enableLowLatency , che non supporta ultraLow .Uno stream a bassa latenza può ridurre il tempo necessario per rendere visibile il video agli utenti che guardano una trasmissione, ma può influire anche sulla fluidità della riproduzione. Uno stream a latenza molto bassa riduce ulteriormente il tempo necessario per rendere visibile il video agli spettatori, semplificando l'interazione con gli spettatori, mentre i valori di latenza molto bassa non supportano i sottotitoli codificati superiori a 0: 8
|
contentDetails.enableAutoStart |
boolean Indica se la trasmissione deve iniziare automaticamente quando avvii lo streaming video nell' live stream . |
contentDetails.enableAutoStop |
boolean Indica se la trasmissione deve interrompersi automaticamente circa un minuto dopo che il proprietario del canale ha interrotto lo streaming del video sullo stream video associato. |
statistics |
object L'oggetto statistics contiene statistiche relative a una trasmissione dal vivo. I valori di queste statistiche possono cambiare durante la trasmissione e possono essere recuperati solo mentre la trasmissione è in diretta. |
statistics.totalChatCount |
unsigned long Il numero totale di messaggi della chat dal vivo associati alla trasmissione. La proprietà e il relativo valore sono presenti se la trasmissione è visibile all'utente, ha attivato la funzionalità di chat dal vivo e ha almeno un messaggio. Tieni presente che questa proprietà non specifica un valore al termine della trasmissione. Pertanto, questa proprietà non identificherebbe il numero di messaggi di chat relativi a un video archiviato di una trasmissione dal vivo completata. |
monetizationDetails |
object L'oggetto monetizationDetails contiene informazioni sui dettagli di monetizzazione dello stream, ad esempio se l'automazione degli annunci è attivo o se l'inserimento degli annunci mid-roll è ritardato. |
monetizationDetails.cuepointSchedule |
object L'oggetto cuepointSchedule specifica le impostazioni di automazione degli annunci per la
trasmissione. |
monetizationDetails.cuepointSchedule.enabled |
boolean Questo valore determina se gli annunci vengono inseriti automaticamente nella trasmissione. Se il valore è true , YouTube inserirà automaticamente gli annunci mid-roll nella trasmissione. La pianificazione della pubblicazione degli annunci sarà determinata dal valore degli altri campi nell'oggetto monetizationDetails.cuepointSchedule .
|
monetizationDetails.cuepointSchedule.pauseAdsUntil |
datetime Questo valore specifica che YouTube non deve inserire annunci mid-roll nella trasmissione prima della data e dell'ora specificate. Il valore è specificato nel formato ISO 8601 (AAAA-MM-GGThh:mm:ss.sZ). Per mettere in pausa gli annunci, il valore deve essere impostato su una data/ora futura; il valore del campo può anche essere impostato su una data/ora futura per riattivare gli annunci al passare del tempo. |
monetizationDetails.cuepointSchedule.scheduleStrategy |
string Questo valore specifica la strategia che YouTube deve seguire per pianificare i cue point. I valori validi sono:
|
monetizationDetails.cuepointSchedule.repeatIntervalSecs |
unsigned integer Questo valore specifica l'intervallo, in secondi, tra l'inserimento automatico di annunci durante una trasmissione. Ad esempio, se il valore è 300 , YouTube può inserire i cue point degli annunci mid-roll a intervalli di cinque minuti.Tieni presente che il valore specifica il tempo che intercorre tra l'inizio dei cue point successivi. Ciò significa che l'intervallo non viene misurato dalla fine di un cue point all'inizio di quello successivo. |