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 參數的值，就必須提供這項參數，且只能與該參數一併使用。此外，要求必須使用 CMS 帳戶授權，該帳戶必須連結至 onBehalfOfContentOwner 參數指定的內容擁有者。最後，onBehalfOfContentOwnerChannel 參數值指定的頻道必須連結至 onBehalfOfContentOwner 參數指定的內容擁有者。

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

要求主體

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

  • 你必須為下列屬性指定值：

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

  • 您可以為下列屬性設定值：

    • snippet.title
    • snippet.description
    • snippet.categoryId
    • snippet.scheduledStartTime
    • snippet.scheduledEndTime
    • status.privacyStatus
    • contentDetails.monitorStream.enableMonitorStream
    • contentDetails.monitorStream.broadcastStreamDelayMs
    • contentDetails.enableAutoStart
    • contentDetails.enableAutoStop
    • contentDetails.enableClosedCaptions
    • contentDetails.enableDvr
    • contentDetails.enableEmbed
    • contentDetails.recordFromStart
    • contentDetails.availabilityConfig
    • monetizationDetails.adsMonetizationStatus
    • monetizationDetails.cuepointSchedule.enabled
    • monetizationDetails.cuepointSchedule.pauseAdsUntil
    • monetizationDetails.cuepointSchedule.ytOptimizedCuepointConfig
    • monetizationDetails.cuepointSchedule.creatorCuepointConfig.scheduleStrategy
    • monetizationDetails.cuepointSchedule.creatorCuepointConfig.repeatIntervalSecs

    提交更新要求時，如果未指定某個屬性的值，但該屬性已有值，系統會刪除該屬性的現有值。

回應

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

錯誤

下表列出 API 在呼叫這個方法時可能傳回的錯誤訊息。詳情請參閱錯誤訊息。

錯誤類型 錯誤詳情 說明
backendError (503) backendError 部分設定目前無法套用。這可能是因為剛建立的廣播。請稍後再試。
forbidden (403) closedCaptionsTypeModificationNotAllowed 只有在直播處於 created 或 ready 狀態時，才能修改 contentDetails.closedCaptionsType 值。
forbidden (403) monetizationDetailsModificationNotAllowed 如果頻道未加入 YouTube 合作夥伴計畫 (YPP)，就無法修改影片的 monetizationDetails。
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 瞭解詳情。
invalidArgument missingAdsMonetizationStatus ads_monetization_status 必須指定為 ON 或 OFF。
invalidValue (400) invalidAutoStart liveBroadcast 資源的 contentDetails.enableAutoStart 屬性包含無效值。 您無法修改永久廣播的 enableAutoStart 設定。
invalidValue (400) invalidAutoStop liveBroadcast 資源的 contentDetails.enableAutoStop 屬性值無效。您無法修改持續性廣播的 enableAutoStop 設定。
invalidValue (400) invalidDescription liveBroadcast 資源未指定有效的 snippet.description 屬性值。snippet.description最多可包含 5,000 個字元。
invalidValue (400) invalidEmbedSetting liveBroadcast 資源的 contentDetails.enable_embed 屬性值無效。無法嵌入這場直播。
invalidValue (400) invalidEnableClosedCaptions 在 liveBroadcast 資源中，contentDetails.enableClosedCaptions 屬性的值與 contentDetails.closedCaptionType 設定的值不相容。請修改資源，只加入其中一個屬性，然後重新提交要求。
invalidValue (400) invalidLatencyPreferenceOptions liveBroadcast 資源的 contentDetails.latencyPreference 屬性值無效。這項延遲時間偏好設定不支援部分設定。
invalidValue (400) invalidEligibleForAdsMonetization eligible_for_ads_monetization 為唯讀，無法在 monetization_details 欄位中指定。
invalidValue (400) invalidCuepointSchedule liveBroadcast 資源的 monetizationDetails.cuepointSchedule 屬性含有無效值。發生這項錯誤的原因如下：
  • 如果 ads_monetization_status 為 OFF，則無法指定 cuepoint_schedule。
  • 如果 ads_monetization_status 為 ON，則必須指定 cuepoint_schedule。
 如果 ads_monetization_status 設為 OFF，則無法指定 cuepoint_schedule。
invalidValue (400) invalidEnabled liveBroadcast 資源的 monetizationDetails.cuepointSchedule.enabled 屬性包含無效或衝突的值。發生這項錯誤的原因如下：
  • 必須在 cuepoint_schedule 欄位中指定 enabled。
  • 如果 enabled 為 false，則無法指定 pause_ads_until、yt_optimized_cuepoint_config 或 creator_cuepoint_config。
  • 如果 enabled 為 true，則只能指定 yt_optimized_cuepoint_config 和 creator_cuepoint_config 其中之一。
invalidValue (400) invalidCreatorCuepointConfig 必須同時指定 schedule_strategy 和 repeat_interval_secs。
invalidValue (400) invalidRepeatIntervalSecs repeat_interval_secs 屬性值必須介於 [360, 3600] 範圍內。
invalidValue (400) invalidPauseAdsUntil liveBroadcast 資源的 monetizationDetails.cuepointSchedule.pauseAdsUntil 屬性包含無效值。發生這項錯誤的原因如下：
  • monetizationDetails.cuepointSchedule.pauseAdsUntil 值並非採用 ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ) 格式。
  • 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 屬性未識別直播。
preconditionFailed (412) videoNotEligibleForAdsMonetization 影片不符合廣告營利資格。如果頻道不符合營利資格，就可能發生這種情況。
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 要求和回應。