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 頻道的訂閱人數。這個值會無條件捨去為 3 重要數據詳情請參閱 修訂版本記錄或 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
limit 並非每個關鍵字的限制,而是所有關鍵字的總長度限制。 |
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 頻道頁面上橫幅圖片的網址。圖片為 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 這個欄位會指出該頻道是否有任何問題。目前,這個欄位代表 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 本地化頻道說明。 |