LiveBroadcasts: update

更新廣播。舉例來說，您可以修改 liveBroadcast 資源 contentDetails 物件中定義的廣播設定。

常見用途

要求

HTTP 要求

PUT https://www.googleapis.com/youtube/v3/liveBroadcasts

授權

這項要求需要至少具備下列其中一個範圍的授權。如要進一步瞭解驗證和授權，請參閱「實作 OAuth 2.0 授權」。

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

參數

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

參數
必要參數
part string
在本作業中，part 參數有以下兩種用途。這個方法會指出寫入作業會設定的屬性，以及 API 回應會納入的屬性。

您可以在參數值中納入的 part 屬性包括 id、snippet、contentDetails、monetizationDetails 和 status。

請注意，這個方法會覆寫參數值所指定的任何部分中包含的所有可變更屬性現有值。舉例來說，廣播的隱私權狀態是在 status 部分定義。因此，如果您的要求更新私人或不公開廣播，且要求的 part 參數值包含 status 部分，則廣播的隱私權設定會更新為要求主體指定的任何值。如果要求主體未指定值，系統會移除現有的隱私權設定，並將廣播訊息還原為預設的隱私權設定。
選用參數
onBehalfOfContentOwner string
這個參數只能用於適當的授權要求。
注意：這個參數僅供 YouTube 內容合作夥伴使用。

onBehalfOfContentOwner 參數表示要求的授權憑證可識別 YouTube 內容管理系統 (CMS) 使用者，該使用者會代表參數值中指定的內容擁有者行事。這個參數適用於擁有及管理多個 YouTube 頻道的 YouTube 內容合作夥伴。這項功能可讓內容擁有者驗證一次，即可存取所有影片和頻道資料，不必為每個頻道提供驗證憑證。使用者驗證的 CMS 帳戶必須連結至指定的 YouTube 內容擁有者。
onBehalfOfContentOwnerChannel string
這個參數僅能用於適當的授權要求。
注意：這個參數僅供 YouTube 內容合作夥伴使用。

onBehalfOfContentOwnerChannel 參數會指定要新增影片的 YouTube 頻道 ID。當要求指定 onBehalfOfContentOwner 參數的值時，就必須使用這個參數，且只能與該參數搭配使用。此外，請求必須使用與 onBehalfOfContentOwner 參數指定的內容擁有者相連結的 CMS 帳戶進行授權。最後，onBehalfOfContentOwnerChannel 參數值指定的頻道必須連結至 onBehalfOfContentOwner 參數指定的內容擁有者。

這個參數適用於擁有及管理多個 YouTube 頻道的 YouTube 內容合作夥伴。這項功能可讓內容擁有者驗證一次，並代表參數值中指定的管道執行動作，而不必為每個管道分別提供驗證憑證。

要求主體

請在要求主體中提供 liveBroadcast 資源。針對該資源：

  • 您必須指定這些屬性的值：

    • id
    • snippet.scheduledStartTime
    • contentDetails.monitorStream.enableMonitorStream
    • contentDetails.monitorStream.broadcastStreamDelayMs

  • 您可以為這些屬性設定值：

    • snippet.title
    • snippet.description
    • snippet.scheduledStartTime
    • snippet.scheduledEndTime
    • status.privacyStatus
    • contentDetails.monitorStream.enableMonitorStream
    • contentDetails.monitorStream.broadcastStreamDelayMs
    • contentDetails.enableAutoStart
    • contentDetails.enableAutoStop
    • contentDetails.enableClosedCaptions
    • contentDetails.enableDvr
    • contentDetails.enableEmbed
    • contentDetails.recordFromStart
    • monetizationDetails.cuepointSchedule.pauseAdsUntil

    如果您提交更新要求，但未為已設有值的屬性指定值，則系統會刪除該屬性現有的值。

回應

如果成功，這個方法會在回應內文中傳回 liveBroadcast 資源。

錯誤

下表列出 API 在回應對此方法的呼叫時可能傳回的錯誤訊息。詳情請參閱「錯誤訊息」。

錯誤類型 錯誤詳細資料 說明
forbidden (403) closedCaptionsTypeModificationNotAllowed 只有在廣播處於 created 或 ready 狀態時，才能修改 contentDetails.closedCaptionsType 值。
forbidden (403) enabledModificationNotAllowed enabled 欄位為唯讀欄位。
forbidden (403) scheduleStrategyModificationNotAllowed scheduleStrategy 欄位為唯讀欄位。
forbidden (403) repeatIntervalSecsModificationNotAllowed repeatIntervalSecs 欄位為唯讀欄位。
forbidden (403) pauseAdsUntilModificationNotAllowed pauseAdsUntil 欄位無法修改。 導致這項錯誤的原因可能如下：
  • monetizationDetails.cuepointSchedule.enabled 欄位未設為 true。這個欄位只能透過 YouTube 工作室設定。
  • 直播尚未開始。
forbidden (403) enableAutoStartModificationNotAllowed 只有在串流處於無效狀態，且廣播處於 created 或 ready 狀態時，才能修改 contentDetails.enableAutoStart 值。
forbidden (403) enableClosedCaptionsModificationNotAllowed 只有在廣播狀態為 created 或 ready 時，才能修改 contentDetails.enableClosedCaptions 值。
forbidden (403) enableDvrModificationNotAllowed 只有在廣播狀態為 created 或 ready 時，才能修改 contentDetails.enableDvr 值。
forbidden (403) enableMonitorStreamModificationNotAllowed 只有在廣播狀態為 created 或 ready 時，才能修改 contentDetails.monitorStream.enableMonitorStream 值。
forbidden (403) recordFromStartModificationNotAllowed 只有在廣播狀態為 created 或 ready 時，才能修改 contentDetails.recordFromStart 值。
insufficientPermissions insufficientLivePermissions 要求者沒有更新指定直播的權限。詳情請參閱「實作 OAuth2 驗證」。
insufficientPermissions liveStreamingNotEnabled 授權要求的使用者無法在 YouTube 上進行直播。你可以前往 https://www.youtube.com/features 查看更多資訊。
invalidValue (400) invalidAutoStart liveBroadcast 資源中的 contentDetails.enableAutoStart 屬性含有無效值。您無法修改持續廣播的 enableAutoStart 設定。
invalidValue (400) invalidAutoStop liveBroadcast 資源包含 contentDetails.enableAutoStop 屬性的無效值。您無法修改永久廣播的 enableAutoStop 設定。
invalidValue (400) invalidDescription liveBroadcast 資源未為 snippet.description 屬性指定有效值。snippet.description 最多可包含 5000 個字元。
invalidValue (400) invalidEmbedSetting liveBroadcast 資源的 contentDetails.enable_embed 屬性含有無效值。你無法嵌入這項直播。
invalidValue (400) invalidEnableClosedCaptions 在 liveBroadcast 資源中，contentDetails.enableClosedCaptions 屬性的值與 contentDetails.closedCaptionType 設定的值不相容。修改資源，只包含這兩個屬性中的其中一個，然後重新提交要求。
invalidValue (400) invalidLatencyPreferenceOptions liveBroadcast 資源包含 contentDetails.latencyPreference 屬性的無效值。這項延遲偏好設定不支援所有設定。
invalidValue (400) invalidPauseAdsUntil liveBroadcast 資源包含 monetizationDetails.cuepointSchedule.pauseAdsUntil 屬性的無效值。導致這項錯誤的原因可能如下：
  • 並未使用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式指定 monetizationDetails.cuepointSchedule.pauseAdsUntil 值。
  • monetizationDetails.cuepointSchedule.pauseAdsUntil 值並非未來日期。
  • monetizationDetails.cuepointSchedule.pauseAdsUntil 值比目前時間高出 10 分鐘。
invalidValue (400) invalidPrivacyStatus liveBroadcast 資源未指定有效的隱私權狀態。請參閱有效的 privacyStatus 值。
invalidValue (400) invalidProjection liveBroadcast 資源含有 contentDetails.projection 屬性的無效值。無法將永久廣播的透視圖設為 360。
invalidValue (400) invalidScheduledEndTime liveBroadcast 資源含有 snippet.scheduledEndTime 屬性的無效值。排定的結束時間必須晚於排定的開始時間。
invalidValue (400) invalidScheduledStartTime liveBroadcast 資源的 snippet.scheduledStartTime 屬性含有無效值。排定的開始時間必須在未來。
invalidValue (400) invalidTitle liveBroadcast 資源未為 snippet.title 屬性指定有效值。snippet.title的長度必須介於 1 到 100 個字元之間。
notFound (404) liveBroadcastNotFound liveBroadcast 資源中指定的 id 屬性未識別廣播內容。
required (400) broadcastStreamDelayMsRequired liveBroadcast 資源未指定 contentDetails.monitorStream.broadcastStreamDelayMs 屬性。
required (400) enableMonitorStreamRequired liveBroadcast 資源未指定 contentDetails.monitorStream.enableMonitorStream 屬性。
required (400) idRequired liveBroadcast 資源必須包含並指定 id 屬性的值。
required (400) scheduledEndTimeRequired liveBroadcast 資源並未指定 snippet.scheduledEndTime 屬性。
required (400) scheduledStartTimeRequired liveBroadcast 資源未指定 snippet.scheduledStartTime 屬性。

試試看！

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