借助 YouTube Data API,您可以将通常在 YouTube 网站上执行的函数整合到您自己的网站或应用中。以下列表列出了您可以使用该 API 检索到的不同类型的资源。该 API 还支持用于插入、更新或删除这些资源中的许多资源。
本参考指南介绍了如何使用 API 执行所有这些操作。本指南按资源类型组织。资源表示构成部分 YouTube 体验的内容的类型,例如视频、播放列表或订阅。对于每种资源类型,该指南都会列出一种或多种数据表示形式,并且资源以 JSON 对象的形式表示。该指南还为每种资源类型列出了一种或多种受支持的方法(LIST
、POST
、DELETE
等),并说明了如何在应用中使用这些方法。
调用 API
以下要求适用于 YouTube Data API 请求:
-
每个请求都必须指定 API 密钥(使用
key
参数)或提供 OAuth 2.0 令牌。您的 API 密钥位于项目的 Developer Console API 访问权限窗格中。 -
您必须为每个插入、更新和删除请求发送授权令牌。对于检索经过身份验证的用户的隐私数据的任何请求,您还必须发送授权令牌。
此外,某些用于检索资源的 API 方法可能支持需要授权的参数,或者在授权请求中包含其他元数据。例如,检索用户的已上传视频的请求中可能包含私享视频。
-
该 API 支持 OAuth 2.0 身份验证协议。您可以通过以下任一方式提供 OAuth 2.0 令牌:
- 请使用如下所示的
access_token
查询参数:?access_token=
oauth2-token
- 使用如下所示的 HTTP
Authorization
标头:Authorization: Bearer
oauth2-token
有关如何在应用中实施 OAuth 2.0 身份验证的完整说明,请参阅身份验证指南。
- 请使用如下所示的
资源类型
活动
activity
资源包含有关特定频道或用户在 YouTube 上执行的操作的信息。活动 Feed 中报告的操作包括对视频评分、分享视频、将视频标记为收藏视频、上传视频等。每个 activity
资源标识了操作类型、与操作相关联的频道以及与操作关联的资源,例如获得评分或上传的视频。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /activities |
返回与请求条件匹配的频道活动事件的列表。例如,您可以检索与特定频道或用户自己的频道相关联的事件。 |
insert |
POST /activities |
注意:此方法已被弃用,不再受支持。 |
字幕
caption
资源表示 YouTube 字幕轨道。一个字幕轨道恰好与一个 YouTube 视频相关联。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /captions |
删除指定的字幕轨道。 |
download |
GET /captions/id |
下载字幕轨道。除非请求为 tfmt 参数及源语言指定值,否则系统会以原始格式返回字幕轨道;除非请求为 tlang 参数指定值。 |
insert |
POST /captions |
上传字幕轨道。 |
list |
GET /captions |
返回与指定视频相关联的字幕轨道列表。请注意,该 API 响应不包含实际字幕,captions.download 方法可用于检索字幕轨道。 |
update |
PUT /captions |
更新字幕轨道。更新字幕轨道时,您可以更改该轨道的草稿状态,或者为轨道上传新的字幕文件。 |
频道横幅
channelBanner
资源包含用于将新上传的图片设为频道的横幅图片的网址。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
insert |
POST /channelBanners/insert |
将频道横幅图片上传到 YouTube。此方法表示更新频道横幅图片的三个步骤中的前两个步骤:
|
频道版块
channelSection
资源包含有关频道选择精选的视频集的信息。例如,版块可以展示频道最新上传的视频、热门上传视频,以及来自一个或多个播放列表的视频。
请注意,只有当频道在浏览视图(而非 Feed 视图)中显示时,系统才会显示频道的版块。为了让频道能在浏览视图中显示内容,请将指定频道的 brandingSettings.channel.showBrowseView
属性设置为 true
。
一个频道最多可以创建 10 个频道架。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /channelSections |
删除频道版块。 |
insert |
POST /channelSections |
将频道部分添加到经过身份验证的用户的频道。一个渠道最多可以创建 10 个书架。 |
list |
GET /channelSections |
返回与 API 请求条件匹配的 channelSection 资源列表。 |
update |
PUT /channelSections |
更新频道版块。 |
频道
channel
资源包含 YouTube 频道的相关信息。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /channels |
返回零个或多个符合请求条件的 channel 资源的集合。 |
update |
PUT /channels |
更新频道的元数据。请注意,此方法目前仅支持更新 channel 资源的 brandingSettings 和 invideoPromotion 对象及其子属性。 |
评论会话
commentThread
资源包含有关 YouTube 评论会话的信息,其中包括评论的顶级评论和回复(如果存在)。commentThread
资源可以表示有关视频或频道的评论。
顶级评论和回复实际上都是嵌套在 commentThread
资源中的 comment
资源。commentThread
资源不一定包含对评论的所有回复,如果要检索对特定评论的所有回复,您需要使用 comments.list
方法。另请注意,有些评论没有回复。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /commentThreads |
返回与 API 请求参数匹配的评论线程列表。 |
insert |
POST /commentThreads |
创建新的顶级评论。如需为现有评论添加回复,请改用 comments.insert 方法。 |
评论数
comment
资源包含一条 YouTube 评论的相关信息。comment
资源可以表示有关视频或频道的评论。此外,评论可以是顶级评论,也可以是对顶级评论的回复。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /comments |
返回与 API 请求参数匹配的注释列表。 |
setModerationStatus |
POST /comments/setModerationStatus |
设置一条或多条评论的审核状态。该 API 请求必须获得与评论相关联的频道或视频的所有者的授权。 |
insert |
POST /comments |
创建对现有评论的回复。注意:如需创建顶级注释,请使用 commentThreads.insert 方法。 |
markAsSpam |
POST /comments/markAsSpam |
表达来电者的意见,即一条或多条评论应该被标记为垃圾内容。 |
delete |
DELETE /comments |
删除评论。 |
update |
PUT /comments |
修改评论。 |
指南类别
guideCategory
资源用于标识 YouTube 根据频道内容或其他指标(例如频道的热门程度)通过算法分配的类别。此列表与视频类别类似,区别在于视频上传者可以分配视频类别,但只有 YouTube 可以分配频道类别。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /guideCategories |
返回可与 YouTube 频道相关联的类别列表。 |
I18n 语言
i18nLanguage
资源用于标识 YouTube 网站所支持的应用语言。应用语言也称为界面语言。对于 YouTube 网站,系统可能会根据 Google 帐号设置、浏览器语言或 IP 地址自动选择应用语言。用户也可以从 YouTube 网站页脚手动选择所需的界面语言。
每项 i18nLanguage
资源都指定了语言代码和名称。调用 videoCategories.list
和 guideCategories.list
等 API 方法时,语言代码可用作 hl
参数的值。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /i18nLanguages |
返回 YouTube 网站支持的应用语言列表。 |
I18n 区域
i18nRegion
资源用于标识 YouTube 用户可以选择作为首选内容区域的地理区域。内容区域也称为内容语言区域。对于 YouTube 网站,系统会根据 YouTube 网域或用户的 IP 位置等启发法自动选择内容区域。用户也可以从 YouTube 网站页脚手动选择所需的内容区域。
每项 i18nRegion
资源都标识了区域代码和名称。调用 search.list
、videos.list
、activities.list
和 videoCategories.list
等 API 方法时,地区代码可用作 regionCode
参数的值。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /i18nRegions |
返回 YouTube 网站支持的内容区域的列表。 |
会员
member
资源表示 YouTube 频道的频道会员。会员可定期向创作者提供资金支持、获享特殊福利。例如,创作者可以在开启聊天功能后开启会员专享模式,让会员参与聊天。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /members |
列出频道的成员(以前称为“赞助商”)。该 API 请求必须由频道所有者授权。 |
会员级别
membershipsLevel
资源用于标识授权 API 请求的创建者的价格级别。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /membershipsLevels |
返回授权 API 请求的渠道拥有的零个或多个 membershipsLevel 资源的集合。级别以隐式显示顺序返回。 |
播放列表项
playlistItem
资源用于标识播放列表中包含的其他资源,例如视频。此外,playlistItem
资源还包含所含资源的详细信息,具体与该资源在该播放列表中的使用方式有关。
YouTube 还会使用播放列表来识别频道中上传的视频列表,其中每个 playlistItem
代表一个上传的视频。您可以从给定频道的 channel resource
中检索该列表的播放列表 ID。然后,您可以使用 playlistItems.list
方法创建列表。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /playlistItems |
删除播放列表项。 |
insert |
POST /playlistItems |
将资源添加到播放列表。 |
list |
GET /playlistItems |
返回与 API 请求参数匹配的播放列表项集合。您可以检索指定播放列表中的所有播放列表项,或者按播放列表 ID 检索一个或多个播放列表项。 |
update |
PUT /playlistItems |
修改播放列表项。例如,您可以更新项在播放列表中的位置。 |
播放列表
playlist
资源表示 YouTube 播放列表。播放列表是可以依序观看并与其他用户分享的视频的集合。一个播放列表最多可包含 200 个视频,而 YouTube 不限制每位用户创建的播放列表数量。默认情况下,播放列表是向其他用户公开显示的,但播放列表可以设为公开或私享。
YouTube 还会使用播放列表来确定频道的特殊视频集合,例如:
- 上传的视频
- 好评(顶)的视频
- 观看记录
- 稍后观看
channel resource
中检索特定频道的这些列表的 ID。然后,您可以使用
playlistItems.list
方法检索任意列表。您还可以通过调用 playlistItems.insert
和 playlistItems.delete
方法向这些列表中添加或移除项。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /playlists |
删除播放列表。 |
list |
GET /playlists |
返回与 API 请求参数匹配的一系列播放列表。例如,您可以检索经过身份验证的用户拥有的所有播放列表,也可以按唯一 ID 检索一个或多个播放列表。 |
insert |
POST /playlists |
创建播放列表。 |
update |
PUT /playlists |
修改播放列表。例如,您可以更改播放列表的标题、说明或隐私设置。 |
搜索
搜索结果包含有关 YouTube 视频、频道或播放列表的信息,这些信息与 API 请求中指定的搜索参数相匹配。虽然搜索结果指向可明确识别的资源(例如视频),但它没有自己的持久性数据。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /search |
返回与 API 请求中指定的查询参数匹配的搜索结果集合。默认情况下,搜索结果集可识别匹配的 video 、channel 和 playlist 资源,但您也可以将查询配置为仅检索特定类型的资源。 |
订阅
subscription
资源包含 YouTube 用户订阅的相关信息。订阅会在用户向频道添加新视频时或在 YouTube 上执行其他操作(例如上传视频、为视频评分或评论视频)时通知用户。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
delete |
DELETE /subscriptions |
删除订阅。 |
insert |
POST /subscriptions |
为经过身份验证的用户的频道添加订阅。 |
list |
GET /subscriptions |
返回与 API 请求条件匹配的订阅资源。 |
缩略图
thumbnail
资源用于标识与资源关联的不同缩略图大小。请注意缩略图的以下特征:
- 资源的
snippet.thumbnails
属性是一个对象,用于标识可用于该资源的缩略图。 thumbnail
资源包含一系列对象。每个对象(default
、medium
、high
等)的名称指的是缩略图大小。- 不同类型的资源可能支持不同的缩略图尺寸。
- 不同类型的资源可能会为同名缩略图定义不同的尺寸。例如,
video
资源的default
缩略图通常为 120 x 90 像素,channel
资源的default
缩略图通常为 88 x 88 像素。 - 对于同类型资源,某些图片可能还有不同的缩略图大小,具体取决于原始图片或上传到 YouTube 的内容的分辨率。例如,与非高清视频相比,高清视频支持的缩略图分辨率可能更高。
- 每个包含缩略图大小信息的对象都具有
width
属性和height
属性。不过,系统可能不会针对该图片返回宽度和高度属性。 - 如果上传的缩略图与要求的尺寸不匹配,系统会调整图片的大小以匹配正确的尺寸,而不会更改其宽高比。图片未剪裁,但可以包含黑边,以确保大小正确无误。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
set |
POST /thumbnails/set |
将自定义视频缩略图上传到 YouTube 并设置视频。 |
视频滥用原因
videoAbuseReportReason
资源包含有关视频因包含滥用内容而遭到举报的原因的信息。当您的应用调用 videos.reportAbuse
方法报告滥用视频时,该请求会使用 videoAbuseReportReason
资源中的信息来确定视频被举报的原因。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /videoAbuseReportReasons |
检索可用于举报侮辱性视频的原因列表。 |
视频类别
videoCategory
资源用于标识已上传的视频或已与上传的视频相关联的类别。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
list |
GET /videoCategories |
返回可与 YouTube 视频相关联的类别列表。 |
视频
video
资源表示 YouTube 视频。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
insert |
POST /videos |
将视频上传到 YouTube,并视需要设置视频的元数据。 |
list |
GET /videos |
返回与 API 请求参数匹配的视频列表。 |
delete |
DELETE /videos |
删除 YouTube 视频。 |
update |
PUT /videos |
更新视频的元数据。 |
rate |
POST /videos/rate |
给视频一个“顶”或“踩”评分,或者从视频中移除评分。 |
getRating |
GET /videos/getRating |
检索授权用户对指定视频列表的评分。 |
reportAbuse |
POST /videos/reportAbuse |
举报包含侮辱性内容的视频。 |
水印
watermark
资源用于标识在指定频道的视频播放期间显示的图片。您还可以指定图片将链接到的目标频道,以及确定水印在视频播放过程中何时显示以及显示时间长度的具体时间信息。
方法 | HTTP 请求 | 说明 |
---|---|---|
相对于 https://www.googleapis.com/youtube/v3 的 URI |
||
set |
POST /watermarks/set |
将水印图片上传到 YouTube,然后为频道设置水印。 |
unset |
POST /watermarks/unset |
删除频道的水印图片。 |