Channels

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

channel 資源包含 YouTube 頻道的相關資訊。

方法

這個 API 支援下列 channels 資源方法:

list
傳回零或多個符合要求條件的 channel 資源集合。立即試用
更新
更新頻道的中繼資料。請注意,這個方法目前僅支援更新 channel 資源的 brandingSettingsinvideoPromotion 物件及其子項屬性。 立即試用

資源表示法

下列 JSON 結構顯示 channels 資源的格式:

{
  "kind": "youtube#channel",
  "etag": etag,
  "id": string,
  "snippet": {
    "title": string,
    "description": string,
    "customUrl": string,
    "publishedAt": datetime,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "defaultLanguage": string,
    "localized": {
      "title": string,
      "description": string
    },
    "country": string
  },
  "contentDetails": {
    "relatedPlaylists": {
      "likes": string,
      "favorites": string,
      "uploads": string
    }
  },
  "statistics": {
    "viewCount": unsigned long,
    "subscriberCount": unsigned long,  // this value is rounded to three significant figures
    "hiddenSubscriberCount": boolean,
    "videoCount": unsigned long
  },
  "topicDetails": {
    "topicIds": [
      string
    ],
    "topicCategories": [
      string
    ]
  },
  "status": {
    "privacyStatus": string,
    "isLinked": boolean,
    "longUploadsStatus": string,
    "madeForKids": boolean,
    "selfDeclaredMadeForKids": boolean
  },
  "brandingSettings": {
    "channel": {
      "title": string,
      "description": string,
      "keywords": string,
      "trackingAnalyticsAccountId": string,
      "unsubscribedTrailer": string,
      "defaultLanguage": string,
      "country": string
    },
    "watch": {
      "textColor": string,
      "backgroundColor": string,
      "featuredPlaylistId": string
    }
  },
  "auditDetails": {
    "overallGoodStanding": boolean,
    "communityGuidelinesGoodStanding": boolean,
    "copyrightStrikesGoodStanding": boolean,
    "contentIdClaimsGoodStanding": boolean
  },
  "contentOwnerDetails": {
    "contentOwner": string,
    "timeLinked": datetime
  },
  "localizations": {
    (key): {
      "title": string,
      "description": string
    }
  }
}

屬性

下表定義了這項資源中顯示的屬性:

屬性
kind string
識別 API 資源的類型。值為 youtube#channel
etag etag
這項資源的 Etag。
id string
YouTube 用來識別頻道的專屬 ID。
snippet object
snippet 物件包含頻道的基本詳細資料,例如名稱、說明和縮圖圖片。
snippet.title string
頻道標題。
snippet.description string
頻道說明。屬性值的長度上限為 1000 個字元。
snippet.customUrl string
頻道的自訂網址。YouTube 說明中心說明瞭取得自訂網址的資格規定,以及網址的設定方式。
snippet.publishedAt datetime
建立頻道的日期與時間。這個值是以 ISO 8601 格式指定。
snippet.thumbnails object
與頻道相關的縮圖地圖。每個地圖物件的鍵都是縮圖名稱,而值則是包含縮圖其他資訊的物件。

在應用程式中顯示縮圖時,請確認程式碼使用的圖片網址與 API 回應中傳回的圖片網址完全相同。舉例來說,您的應用程式不應在 API 回應傳回的網址中使用 http 網域,而非 https 網域。

頻道縮圖網址只能在 https 網域中使用,這也是網址在 API 回應中的呈現方式。如果應用程式嘗試從 http 網域載入 YouTube 圖片,您的應用程式可能會顯示毀損的圖片。新建頻道的縮圖圖片可能空白,系統最多可能需要一天才會填入圖片。
snippet.thumbnails.(key) object
有效的鍵/值包括:
  • default:預設的縮圖圖片。影片的預設縮圖或參照影片的資源 (例如播放清單項目或搜尋結果) 的預設縮圖寬度為 120 像素,高度為 90 像素。頻道的預設縮圖寬度為 88 像素、高度 88 像素。
  • medium:縮圖解析度更高的版本。如為影片 (或參照影片的資源),這張圖片的寬度為 320 像素,高度為 180 像素。頻道的圖片寬度為 240 像素,高度為 240 像素。
  • high:縮圖的高解析度版本。如為影片 (或參照影片的資源),這張圖片的寬度為 480 像素,高度為 360 像素。對頻道而言,這張圖片寬度為 800 像素,高度為 800 像素。
snippet.thumbnails.(key).url string
圖片的網址。如需在應用程式中使用縮圖網址的其他指南,請參閱 snippet.thumbnails 屬性定義。
snippet.thumbnails.(key).width unsigned integer
圖片的寬度。
snippet.thumbnails.(key).height unsigned integer
圖片的高度。
snippet.defaultLanguage string
channel 資源 snippet.titlesnippet.description 屬性中的文字語言。
snippet.localized object
snippet.localized 物件包含頻道的本地化標題和說明,或包含頻道中繼資料預設語言中的頻道標題和說明。
  • 如果 channels.list 要求使用 hl 參數指定要傳回本地化文字的語言,hl 參數值就會識別 YouTube 應用程式語言,且本地化文字提供該語言時,系統會在資源程式碼片段中傳回本地化文字。
  • 如未指定 hl 參數值,或是已指定值,但不支援指定語言的中繼資料,則系統會傳回預設語言的中繼資料。
屬性包含唯讀值。使用 localizations 物件新增、更新或刪除本地化中繼資料。
snippet.localized.title string
本地化頻道名稱。
snippet.localized.description string
本地化頻道說明。
snippet.country string
頻道關聯的國家/地區。如要設定此屬性的值,請更新 brandingSettings.channel.country 屬性的值。
contentDetails object
contentDetails 物件會封裝頻道內容的相關資訊。
contentDetails.relatedPlaylists object
relatedPlaylists 物件是地圖,用於識別與頻道相關的播放清單,例如頻道上傳的影片或喜歡的影片。您可以使用 playlists.list 方法擷取任何播放清單。
contentDetails.relatedPlaylists.likes string
含有頻道喜歡影片的播放清單 ID。使用 playlistItems.insertplaylistItems.delete 方法在清單中新增或移除項目。
contentDetails.relatedPlaylists.favorites string
我們已淘汰這項資源。

含有頻道最愛影片的播放清單 ID。請使用 playlistItems.insertplaylistItems.delete 方法在清單中新增或移除項目。

請注意,YouTube 已淘汰收藏的影片功能。舉例來說,video 資源的 statistics.favoriteCount 屬性已於 2015 年 8 月 28 日淘汰。基於歷史原因,這個屬性值可能含有播放清單 ID 來參照空的播放清單,因此無法擷取。
contentDetails.relatedPlaylists.uploads string
頻道上傳影片所屬的播放清單 ID。使用 videos.insert 方法上傳新影片,並使用 videos.delete 方法刪除先前上傳的影片。
statistics object
statistics 物件會封裝管道的統計資料。
statistics.viewCount unsigned long
頻道的觀看次數。
statistics.commentCount unsigned long
此屬性已淘汰。

頻道的留言數量。
statistics.subscriberCount unsigned long
頻道擁有的訂閱人數。這個值會無條件捨去為三個有效數字。如要進一步瞭解訂閱人數的計算方式,請參閱修訂版本記錄YouTube 說明中心
statistics.hiddenSubscriberCount boolean
指出頻道的訂閱人數是否公開顯示。
statistics.videoCount unsigned long
上傳至頻道的公開影片數量。請注意,這個數值只反映頻道公開影片的數量,即使是擁有者也不例外。這項行為與 YouTube 網站上顯示的次數一致。
topicDetails object
topicDetails 物件會封裝與頻道相關主題相關的資訊。

重要事項:如要進一步瞭解主題 ID 相關變更,請參閱 topicDetails.topicIds[] 屬性定義和修訂版本記錄
topicDetails.topicIds[] list
與頻道相關聯的主題 ID 清單。

這項資源已於 2016 年 11 月 10 日淘汰。直到 2017 年 11 月 10 日止。

重要事項:由於 Freebase 和 Freebase API 已淘汰,主題 ID 的運作方式也從 2017 年 2 月 27 日起開始不同。屆時 YouTube 已開始傳回一小部分的精選主題 ID。

topicDetails.topicCategories[] list
說明頻道內容的維基百科網址清單。
status object
status 物件會封裝頻道的隱私權狀態相關資訊。
status.privacyStatus string
頻道的隱私權狀態。

這項資源的有效值如下:
  • private
  • public
  • unlisted
status.isLinked boolean
指出頻道資料是否可用來識別已連結至 YouTube 使用者名稱或 Google+ 帳戶的使用者。具有這類連結的使用者已具有公開的 YouTube 身分,這是執行多項操作 (例如上傳影片) 的先決條件。
status.longUploadsStatus string
指出頻道是否有資格上傳長度超過 15 分鐘的影片。只有在頻道擁有者授權 API 要求時,才會傳回這個屬性。如要進一步瞭解這項功能,請參閱 YouTube 說明中心

這項資源的有效值如下:
  • allowed:這個頻道可以上傳長度超過 15 分鐘的影片。
  • disallowed:這個頻道無法或不符合上傳長度超過 15 分鐘的影片。根據《YouTube 社群規範》的定義,頻道記錄良好,且內容未受到全球 Content ID 封鎖限制,才符合上傳長片資格。

    頻道擁有者解決導致頻道無法上傳長片的問題後,頻道就會恢復為allowedeligible狀態。
  • eligible:這個頻道可以上傳長度超過 15 分鐘的影片。不過,頻道擁有者必須先前往 https://www.youtube.com/verify 上傳更長的影片。如要進一步瞭解這項功能,請參閱 YouTube 說明中心
status.madeForKids boolean
這個值指出頻道是否標示為兒童導向,且包含頻道目前的「兒童專屬」狀態。舉例來說,系統可能會根據 selfDeclaredMadeForKids 屬性的值決定狀態。如要進一步瞭解如何為頻道、影片或廣播設定目標觀眾,請參閱 YouTube 說明中心
status.selfDeclaredMadeForKids boolean
channels.update 要求中,這個屬性可讓頻道擁有者將頻道指定為兒童導向內容。只有在頻道擁有者授權 API 要求的情況下,系統才會傳回屬性值。
brandingSettings object
brandingSettings 物件會封裝頻道品牌宣傳的相關資訊。
brandingSettings.channel object
channel 物件會封裝頻道頁面的品牌屬性。
brandingSettings.channel.title string
頻道標題。標題的長度上限為 30 個字元。
brandingSettings.channel.description string
頻道說明會顯示在頻道頁面的頻道資訊方塊中。屬性值的長度上限為 1000 個字元。
brandingSettings.channel.keywords string
與頻道相關聯的關鍵字。這個值是以空格分隔的字串清單。如果頻道關鍵字超過 500 個字元的長度上限,或是含有未逸出的引號 ("),可能會遭到截斷。請注意,500 個字元的限制並非每個關鍵字的上限,而是所有關鍵字的總長度限制。
brandingSettings.channel.trackingAnalyticsAccountId string
要用來追蹤及評估頻道流量的 Google Analytics (分析) 帳戶 ID。
brandingSettings.channel.unsubscribedTrailer string
未訂閱觀眾會在頻道頁面瀏覽檢視畫面的精選影片模組中播放的影片。訂閱的觀眾可能會看見另一部影片,當中介紹頻道最近的活動。

如有指定,屬性值必須是頻道擁有者擁有的公開或不公開影片的 YouTube 影片 ID。
brandingSettings.channel.defaultLanguage string
channel 資源 snippet.titlesnippet.description 屬性中的文字語言。
brandingSettings.channel.country string
頻道關聯的國家/地區。更新這個屬性來設定 snippet.country 屬性的值。
brandingSettings.watch object
注意:這個物件及其所有子項屬性都已淘汰。

watch 物件會封裝頻道影片觀賞頁面的品牌屬性。
brandingSettings.watch.textColor string
注意:這項屬性已淘汰。

影片觀賞頁面品牌區域的文字顏色。
brandingSettings.watch.backgroundColor string
注意:這項屬性已淘汰。

影片觀賞頁面的品牌區域背景顏色。
brandingSettings.watch.featuredPlaylistId string
注意:這項屬性已淘汰。如果您嘗試設定其值,API 會傳回錯誤。
brandingSettings.image object
此屬性及其所有子項資源已淘汰。

image 物件會封裝頻道頁面或影片觀賞頁面上顯示的圖片資訊。
brandingSettings.image.bannerImageUrl string
此屬性已淘汰。

YouTube 網站頻道頁面上顯示的橫幅圖片網址。圖片為 1060 像素 x 175 像素。
brandingSettings.image.bannerMobileImageUrl string
此屬性已淘汰。

顯示在行動應用程式頻道頁面的橫幅圖片網址。圖片為 640 x 175 像素。
brandingSettings.image.watchIconImageUrl string
此屬性已淘汰。

顯示在影片播放器上方的圖片網址。這張圖片為 25 像素的高度,彈性寬度不得超過 170 像素。如果您未提供圖片,系統就會顯示您的頻道名稱,而非圖片。
brandingSettings.image.trackingImageUrl string
此屬性已淘汰。

1 x 1 像素追蹤像素的網址,可用於收集頻道或影片頁面觀看次數的統計資料。
brandingSettings.image.bannerTabletLowImageUrl string
此屬性已淘汰。

低解析度橫幅圖片的網址,會顯示在平板電腦應用程式的頻道頁面。圖片的大小上限為 1138 x 188 像素。
brandingSettings.image.bannerTabletImageUrl string
此屬性已淘汰。

平板電腦應用程式頻道頁面中顯示的橫幅圖片網址。圖片為 1707 x 283 像素。
brandingSettings.image.bannerTabletHdImageUrl string
此屬性已淘汰。

高解析度橫幅圖片的網址,會顯示在平板電腦應用程式的頻道頁面。圖片尺寸上限為 2276 x 377 像素。
brandingSettings.image.bannerTabletExtraHdImageUrl string
此屬性已淘汰。

高解析度橫幅圖片的網址,會顯示在平板電腦應用程式的頻道頁面。圖片的大小上限為 2560 x 424 像素。
brandingSettings.image.bannerMobileLowImageUrl string
此屬性已淘汰。

低解析度橫幅圖片的網址,會顯示在行動應用程式的頻道頁面。圖片的大小上限為 320 x 88 像素。
brandingSettings.image.bannerMobileMediumHdImageUrl string
此屬性已淘汰。

中解析度橫幅圖片的網址,會顯示在行動應用程式的頻道頁面。圖片的大小上限為 960 x 263 像素。
brandingSettings.image.bannerMobileHdImageUrl string
此屬性已淘汰。

高解析度橫幅圖片的網址,會顯示在行動應用程式的頻道頁面。圖片的大小上限為 1280 x 360 像素。
brandingSettings.image.bannerMobileExtraHdImageUrl string
此屬性已淘汰。

高解析度橫幅圖片的網址,會顯示在行動應用程式的頻道頁面。圖片的大小上限為 1440 x 395 像素。
brandingSettings.image.bannerTvImageUrl string
此屬性已淘汰。

高解析度橫幅圖片的網址,會顯示在電視應用程式的頻道頁面。圖片的大小上限為 2120 x 1192 像素。
brandingSettings.image.bannerTvLowImageUrl string
此屬性已淘汰。

低解析度橫幅圖片的網址,會顯示在電視應用程式的頻道頁面。圖片的大小上限為 854 x 480 像素。
brandingSettings.image.bannerTvMediumImageUrl string
此屬性已淘汰。

電視應用程式頻道頁面中顯示的中解析度橫幅圖片網址。圖片的大小上限為 1280 x 720 像素。
brandingSettings.image.bannerTvHighImageUrl string
此屬性已淘汰。

顯示在電視應用程式的頻道頁面的高解析度橫幅圖片網址。圖片的大小上限為 1920 x 1080 像素。
brandingSettings.image.bannerExternalUrl string
這個屬性指定橫幅圖片的位置,供 YouTube 用來為頻道產生各種橫幅圖片大小。
brandingSettings.hints[] list
此屬性及其所有子項資源已淘汰。

hints 物件會封裝其他品牌屬性。
brandingSettings.hints[].property string
此屬性已淘汰。

資源。
brandingSettings.hints[].value string
此屬性已淘汰。

屬性的值。
auditDetails object
auditDetails 物件會封裝多頻道聯播網 (MCN) 評估的頻道資料,並決定是否接受或拒絕特定頻道。請注意,任何擷取這個資源部分的 API 要求都必須提供包含 https://www.googleapis.com/auth/youtubepartner-channel-audit 範圍的授權權杖。此外,當 MCN 決定接受或拒絕頻道時,或在核發權杖後的兩週內,必須撤銷使用該範圍的權杖。
auditDetails.overallGoodStanding boolean
這個欄位會指出頻道是否有任何問題。目前,這個欄位代表 communityGuidelinesGoodStandingcopyrightStrikesGoodStandingcontentIdClaimsGoodStanding 屬性的邏輯 AND 運算結果,表示如果其他所有屬性也有 true 的值,這個屬性的值就是 true。不過,如果任何屬性的值為 false,這個屬性的值將是 false。不過請注意,用於設定此屬性值的方法隨時可能變動。
auditDetails.communityGuidelinesGoodStanding boolean
表明頻道是否遵循 YouTube《社群規範》。
auditDetails.copyrightStrikesGoodStanding boolean
指出頻道是否收到版權警告。
auditDetails.contentIdClaimsGoodStanding boolean
指出頻道是否有任何尚未解決的版權聲明。
contentOwnerDetails object
contentOwnerDetails 物件會封裝頻道資料,僅供將頻道連結至內容管理員的 YouTube 合作夥伴查看。
contentOwnerDetails.contentOwner string
連結至頻道的內容擁有者 ID。
contentOwnerDetails.timeLinked datetime
頻道與內容擁有者相連結的日期和時間。這個值是以 ISO 8601 格式指定。
localizations object
localizations 物件會封裝頻道中繼資料的翻譯。
localizations.(key) object
與鍵/值相關聯的本地化中繼資料語言。這個值是包含 BCP-47 語言代碼的字串。
localizations.(key).title string
本地化頻道名稱。
localizations.(key).description string
本地化頻道說明。