YouTube Data API 概览

简介

本文档适用于想要编写与 YouTube 互动的应用的开发者。它介绍了 YouTube 和 API 本身的基本概念。此外，它还概述了该 API 支持的不同功能。

前期准备

您需要拥有 Google 账号才能访问 Google API 控制台、申请 API 密钥和注册应用。
在 Google Developers Console 中创建项目，并获取授权凭据，以便您的应用可以提交 API 请求。
创建项目后，请确保 YouTube Data API 是您的应用注册使用的服务之一：
1. 前往 API 控制台，然后选择刚刚注册的项目。
2. 访问“已启用的 API”页面。在 API 列表中，确保 YouTube Data API v3 的状态为启用。
如果您的应用所采用的 API 方法需要用户授权，则您可以参阅授权指南，了解如何采用 OAuth 2.0 授权。
选择客户端库，简化 API 执行过程。
熟悉 JSON（JavaScript 对象表示法）数据格式的核心概念。JSON 是一种与语言无关的常见数据格式，可通过简单的文本来表示任意数据结构。如需了解详情，请参阅 json.org。

资源和资源类型

资源是指具有唯一标识符的单个数据实体。下表介绍了您可以使用 API 互动的不同类型的资源。

资源
`activity`	包含有关特定用户在 YouTube 网站上执行的操作的信息。活动 Feed 中报告的用户操作包括对视频评分、分享视频、将视频标记为收藏以及发布频道公告等。
`channel`	包含单个 YouTube 频道的相关信息。
`channelBanner`	用于标识要使用的网址，以将新上传的图片设置为频道的横幅图片。
`channelSection`	包含频道选择展示的一组视频的相关信息。例如，某个版块可以展示频道的最新上传内容、最热门的上传内容或一个或多个播放列表中的视频。
`guideCategory`	用于标识 YouTube 根据频道的内容或其他指标（例如热门程度）与频道相关联的类别。指南类别旨在以一种便于 YouTube 用户查找所需内容的方式整理频道。虽然频道可以与一个或多个节目指南类别相关联，但不能保证频道一定位于某个节目指南类别中。
`i18nLanguage`	用于标识 YouTube 网站支持的应用语言。应用语言也可称为界面语言。
`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 请求（包括无效请求）至少会产生 1 点配额费用。您可以在 API Console 中找到应用可用的配额。

启用 YouTube Data API 的项目的默认配额分配为每天 10,000 个单位，这对于绝大多数 API 用户来说都足够了。默认配额可能会发生变化，有助于我们优化配额分配并扩展基础设施，从而更好地满足 API 用户的需求。您可以在 API 控制台的配额页面上查看配额用量。

注意：如果您达到配额限制，可以填写 YouTube API 服务的配额延期申请表单来申请增加配额。

计算配额使用情况

Google 会为每个请求分配一定费用，从而计算您的配额用量。不同类型的操作具有不同的配额费用。例如：

检索资源（频道、视频、播放列表）列表的读取操作通常需要 1 个单位。
创建、更新或删除资源的写入操作通常需要花费 50 个单位。
一次搜索请求的费用为 100 个单位。
上传视频的费用为 100 个单位。

API 请求的配额费用表格显示了每种 API 方法的配额费用。请谨记这些规则，然后估算您的应用每天可以发送的请求数量，以免超出配额。

部分资源

该 API 允许（实际上是要求）检索部分资源，以便应用避免传输、解析和存储不需要的数据。此方法还可确保 API 更高效地使用网络、CPU 和内存资源。

该 API 支持两个请求参数（将在以下部分中进行说明），可让您确定应在 API 响应中包含的资源属性。

part 参数用于标识应为资源返回的属性组。
fields 参数用于过滤 API 响应，以仅返回所请求资源部分中的特定属性。

如何使用 `part` 参数

对于检索或返回资源的任何 API 请求，part 参数都是必需的。此参数用于标识应包含在 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 参数值也必须采用网址编码。为了便于阅读，本文中的示例省略了编码。

部分请求示例

以下示例展示了如何使用 part 和 fields 参数来确保 API 响应仅包含您的应用使用的数据：

示例 1 返回一个视频资源，其中包含四个部分以及 kind 和 etag 属性。
示例 2 返回一个包含两个部分以及 kind 和 etag 属性的视频资源。
示例 3 返回一个包含两个部分但排除 kind 和 etag 属性的视频资源。
示例 4 返回一个包含两个部分的视频资源，但排除 kind 和 etag 以及资源 snippet 对象中的一些嵌套属性。

示例 1

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video 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"
   }
  }
 ]
}

示例 2

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status 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"
   }
  }
 ]
}

示例 3

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 the fields parameter to remove all
             kind and etag 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"
   }
  }
 ]
}

示例 4

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 the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId 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 资源的特定版本。资源可以是整个 Feed，也可以是该 Feed 中的某个商品。此功能支持以下使用场景：

缓存和条件检索 - 应用可以缓存 API 资源及其 ETag。然后，当您的应用再次请求存储的资源时，它会指定与该资源关联的 ETag。如果资源已更改，API 会返回修改后的资源以及与该资源版本关联的 ETag。如果资源未发生变化，API 会返回 HTTP 304 响应 (Not Modified)，表明资源未发生变化。您的应用可以通过这种方式提供缓存资源，从而缩短延迟时间并减少带宽用量。

Google API 的客户端库在对 ETag 的支持方面有所不同。例如，JavaScript 客户端库通过允许的请求标头的白名单（包含 If-Match 和 If-None-Match）支持 ETag。通过将资源列入许可名单，可以实现正常的浏览器缓存，这样一来，如果资源的 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)

YouTube Data API 概览 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

简介