LiveBroadcasts: control

注意:liveBroadcasts.control 方法已淘汰,將於 2020 年 10 月 1 日當天或之後停止運作。上述日期過後,對這個方法的所有呼叫都會傳回禁止 (403) 錯誤,系統之後會完全移除該方法。

客戶仍可為自己傳送至 YouTube 擷取伺服器的影片加入重疊元素,藉此導入專屬的剪輯作業。請參閱淘汰公告

控制可在廣播串流中顯示的插入畫面設定。

常見用途

要求

HTTP 要求

POST https://www.googleapis.com/youtube/v3/liveBroadcasts/control

授權

此要求需要至少具備下列其中一個範圍的授權 (進一步瞭解驗證和授權)。

範圍
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl

參數

下表列出這項查詢支援的參數。上方列出的所有參數都是查詢參數。

參數
必要參數
id string
id 參數會指定 YouTube 現場直播 ID,專門用來識別正在更新插入畫面的廣播。
part string
part 參數會指定以逗號分隔的清單,其中包含 API 回應將包含的一或多個 liveBroadcast 資源屬性。您可以在參數值中加入的 part 名稱為 idsnippetcontentDetailsstatus
選用參數
displaySlate boolean
displaySlate 參數可指定要啟用或停用插入畫面。
offsetTimeMs unsigned long
offsetTimeMs 參數會指定指定插入畫面變更發生時的正面時間偏移。這個值會從廣播監控串流開始時算起 (以毫秒為單位),也就是廣播開始的測試階段。雖然這個值是以毫秒為單位,但值實際上僅為約略值,YouTube 會盡可能完成你要求的動作。

如果您沒有指定這個參數的值,YouTube 會盡快執行動作。詳情請參閱入門指南

重要事項:只有在播送串流發生延遲時,才應指定這個參數的值。
onBehalfOfContentOwner string
這個參數只能在妥善的授權要求中使用。注意:這個參數僅適用於 YouTube 內容合作夥伴。

onBehalfOfContentOwner 參數表示請求的授權憑證能代表代替參數值中所指定的內容擁有者所擔任的 YouTube CMS 使用者。這個參數適用於擁有和管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要驗證一次即可,就能存取所有影片和頻道資料,而不需要為每個頻道分別提供驗證憑證。使用者驗證的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。
onBehalfOfContentOwnerChannel string
這個參數只能在妥善的授權要求中使用。這個參數只能在適當的授權要求中使用。注意:這個參數僅適用於 YouTube 內容合作夥伴。

onBehalfOfContentOwnerChannel 參數會指定影片所屬頻道的 YouTube 頻道 ID。如果要求指定了 onBehalfOfContentOwner 參數的值,就必須使用這個參數,而且這個參數只能搭配該參數使用。此外,要求必須使用連結至 onBehalfOfContentOwner 參數指定內容擁有者的 CMS 帳戶。最後,onBehalfOfContentOwnerChannel 參數值指定的管道必須連結至 onBehalfOfContentOwner 參數指定的內容擁有者。

這個參數適用於擁有和管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。這樣內容擁有者就能驗證一次,並且能代表參數值指定的頻道執行動作,而不必分別為每個頻道提供驗證憑證。
walltime datetime
walltime 參數會指定以指定的插入畫面變更的牆壁時鐘時間。這個值以 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定。

要求主體

呼叫此方法時請不要提供要求主體。

回應

如果成功,此方法會在回應主體中傳回 liveBroadcast 資源

錯誤

下表說明 API 在回應此方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息說明文件。

錯誤類型 錯誤詳細資料 說明
backendError errorDisplaySlate 執行要求的動作時發生錯誤。
forbidden (403) liveBroadcastControlNotAllowed 要求的狀態為 live 時,您才能執行要求的動作。
insufficientPermissions insufficientLivePermissions 使用者沒有權限進行要求的操作,原因可能是使用者沒有進行直播的權限。
insufficientPermissions liveStreamingNotEnabled 授權要求的使用者未啟用 YouTube 的即時串流影片。使用者可以前往 https://www.youtube.com/features 瞭解詳情。
invalidValue (400) conflictingTimeFields 您只能指定 offsetTimeMswalltime 其中之一。
invalidValue (400) invalidOffsetTimeMs offsetTimeMs 參數值無效。參數值必須是正數,但只有在廣播的監控串流已啟用時,才能指定這個參數。
invalidValue (400) invalidWalltime walltime 參數值無效。
notFound (404) liveBroadcastNotFound id 參數指定的廣播不存在。
required (400) actionRequired API 要求必須指定至少一個動作。目前只能啟用或停用啟用插入畫面的功能。
required (400) idRequired 必要的 id 參數必須識別正在更新的廣播。

試試看!

使用 APIs Explorer 呼叫這個 API 並查看 API 要求和回應。