介绍
本文档面向想要编写与 YouTube 交互的应用程序的开发人员。它解释了 YouTube 和 API 本身的基本概念。它还概述了 API 支持的不同功能。
在你开始前
-
您需要一个Google 帐户才能访问 Google API 控制台、请求 API 密钥和注册您的应用程序。
-
在Google Developers Console 中创建一个项目并获取授权凭证,以便您的应用程序可以提交 API 请求。
-
创建项目后,请确保 YouTube 数据 API 是您的应用程序注册使用的服务之一:
- 转到API 控制台并选择您刚刚注册的项目。
- 访问启用的 API 页面。在API列表中,确保状态是ON的YouTube数据API V3。
-
如果您的应用程序将使用任何需要用户授权的 API 方法,请阅读身份验证指南以了解如何实现 OAuth 2.0 授权。
-
选择一个客户端库来简化您的 API 实现。
-
熟悉 JSON(JavaScript Object Notation)数据格式的核心概念。JSON 是一种通用的、独立于语言的数据格式,它提供任意数据结构的简单文本表示。有关更多信息,请参阅json.org。
资源和资源类型
资源是具有唯一标识符的单个数据实体。下表描述了您可以使用 API 进行交互的不同类型的资源。
资源 | |
---|---|
activity |
包含有关特定用户在 YouTube 网站上执行的操作的信息。活动源中报告的用户操作包括对视频进行评级、共享视频、将视频标记为收藏以及发布频道公告等。 |
channel |
包含有关单个 YouTube 频道的信息。 |
channelBanner |
标识用于将新上传的图像设置为频道的横幅图像的 URL。 |
channelSection |
包含有关频道选择展示的一组视频的信息。例如,一个版块可以展示频道的最新上传内容、最受欢迎的上传内容或来自一个或多个播放列表的视频。 |
guideCategory |
标识 YouTube 根据频道的内容或其他指标(例如受欢迎程度)与频道相关联的类别。指南类别旨在以一种使 YouTube 用户更容易找到他们正在寻找的内容的方式来组织频道。虽然频道可以与一个或多个指南类别相关联,但不能保证它们属于任何指南类别。 |
i18nLanguage |
标识 YouTube 网站支持的应用程序语言。应用程序语言也可以称为 UI 语言。 |
i18nRegion |
标识 YouTube 用户可以选择作为首选内容区域的地理区域。内容区域也可以称为内容区域。 |
playlist |
表示单个 YouTube 播放列表。播放列表是可以按顺序查看并与其他用户共享的视频集合。 |
playlistItem |
标识作为播放列表一部分的资源,例如视频。playlistItem 资源还包含解释如何在播放列表中使用包含的资源的详细信息。 |
search result |
包含有关与 API 请求中指定的搜索参数匹配的 YouTube 视频、频道或播放列表的信息。虽然搜索结果指向唯一可识别的资源,如视频,但它没有自己的持久数据。 |
subscription |
包含有关 YouTube 用户订阅的信息。订阅会在频道中添加新视频或其他用户在 YouTube 上执行多项操作之一(例如上传视频、为视频评分或评论视频)时通知用户。 |
thumbnail |
标识与资源关联的缩略图。 |
video |
代表单个 YouTube 视频。 |
videoCategory |
标识已经或可能与上传的视频相关联的类别。 |
watermark |
标识在播放指定频道的视频期间显示的图像。频道所有者还可以指定图像链接到的目标频道以及确定水印在视频播放期间出现的时间以及可见的时间长度的时间细节。 |
请注意,在许多情况下,资源包含对其他资源的引用。例如,playlistItem
资源的snippet.resourceId.videoId
属性标识视频资源,而该资源又包含有关视频的完整信息。作为另一个例子,搜索结果包含无论是videoId
,playlistId
,或channelId
属性标识特定视频,播放列表或信道资源。
支持的操作
下表显示了 API 支持的最常见方法。某些资源还支持执行更特定于这些资源的功能的其他方法。例如,该videos.rate
方法将用户评分与视频相关联,该thumbnails.set
方法将视频缩略图上传到YouTube并将其与视频相关联。
操作 | |
---|---|
list |
检索 ( GET ) 零个或多个资源的列表。 |
insert |
创建 ( POST ) 一个新资源。 |
update |
修改 ( PUT ) 现有资源以反映请求中的数据。 |
delete |
删除 ( DELETE ) 特定资源。 |
API 当前支持列出每种支持的资源类型的方法,并且它还支持对许多资源的写操作。
下表列出了不同类型资源支持的操作。插入、更新或删除资源的操作始终需要用户授权。在某些情况下,list
方法支持授权和未授权的请求,其中未授权的请求仅检索公共数据,而授权的请求还可以检索有关当前已验证用户的信息或私有的信息。
支持的操作 | ||||
---|---|---|---|---|
list | insert | update | delete | |
activity |
||||
caption |
||||
channel |
||||
channelBanner |
||||
channelSection |
||||
comment |
||||
commentThread |
||||
guideCategory |
||||
i18nLanguage |
||||
i18nRegion |
||||
playlist |
||||
playlistItem |
||||
search result |
||||
subscription |
||||
thumbnail |
||||
video |
||||
videoCategory |
||||
watermark |
配额使用情况
这 YouTube Data API使用配额来确保开发人员按预期使用服务,并且不会创建不公平地降低服务质量或限制他人访问的应用程序。所有 API 请求(包括无效请求)至少会产生一分配额成本。您可以在API Console.
启用 YouTube 数据 API 的项目的默认配额分配为每天 10,000 个单位,足以满足我们绝大多数 API 用户的需求。默认配额可能会发生变化,可帮助我们优化配额分配并以对 API 用户更有意义的方式扩展我们的基础设施。您可以在 API 控制台的配额页面上查看您的配额使用情况。
注意:如果您达到配额限制,您可以通过填写YouTube API 服务的配额延期申请表来申请额外配额。
计算配额使用量
Google 通过为每个请求分配费用来计算您的配额使用情况。不同类型的操作有不同的配额成本。例如:
- 检索资源列表(频道、视频、播放列表)的读取操作通常需要 1 个单位。
- 创建、更新或删除资源的写入操作通常具有成本
50
单位。 - 搜索请求花费
100
单位。 - 视频上传费用为
1600
单位。
该API请求的配额费用表显示每个API方法的配额费用。考虑到这些规则,您可以估计您的应用程序每天可以发送的请求数量,而不会超出您的配额。
部分资源
API 允许并且实际上需要检索部分资源,以便应用程序避免传输、解析和存储不需要的数据。这种方法还确保 API 使用网络,CPU和内存资源更有效。
API 支持两个请求参数,这将在以下部分进行解释,使您能够识别应包含在 API 响应中的资源属性。
part
参数使用方法
该part
参数是任何检索或返回资源的 API 请求的必需参数。该参数标识应包含在 API 响应中的一个或多个顶级(非嵌套)资源属性。例如,一个video
资源具有以下部分:
snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails
所有这些部分都是包含嵌套属性的对象,您可以将这些对象视为 API 服务器可能(或可能不会)检索的元数据字段组。因此,该part
参数要求您选择应用程序实际使用的资源组件。此要求有两个关键目的:
- 它通过防止 API 服务器花费时间检索您的应用程序不使用的元数据字段来减少延迟。
- 它通过减少(或消除)您的应用程序可能检索的不必要数据量来减少带宽使用。
随着时间的推移,随着资源添加更多部分,这些好处只会增加,因为您的应用程序不会请求它不支持的新引入的属性。
fields
参数使用方法
该fields
参数过滤 API 响应,该响应仅包含part
参数值中标识的资源部分,因此响应仅包含一组特定的字段。该fields
参数允许您从 API 响应中删除嵌套属性,从而进一步减少带宽使用。(该part
参数不能用于从响应中过滤嵌套属性。)
以下规则解释了fields
参数值支持的语法,该语法松散地基于XPath 句法:
- 使用逗号分隔的列表 (
fields=a,b
) 选择多个字段。 - 使用星号 (
fields=*
) 作为通配符来标识所有字段。 - 使用括号 (
fields=a(b,c)
) 指定将包含在 API 响应中的一组嵌套属性。 - 使用正斜杠 (
fields=a/b
) 来标识嵌套属性。
在实践中,这些规则通常允许多个不同的fields
参数值检索相同的 API 响应。例如,如果要检索播放列表中每个项目的播放列表项目 ID、标题和位置,可以使用以下任何值:
fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
fields=items(id,snippet/title,snippet/position)
fields=items(id,snippet(title,position))
注意:与所有查询参数值一样,fields
参数值必须经过 URL 编码。为了更好的可读性,本文档中的示例省略了编码。
部分请求示例
下面的示例演示了如何使用part
和fields
参数来确保 API 响应仅包含您的应用程序使用的数据:
- 实施例1点返回,其包括四个部分,以及一个视频资源
kind
和etag
性能。 - 实施例2点返回,其包括两个部分,以及作为视频资源
kind
和etag
性能。 - 示例 3 返回一个包含两部分但排除
kind
和etag
属性的视频资源。 - 示例 4 返回一个视频资源,该资源包括两部分,但不包括
kind
和etag
以及资源snippet
对象中的一些嵌套属性。
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status
Description: This example retrieves avideo
resource and identifies several
resource parts that should be included in the API response.
API response:
{
"kind": "youtube#videoListResponse",
"etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
"videos": [
{
"id": "7lCDEYXw3mM",
"kind": "youtube#video",
"etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
"snippet": {
"publishedAt": "2012-06-20T22:45:24.000Z",
"channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"title": "Google I/O 101: Q&A On Using Google APIs",
"description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
"thumbnails": {
"default": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
},
"medium": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
},
"high": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
}
},
"categoryId": "28"
},
"contentDetails": {
"duration": "PT15M51S",
"aspectRatio": "RATIO_16_9"
},
"statistics": {
"viewCount": "3057",
"likeCount": "25",
"dislikeCount": "0",
"favoriteCount": "17",
"commentCount": "12"
},
"status": {
"uploadStatus": "STATUS_PROCESSED",
"privacyStatus": "PRIVACY_PUBLIC"
}
}
]
}
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics
Description: This example modifies thepart
parameter value so that the
contentDetails
andstatus
properties are not included
in the response.
API response:
{
"kind": "youtube#videoListResponse",
"etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
"videos": [
{
"id": "7lCDEYXw3mM",
"kind": "youtube#video",
"etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
"snippet": {
"publishedAt": "2012-06-20T22:45:24.000Z",
"channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"title": "Google I/O 101: Q&A On Using Google APIs",
"description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
"thumbnails": {
"default": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
},
"medium": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
},
"high": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
}
},
"categoryId": "28"
},
"statistics": {
"viewCount": "3057",
"likeCount": "25",
"dislikeCount": "0",
"favoriteCount": "17",
"commentCount": "12"
}
}
]
}
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics)
Description: This example adds thefields
parameter to remove all
kind
andetag
properties from the API response.
API response:
{
"videos": [
{
"id": "7lCDEYXw3mM",
"snippet": {
"publishedAt": "2012-06-20T22:45:24.000Z",
"channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"title": "Google I/O 101: Q&A On Using Google APIs",
"description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
"thumbnails": {
"default": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
},
"medium": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
},
"high": {
"url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
}
},
"categoryId": "28"
},
"statistics": {
"viewCount": "3057",
"likeCount": "25",
"dislikeCount": "0",
"favoriteCount": "17",
"commentCount": "12"
}
}
]
}
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics
Description: This example modifies thefields
parameter from example 3
so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
,
andcategoryId
properties.
API response:
{
"videos": [
{
"id": "7lCDEYXw3mM",
"snippet": {
"channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"title": "Google I/O 101: Q&A On Using Google APIs",
"categoryId": "28"
},
"statistics": {
"viewCount": "3057",
"likeCount": "25",
"dislikeCount": "0",
"favoriteCount": "17",
"commentCount": "12"
}
}
]
}
优化性能
使用 ETag
ETags,HTTP 协议的标准部分,允许应用程序引用特定 API 资源的特定版本。资源可以是整个提要或该提要中的项目。此功能支持以下用例:
-
缓存和条件检索——您的应用程序可以缓存 API 资源及其 ETag。然后,当您的应用程序再次请求存储的资源时,它会指定与该资源关联的 ETag。如果资源已更改,则 API 会返回修改后的资源以及与该资源版本关联的 ETag。如果资源没有改变,API 会返回 HTTP 304 响应 (
Not Modified
),表示资源没有改变。您的应用程序可以通过以这种方式提供缓存资源来减少延迟和带宽使用。Google API 的客户端库在对 ETag 的支持方面有所不同。例如,JavaScript 客户端库通过包含
If-Match
和 的允许请求标头的白名单来支持 ETagIf-None-Match
。白名单允许正常的浏览器缓存发生,因此如果资源的 ETag 没有改变,则可以从浏览器缓存中提供资源。另一方面,Obj-C 客户端不支持 ETag。 -
防止无意中覆盖更改——ETag 有助于确保多个 API 客户端不会无意中覆盖彼此的更改。更新或删除资源时,您的应用程序可以指定资源的 ETag。如果 ETag 与该资源的最新版本不匹配,则 API 请求将失败。
在您的应用程序中使用 ETag 有几个好处:
- API 可以更快地响应缓存但未更改的资源的请求,从而降低延迟和带宽使用率。
- 您的应用程序不会无意中覆盖从另一个 API 客户端对资源所做的更改。
这 Google APIs Client Library for JavaScript支持If-Match
和If-None-Match
HTTP 请求标头,从而使 ETag 能够在正常浏览器缓存的上下文中工作。
使用 gzip
您还可以通过启用 gzip 压缩来减少每个 API 响应所需的带宽。虽然您的应用程序将需要额外的 CPU 时间来解压缩 API 响应,但消耗较少网络资源的好处通常会超过该成本。
要接收 gzip 编码的响应,您必须做两件事:
- 将
Accept-Encoding
HTTP 请求标头设置为gzip
. - 修改您的用户代理以包含字符串
gzip
。
下面的示例 HTTP 标头展示了启用 gzip 压缩的这些要求:
Accept-Encoding: gzip User-Agent: my program (gzip)