這個 API 現已支援將頻道或影片標示成「兒童專屬」的功能。此外,
channel
和 video
資源現在也包含一項資源,可指明頻道或影片處於「兒童專屬」狀態。YouTube API 的《服務條款》和《開發人員政策》也已於 2020 年 1 月 10 日更新。詳情請參閱 YouTube Data API 服務和《YouTube API 服務條款》的修訂版本記錄。channel
資源包含 YouTube 頻道的相關資訊。
方法
這個 API 支援下列 channels
資源方法:
資源表示法
下列 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 有效的鍵/值包括:
|
snippet.thumbnails.(key).url |
string 圖片的網址。如需在應用程式中使用縮圖網址的其他指南,請參閱 snippet.thumbnails 屬性定義。 |
snippet.thumbnails.(key).width |
unsigned integer 圖片的寬度。 |
snippet.thumbnails.(key).height |
unsigned integer 圖片的高度。 |
snippet.defaultLanguage |
string channel 資源 snippet.title 和 snippet.description 屬性中的文字語言。 |
snippet.localized |
object snippet.localized 物件包含頻道的本地化標題和說明,或包含頻道中繼資料預設語言中的頻道標題和說明。
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.insert 和 playlistItems.delete 方法在清單中新增或移除項目。 |
contentDetails.relatedPlaylists.favorites |
string 我們已淘汰這項資源。 含有頻道最愛影片的播放清單 ID。請使用 playlistItems.insert 和 playlistItems.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.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 頻道的隱私權狀態。 這項資源的有效值如下:
|
status.isLinked |
boolean 指出頻道資料是否可用來識別已連結至 YouTube 使用者名稱或 Google+ 帳戶的使用者。具有這類連結的使用者已具有公開的 YouTube 身分,這是執行多項操作 (例如上傳影片) 的先決條件。 |
status.longUploadsStatus |
string 指出頻道是否有資格上傳長度超過 15 分鐘的影片。只有在頻道擁有者授權 API 要求時,才會傳回這個屬性。如要進一步瞭解這項功能,請參閱 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.title 和 snippet.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 這個欄位會指出頻道是否有任何問題。目前,這個欄位代表 communityGuidelinesGoodStanding 、copyrightStrikesGoodStanding 和 contentIdClaimsGoodStanding 屬性的邏輯 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 本地化頻道說明。 |