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，這個 ID 是用來識別插入畫面要更新的廣播節目。
part string
part 參數會指定一份以逗號分隔的清單，其中包含一或多個 API 回應會包含的 liveBroadcast 資源屬性。您可以在參數值中加入的 part 名稱包括 id、snippet、contentDetails 和 status。
選用參數
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 只能指定為 offsetTimeMs 和 walltime 其中之一。
invalidValue (400) invalidOffsetTimeMs offsetTimeMs 參數的值無效。參數值必須是正數，但只有在廣播的監控串流已啟用時，才能指定這個參數。
invalidValue (400) invalidWalltime walltime 參數的值無效。
notFound (404) liveBroadcastNotFound id 參數指定的廣播訊息不存在。
required (400) actionRequired API 要求需要指定至少一個動作。目前唯一支援的動作是啟用或停用插入畫面。
required (400) idRequired 必要的 id 參數必須識別正在更新的廣播訊息。

試試看！

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