该 API 现在支持将您的频道或视频标记为“面向儿童的内容”。此外,
channel
和 video
资源现在还包含一个属性,用于标识相应频道或视频是否属于“面向儿童的内容”。YouTube API 服务的《服务条款》和《开发者政策》也已于 2020 年 1 月 10 日更新。如需了解详情,请参阅 YouTube Data API 服务和 YouTube API 服务的服务条款的修订历史记录。channel
资源包含有关 YouTube 频道的信息。
方法
对于 channels
资源,该 API 支持以下方法:
资源表示法
以下 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 网站的频道页上显示的横幅图片的网址。图片尺寸为 1060x175 像素。 |
brandingSettings.image.bannerMobileImageUrl |
string 此属性已废弃。 移动应用中频道页上显示的横幅图片的网址。图片尺寸为 640x175 像素。 |
brandingSettings.image.watchIconImageUrl |
string 此属性已废弃。 视频播放器上方显示的图片的网址。此图片高 25 像素,宽度不固定,不得超过 170 像素。如果您不提供该图片,系统会显示您的频道名称,而不是图片。 |
brandingSettings.image.trackingImageUrl |
string 此属性已废弃。 1x1 像素跟踪像素的网址,可用于收集频道或视频页的观看次数统计信息。 |
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 此属性已废弃。 移动应用的频道页上显示的中分辨率横幅图片的网址。图片的最大尺寸为 960x263 像素。 |
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 此属性已废弃。 电视应用的频道页上显示的高分辨率横幅图片的网址。图片的最大尺寸为 1920x1080 像素。 |
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 范围的授权令牌。此外,如果多频道网络决定接受或拒绝频道,或者在令牌发放后的两周内,就必须撤消使用该范围的任何令牌。 |
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 本地化频道说明。 |