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 像素。頻道圖片的寬度和高度為 240px 和 240px。
  • high:縮圖的高解析度版本。影片 (或影片資源) 寬度為 480 像素,高度為 360 像素。頻道圖片的寬度和高度為 800px 和 800px。
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
頻道的訂閱人數。這個值會無條件捨去為 3 重要數據詳情請參閱 修訂版本記錄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 limit 並非每個關鍵字的限制,而是所有關鍵字的總長度限制。
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 頻道頁面上橫幅圖片的網址。圖片為 1060px x 175px。
brandingSettings.image.bannerMobileImageUrl string
這項屬性已淘汰

在行動應用程式中,頻道頁面上顯示橫幅圖片的網址。圖片為 640px x 175px。
brandingSettings.image.watchIconImageUrl string
這項屬性已淘汰

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

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

這是低解析度橫幅圖片的網址,此網址會在平板電腦應用程式的頻道頁面上顯示。圖片的大小上限為 1138 x 188 像素。
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
這項屬性已淘汰

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