Channels: update

API 現在支援將頻道或影片標示為「兒童專屬」的功能。此外，channel 和 video 資源現在也包含可識別頻道或影片「兒童專屬」狀態的屬性。《YouTube API 服務條款》和《開發人員政策》也已於 2020 年 1 月 10 日更新。詳情請參閱 YouTube Data API 服務和《YouTube API 服務條款》的修訂版本記錄。

更新頻道的中繼資料。請注意，這個方法僅支援更新 channel 資源的 brandingSettings、invideoPromotion 和 localizations 物件及其子項屬性。

配額影響：呼叫這個方法會產生 50 個單位的配額費用。

常見用途

要求

HTTP 要求

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

授權

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

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

參數

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

參數
必要參數
part string
part 參數在這項作業中有兩個用途。這個參數會識別寫入作業將設定的屬性，以及 API 回應將包含的屬性。

API 只允許將參數值設為 brandingSettings、invideoPromotion 或 localizations。(您只能透過單一要求更新其中一個部分)。

請注意，這個方法會覆寫參數值指定部分中所有可變動屬性的現有值。
選用參數
onBehalfOfContentOwner string
這個參數只能用於授權要求。

onBehalfOfContentOwner 參數表示已驗證的使用者代表參數值中指定的內容擁有者。這項參數適用於擁有及管理多個不同 YouTube 頻道的 YouTube 內容合作夥伴。內容擁有者只要驗證一次，就能存取所有影片和頻道資料，不必為每個頻道提供驗證憑證。使用者用來驗證的實際 CMS 帳戶，必須連結至指定的 YouTube 內容擁有者。

如果要求是透過 CMS 內容擁有者使用受管理頻道時的憑證進行驗證，就必須提供這個參數。如果省略，要求會在已驗證使用者的直接環境下執行，並傳回 HTTP 403 Forbidden 錯誤。

要求主體

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

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

    • id

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

    • brandingSettings.channel.country
    • brandingSettings.channel.description
    • brandingSettings.channel.defaultLanguage
    • brandingSettings.channel.keywords
    • brandingSettings.channel.trackingAnalyticsAccountId
    • brandingSettings.channel.unsubscribedTrailer
    • localizations.(key)
    • localizations.(key).title
    • localizations.(key).description
    • status.selfDeclaredMadeForKids

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

回應

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

錯誤

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

錯誤類型 錯誤詳情 說明
badRequest (400) brandingValidationError brandingSettings 物件中的其中一個值未通過驗證。使用 channels.list 方法擷取頻道的現有設定，然後按照 channels 資源說明文件中的指南更新屬性值。
badRequest (400) channelTitleUpdateForbidden 更新頻道的 brandingSettings part 時，必須將 brandingSettings.channel.title 屬性的值設為頻道的目前名稱，或省略該屬性。如果變更屬性值，API 會傳回錯誤。
badRequest (400) defaultLanguageNotSetError defaultLanguage 必須設為更新 localizations。
badRequest (400) invalidBrandingOption 您指定的其中一項品牌設定不存在。請使用 channels.list 方法擷取有效值，並務必按照 channels 資源說明文件中的規範更新。
badRequest (400) invalidCustomMessage 要求中繼資料指定了無效的自訂訊息。請檢查要求傳送的資源中 invideoPromotion.items[].customMessage 屬性的值。
badRequest (400) invalidDuration 要求中繼資料在 invideoPromotion 部分指定了無效的時間長度。
badRequest (400) invalidDuration 要求中繼資料指定的位置類型無效，無法判斷宣傳項目在影片播放器中的位置。請檢查要求傳送的資源中 invideoPromotion.position.type 屬性的值。
badRequest (400) invalidRecentlyUploadedBy 要求中繼資料指定的頻道 ID 無效。請檢查要求傳送的資源中 invideoPromotion.items[].id.recentlyUploadedBy 屬性的值。
badRequest (400) invalidTimingOffset 要求中繼資料在 invideoPromotion 部分指定了無效的時間偏移。
badRequest (400) invalidTimingOffset 請求中繼資料指定了無效的時間偏移，無法判斷宣傳項目應在影片播放器中顯示的時間。請檢查要求傳送的資源中 invideoPromotion.timing.offsetMs 屬性的值。
badRequest (400) invalidTimingType 要求中繼資料指定了無效的時間方法，用於判斷何時在影片播放器中顯示宣傳項目。請檢查要求傳送的資源中 invideoPromotion.timing.type 屬性的值。
badRequest (400) localizationValidationError localizations 物件中的某個值未通過驗證。請使用 channels.list 方法擷取有效值，並務必按照管道資源說明文件中的規範更新。
badRequest (400) tooManyPromotedItems invideoPromotion 部分中的宣傳項目數量超過上限。
forbidden (403) channelForbidden id 參數中指定的管道不支援要求，或要求未正確授權。
forbidden (403) promotedVideoNotAllowed 找不到 API 要求嘗試更新的頻道。檢查要求傳送至 channel 資源中的 id 屬性值，確保頻道 ID 正確無誤。
forbidden (403) websiteLinkNotAllowed 不允許使用指定的網站網址。
notFound (404) channelNotFound 找不到 id 參數中指定的管道。
notFound (404) channelNotFound 找不到 id 參數指定的頻道，或該頻道沒有品牌選項。
notFound (404) unknownChannelId 找不到指定的頻道 ID。
notFound (404) unknownChannelId 找不到指定的 recentlyUploadedBy 頻道 ID。
notFound (404) unknownVideoId 找不到指定為宣傳項目的影片 ID。
required (400) requiredItemIdType 要求中繼資料必須在 invideoPromotion 部分指定項目類型。
required (400) requiredItemId 要求中繼資料必須指定 invideoPromotion 部分的項目 ID。
required (400) requiredTimingOffset 要求中繼資料必須指定預設時間偏移，YouTube 才能判斷何時顯示宣傳項目。在要求傳送的資源中，設定 invideoPromotion.defaultTiming.offsetMs 屬性的值。
required (400) requiredTimingOffset 要求中繼資料必須指定時間偏移，YouTube 才能判斷何時顯示宣傳商品。在要求傳送的資源中，設定 invideoPromotion.timing.offsetMs 屬性的值。
required (400) requiredTimingType 要求中繼資料必須指定時間設定方法，YouTube 才能判斷何時顯示宣傳項目。在要求傳送的資源中，設定 invideoPromotion.defaultTiming.type 屬性的值。
required (400) requiredTimingType 要求中繼資料必須指定時間設定方法，YouTube 才能判斷何時顯示宣傳項目。在要求傳送的資源中，設定 invideoPromotion.timing.type 屬性的值。
required (400) requiredTiming 要求中繼資料必須在 invideoPromotion 部分中，為每個項目指定時間碼。
required (400) requiredVideoId 要求中繼資料必須指定影片 ID，才能識別宣傳項目。
required (400) requiredWebsiteUrl 要求中繼資料必須在 invideoPromotion 部分指定網站網址。在要求傳送的資源中，設定 invideoPromotion.items[].id.websiteUrl 屬性的值。

試試看！

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