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,
      "moderateComments": boolean,
      "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 像素。頻道的寬度為 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 封鎖功能的頻道,才能上傳長片。

    頻道擁有者解決導致頻道無法上傳長片的問題後,頻道就會還原為「allowed」或「eligible」狀態。
  • 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.moderateComments boolean
這項設定可決定使用者能否在頻道頁面中提交其他使用者的留言,必須經過頻道擁有者核准才能公開發布。預設值為 false
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 頻道頁面的橫幅網址。圖片尺寸為 1060px x 175px。
brandingSettings.image.bannerMobileImageUrl string
這項屬性已淘汰,

顯示在頻道頁面的橫幅圖片網址。圖片尺寸為 640px x 175px。
brandingSettings.image.watchIconImageUrl string
這項屬性已淘汰,

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

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

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

平板電腦應用程式頻道頁面顯示的橫幅網址。圖片尺寸為 1707px x 283px。
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
這項屬性已淘汰,

顯示在電視應用程式頻道頁面的低解析度橫幅網址。圖片大小上限為 854px x 480px。
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
本地化版本的說明。