Channels

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。
该 API 现在支持将您的频道或视频标记为“面向儿童的内容”。此外，channel 和 video 资源现在还包含一项标识该频道或视频的“面向儿童的内容”状态的属性。《YouTube API 服务服务条款》和《开发者政策》也在 2020 年 1 月 10 日进行了更新。如需了解详情，请参阅 YouTube Data API 服务和 YouTube API 服务的服务条款的修订历史记录。

channel 资源包含 YouTube 频道的相关信息。

方法

该 API 支持 channels 资源的以下方法：

list
返回与请求条件匹配的零个或多个 channel 资源的集合。 立即试用。
update
更新频道的元数据。请注意，此方法目前仅支持更新 channel 资源的 brandingSettings 和 invideoPromotion 对象及其子属性。 立即试用。

资源表示法

以下 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 px，高度为 90 px。频道的默认缩略图宽度为 88px，高度为 88px。
  • medium - 缩略图的高分辨率版本。对于视频（或引用视频的资源），此图片的宽度为 320 像素，高度为 180 像素。对于频道，此图片的宽度为 240 像素，高度为 240 像素。
  • high - 缩略图的高分辨率版本。对于视频（或引用视频的资源），此图片宽 480 像素，高 360 像素。对于频道，此图片的宽度为 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.title 和 snippet.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.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.hiddenSubscriberCount boolean
指明频道的订阅人数是否公开显示。
statistics.videoCount unsigned long
上传到频道的公开视频的数量。请注意，该值只反映频道的公开视频数量，即使对于所有者也是如此。此行为与 YouTube 网站上显示的计数一致。
topicDetails object
topicDetails 对象可封装与频道相关联的主题的相关信息。

重要提示：如需详细了解与主题 ID 相关的变更，请参阅 topicDetails.topicIds[] 属性定义和修订历史记录。
topicDetails.topicIds[] list
与该频道相关联的主题 ID 的列表。

此属性自 2016 年 11 月 10 日起已弃用。我们将于 2017 年 11 月 10 日停止支持此 API。

重要提示：由于 Freebase 和 Freebase API 已弃用，因此从 2017 年 2 月 27 日开始，主题 ID 的运作方式有所不同。当时，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 社区准则、信誉良好，并且在全球范围内没有任何内容 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.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
此属性已被弃用。

在平板电脑应用的频道页中显示的横幅图片的网址。图片为 1707x283 像素。
brandingSettings.image.bannerTabletHdImageUrl string
此属性已被弃用。

在平板电脑应用中的频道页面上显示的高分辨率横幅图片的网址。图片尺寸上限为 2276 x 377 像素。
brandingSettings.image.bannerTabletExtraHdImageUrl string
此属性已被弃用。

在平板电脑应用的频道页面上显示超高分辨率横幅图片的网址。图片尺寸上限为 2560x424 像素。
brandingSettings.image.bannerMobileLowImageUrl string
此属性已被弃用。

显示在移动应用的频道页上显示的低分辨率横幅图片的网址。图片尺寸上限为 320x88 像素。
brandingSettings.image.bannerMobileMediumHdImageUrl string
此属性已被弃用。

显示在移动应用频道页上显示的中等分辨率横幅图片的网址。图片尺寸上限为 960x263 像素。
brandingSettings.image.bannerMobileHdImageUrl string
此属性已被弃用。

在移动应用的频道页上显示的高分辨率横幅图片的网址。图片尺寸上限为 1280x360 像素。
brandingSettings.image.bannerMobileExtraHdImageUrl string
此属性已被弃用。

显示在移动应用的频道页中的高分辨率横幅图片的网址。图片尺寸上限为 1440x395 像素。
brandingSettings.image.bannerTvImageUrl string
此属性已被弃用。

显示在电视应用中的频道页面上的超高分辨率横幅图片的网址。图片尺寸上限为 2120x1192 像素。
brandingSettings.image.bannerTvLowImageUrl string
此属性已被弃用。

显示在电视应用中的频道页面上的低分辨率横幅图片的网址。图片尺寸上限为 854x480 像素。
brandingSettings.image.bannerTvMediumImageUrl string
此属性已被弃用。

中等分辨率的横幅图片的网址，显示在电视应用的频道页中。图片尺寸上限为 1280x720 像素。
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
本地化渠道说明。