這個 API 現在支援將現場直播標示為「兒童專屬」,而且
liveBroadcast
資源現在包含一項屬性,可用來識別直播中的「兒童專屬」狀態。YouTube API 服務的《服務條款》和《開發人員政策》也已於 2020 年 1 月 10 日更新。詳情請參閱 YouTube Live Streaming API 服務的修訂版本記錄和《YouTube API 服務條款》。liveBroadcast
資源代表要在 YouTube 上透過直播影片串流的活動。
方法
這個 API 支援下列 liveBroadcasts
資源方法:
- list
- 傳回符合 API 要求參數的 YouTube 廣播清單。立即試用。
- 插入
- 建立廣播。 立即試用。
- 更新
- 更新廣播。舉例來說,您可以修改
liveBroadcast
資源的contentDetails
物件中定義的廣播設定。 立即試用。 - 刪除
- 刪除廣播。 立即試用。
- 繫結
- 將 YouTube 廣播訊息繫結至串流,或移除廣播與串流之間的現有繫結。每個視訊串流只能繫結至一個視訊串流,但一個視訊串流可繫結至多個廣播。 立即試用。
- transition
- 變更 YouTube 直播的狀態,並啟動與新狀態相關的所有程序。舉例來說,如果您將廣播的狀態轉換為
testing
,YouTube 就會開始將影片傳輸至該廣播的監控串流。呼叫這個方法之前,應在繫結到廣播訊息的串流中,確認status.streamStatus
屬性的值是否為active
。立即試用。 - 提示點
- 在現場直播中插入提示點。提示點可能會觸發廣告插播。
資源表示法
下列 JSON 結構顯示了 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, } } }
屬性
下表列出顯示在這項資源中的屬性:
屬性 | |
---|---|
kind |
string 識別 API 資源的類型。值為 youtube#liveBroadcast 。 |
etag |
etag 這項資源的 Etag。 |
id |
string YouTube 指派給廣播的專屬 ID。 |
snippet |
object snippet 物件包含活動的基本詳細資料,包括活動名稱、說明、開始時間和結束時間。 |
snippet.publishedAt |
datetime YouTube 直播活動中新增的播送日期和時間。這個值以 ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ) 格式指定。 |
snippet.channelId |
string YouTube 會使用這組 ID 識別發布直播的頻道。 |
snippet.title |
string 播送的標題。請注意,播送只代表一部 YouTube 影片,如要設定這個欄位,請修改廣播資源,或是設定對應影片資源的 title 欄位。 |
snippet.description |
string 廣播的說明。和 title 一樣,您可以修改廣播資源或設定對應影片資源的 description 欄位,藉此設定這個欄位。 |
snippet.thumbnails |
object 與廣播相關的縮圖圖片地圖。在這個物件中,每個巢狀物件的索引鍵是縮圖名稱,而值則是包含縮圖其他資訊的物件。 |
snippet.thumbnails.(key) |
object 有效的鍵/值如下:
|
snippet.thumbnails.(key).url |
string 圖片網址。 |
snippet.thumbnails.(key).width |
unsigned integer 圖片的寬度。 |
snippet.thumbnails.(key).height |
unsigned integer 圖片的高度。 |
snippet.scheduledStartTime |
datetime 直播預定開始的日期和時間。這個值以 ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ) 格式指定。創作者工作室功能可讓您在不需排定開始時間的情況下製作直播。在這種情況下,只要頻道擁有者開始串流播放,系統就會開始播送內容。對於這些廣播訊息,datetime 值會對應至 UNIX 時間零,但無法透過 API 或創作者工作室變更這個值。 |
snippet.scheduledEndTime |
datetime 直播預定結束的日期和時間。這個值以 ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ) 格式指定。如果 liveBroadcast 資源未指定這個屬性的值,則播送排程將無限期繼續。同樣地,如果您沒有指定這個屬性的值,YouTube 會將播送內容視為無限期播放。 |
snippet.actualStartTime |
datetime 播送實際開始的日期和時間。只有在廣播處於 live 狀態時,系統才會顯示這項資訊。這個值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ ) 格式指定。 |
snippet.actualEndTime |
datetime 播送實際結束的日期和時間。只有在廣播處於 complete 狀態時,系統才會顯示這項資訊。這個值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ ) 格式指定。 |
snippet.isDefaultBroadcast |
boolean
這項資源將在 2020 年 9 月 1 日當天或之後淘汰。屆時,如果頻道已啟用直播功能,YouTube 就會停止建立預設直播和預設直播活動。詳情請參閱淘汰公告。
這個屬性可指出此廣播是否為預設的廣播訊息。預設廣播功能的運作方式 啟用 YouTube 頻道的直播功能後,YouTube 就會為頻道建立預設直播活動和預設直播節目。直播可定義頻道擁有者傳送直播影片到 YouTube 的方式,直播內容則是觀眾看到預設直播的方式。頻道擁有者可以使用 liveStreams.list 和 liveBroadcasts.list 方法來識別這些資源。頻道開始以預設串流方式串流播放影片時,頻道的預設直播中就會顯示影片。串流結束後,YouTube 會將已結束的播送內容轉換成 YouTube 影片,並為影片指派 YouTube 影片 ID。 轉換作業完成後,影片就會納入頻道的上傳影片清單。播送結束後,影片將無法立即播放,而且延遲的長度與直播的播放長度有關。 |
snippet.liveChatId |
string 直播的 YouTube 聊天室 ID。透過這個 ID,您可以使用 liveChatMessage 資源的方法擷取、插入或刪除即時通訊訊息。你也可以新增或移除聊天室管理員、禁止使用者參與聊天室,或移除現有停權狀態。 |
status |
object status 物件包含事件狀態的相關資訊。 |
status.lifeCycleStatus |
string 廣播的狀態。您可以使用 API 的 liveBroadcasts.transition 方法更新狀態。這個屬性的有效值如下:
|
status.privacyStatus |
string 廣播的隱私權狀態。請注意,播送時只會代表一部 YouTube 影片,因此其隱私權設定與支援的影片相同。此外,你可以修改廣播資源,或是設定對應影片資源的 privacyStatus 欄位,藉此設定這個欄位。這個屬性的有效值如下:
|
status.recordingStatus |
string 廣播的錄製狀態。 這個屬性的有效值如下:
|
status.madeForKids |
boolean 這個值表示廣播是否標示為兒童導向內容。此屬性值為唯讀性質。 |
status.selfDeclaredMadeForKids |
boolean 在 liveBroadcasts.insert 要求中,這個屬性可讓頻道擁有者將直播指定為兒童導向內容。在 liveBroadcasts.list 要求中,只有在頻道擁有者已授權 API 要求時,才會傳回屬性值。 |
contentDetails |
object contentDetails 物件包含事件的影片內容相關資訊,例如內容是否能顯示在內嵌影片播放器中,或是是否封存,以便於活動結束後觀看。 |
contentDetails.boundStreamId |
string 這個值專門用於識別繫結至廣播的 live stream 。 |
contentDetails.boundStreamLastUpdateTimeMs |
datetime 「 boundStreamId 」參照的直播上次更新時間。 |
contentDetails.monitorStream |
object monitorStream 物件包含監控串流的相關資訊,可供播送者在公開顯示播送串流前查看活動內容。 |
contentDetails.monitorStream.enableMonitorStream |
boolean 這個值會決定是否要為直播啟用監控串流功能。如果啟用監控串流功能,YouTube 就會在專為電視台直播的特殊串流中播送活動內容。播送者可以使用串流來檢視活動內容,也可以找出插入提示點的最佳時間。 如果您想為直播活動設定 testing 階段,或想為活動設定播送延遲,請將這個值設為 true 。此外,如果這個屬性的值為 true ,則您必須將廣播轉換為 testing 狀態,才能將其轉換為 live 狀態。(如果屬性值為 false ,則廣播不能有 testing 階段,因此您可以將播送內容直接轉換為 live 狀態)。如果設為 update a broadcast ,如果您的 API 要求包含 part 參數值的 contentDetails 部分,就必須設定這個屬性。不過,當您 insert a broadcast 時,該屬性為選用屬性,且其預設值為 true 。重要事項:廣播處於 testing 或 live 狀態時,無法更新這項屬性。 |
contentDetails.monitorStream.broadcastStreamDelayMs |
unsigned integer 如果將 enableMonitorStream 屬性設為 true ,這個屬性可決定直播延遲時間的長度。如果設為 update a broadcast ,如果您的 API 要求包含 part 參數值的 contentDetails 部分,就必須設定這個屬性。不過,當您 insert a broadcast 時,該屬性為選用屬性,且其預設值為 0 。這個值表示廣播沒有播送延遲。注意:廣播處於 testing 或 live 狀態時,無法更新這項屬性。 |
contentDetails.monitorStream.embedHtml |
string 嵌入可播放監控串流播放器的 HTML 程式碼。 |
contentDetails.enableEmbed |
boolean 這項設定會指定直播影片能否在嵌入式播放器中播放。如果選擇封存影片 (使用 enableArchive 屬性),這項設定也會套用至封存影片。如果設為 update a broadcast ,如果您的 API 要求包含 part 參數值的 contentDetails 部分,就必須設定這個屬性。不過,當您 insert a broadcast 時,該屬性為選用屬性,且其預設值為 true 。注意:廣播處於 testing 或 live 狀態時,無法更新這項屬性。 |
contentDetails.enableDvr |
boolean 這項設定會決定觀眾觀看影片時,是否能使用 DVR 控制項。DVR 控制項可讓觀眾暫停、倒轉或快轉內容,藉此控制影片播放體驗。此屬性的預設值為 true 。如果設為 update a broadcast ,如果您的 API 要求包含 part 參數值的 contentDetails 部分,就必須設定這個屬性。不過,當您 insert a broadcast 時,該屬性為選用屬性,且其預設值為 true 。重要事項:如果您想在廣播結束後立即提供播放功能,請務必將值設為 true ,並將 enableArchive 屬性的值設為 true 。此外,廣播處於 testing 或 live 狀態時,就無法更新這項屬性。 |
contentDetails.recordFromStart |
boolean 這項設定可指定活動狀態變更為直播後,YouTube 是否會自動開始錄製播送內容。 這個屬性的預設值是 true ,只有在廣播頻道可以停用現場直播的錄影功能時,才能設為 false 。如果您的頻道沒有停用錄製功能的權限,而您試圖插入播送內容,並將 recordFromStart 屬性設為 false ,API 就會傳回 Forbidden 錯誤。此外,如果您的頻道沒有該權限,而您嘗試更新廣播將 recordFromStart 屬性設為 false ,API 會傳回 modificationNotAllowed 錯誤。如果設為 update a broadcast ,如果您的 API 要求包含 part 參數值的 contentDetails 部分,就必須設定這個屬性。不過,當您 insert a broadcast 時,該屬性為選用屬性,且其預設值為 true 。重要事項:如果想在廣播結束後立即提供播放功能,您也必須將 enableDvr 屬性的值設為 true 。如果將這個屬性的值設為 true ,但沒有將 enableDvr 屬性設為 true ,則封存影片可能需要大約一天的時間才能播放。注意:廣播處於 testing 或 live 狀態時,無法更新這項屬性。 |
contentDetails.enableClosedCaptions |
boolean 這項屬性已於 2015 年 12 月 17 日淘汰。請改用 contentDetails.closedCaptionsType 屬性。這項設定會指出是否要為這個廣播啟用 HTTP POST 隱藏式輔助字幕。已經使用此屬性的 API 用戶端:
|
contentDetails.closedCaptionsType |
string 注意:這項屬性會取代 contentDetails.enableClosedCaptions 屬性。這個屬性指出您的直播影片是否已啟用隱藏式輔助字幕。如果可以,這項屬性就會顯示您提供的隱藏式輔助字幕類型:
|
contentDetails.projection |
string 此廣播的投影格式。這個屬性的預設值是 rectangular 。這個屬性的有效值如下:
|
contentDetails.enableLowLatency |
boolean 指出這個廣播訊息是否應編碼為低延遲的串流。低延遲串流可以縮短影片在收看直播時向使用者顯示的時間,不過也會影響直播觀眾的解析度。 |
contentDetails.latencyPreference |
string 說明這個廣播訊息要使用的延遲時間設定。這個屬性可能會用在不支援 ultraLow 的 enableLowLatency 上。
|
contentDetails.enableAutoStart |
boolean 指出在繫結的 live stream 上開始播放影片時,是否要自動開始播送。 |
contentDetails.enableAutoStop |
boolean 表示頻道擁有者停止在繫結的影片串流中串流影片後,是否要在一分鐘左右自動停止播送。 |
statistics |
object statistics 物件包含與現場直播相關的統計資料。這些統計資料的值可在直播期間變更,而且只能在直播期間擷取。 |
statistics.totalChatCount |
unsigned long 與直播相關聯的聊天室訊息總數。如果使用者可以看到直播、啟用聊天室功能,而且至少有一則訊息,系統就會顯示這個屬性和屬性值。請注意,這個屬性不會在廣播結束後指定值。因此,針對已結束的現場直播封存影片,這項資源無法辨識聊天室訊息數量。 |
monetizationDetails |
object monetizationDetails 物件包含串流的營利詳細資料,例如廣告自動化器已啟用,或片中廣告是否延遲插入。 |
monetizationDetails.cuepointSchedule |
object cuepointSchedule 物件會指定廣播的廣告自動化設定。 |
monetizationDetails.cuepointSchedule.enabled |
boolean 這個值會決定廣告是否自動插入到直播中。如果值為 true ,YouTube 會自動在播送中插入片中廣告。放送廣告的時段取決於 monetizationDetails.cuepointSchedule 物件中其他欄位的值。 |
monetizationDetails.cuepointSchedule.pauseAdsUntil |
datetime 這個值指定 YouTube 在指定的日期和時間之前,不應在廣播中插入片中廣告。這個值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。這個值必須設為未來的日期時間才能暫停廣告;欄位值也可以設為即將到來的日期,以便在時間過後取消暫停廣告。 |
monetizationDetails.cuepointSchedule.scheduleStrategy |
string 這個值指定 YouTube 安排提示點時應採用的策略。有效值如下:
|
monetizationDetails.cuepointSchedule.repeatIntervalSecs |
unsigned integer 這個值可指定在直播期間自動插入廣告插播的間隔時間 (以秒為單位)。舉例來說,如果值為 300 ,YouTube 就能以五分鐘的間隔插入片中廣告提示點。請注意,這個值可指定連續提示點開始之間的時間。也就是說,間隔時不會從一個提示點的結尾到下一個提示點開始。 |