YouTube Data API 概览

简介

本文档适用于希望编写与 YouTube 交互的应用程序的开发者。介绍了 YouTube 的基本概念和 API 本身。此外，它还概述了 API 支持的不同函数。

前期准备

  1. 您需要 Google 账号才能访问 Google API 控制台、请求 API 密钥以及注册应用。

  2. 在 Google Developers Console 中创建一个项目并获取授权凭据，以便您的应用能够提交 API 请求。

  3. 创建项目后，请确保 YouTube 数据 API 是您的应用注册要使用的服务之一：

    1. 转到 API 控制台，选择您刚刚注册的项目。
    2. 访问“已启用的 API”页面。 在 API 列表中，确保 YouTube Data API v3 的状态为启用。

  4. 如果您的应用所采用的 API 方法需要用户授权，则您可以参阅授权指南，了解如何采用 OAuth 2.0 授权。

  5. 选择客户端库，简化 API 执行过程。

  6. 熟悉 JSON（JavaScript 对象表示法）数据格式的核心概念。JSON 是一种与语言无关的常见数据格式，可通过简单的文本方式来表示任意数据结构。如需了解详情，请参阅 json.org。

资源和资源类型

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

资源
activity 包含特定用户在 YouTube 网站上所执行操作的相关信息。活动供稿中报告的用户操作包括评分视频、分享视频、将视频加入收藏和发布频道公告等。
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 请求（包括无效请求）都至少产生单点配额费用。您可以在 API Console 中找到您的应用可用的配额。

启用 YouTube Data API 的项目默认每天分配 10,000 个单元的配额，这个配额足以满足绝大多数 API 用户的需求。默认配额可能会发生变化，可帮助我们优化配额分配，并以对 API 用户更有意义的方式扩缩我们的基础架构。您可以在 API 控制台的配额页面上查看您的配额使用情况。

注意：如果您达到配额上限，可以通过以下方式申请更多配额： 完成配额扩展任务 YouTube API 服务的申请表单。

计算配额用量

Google 通过为每个请求分配费用来计算您的配额用量。不同类型的 操作具有不同的配额费用。例如：

  • 读取操作通常用于检索频道、视频和播放列表等资源 价格为 1 个单位。
  • 创建、更新或删除资源的写入操作通常会产生费用 50 个单位。
  • 一个搜索请求消耗 100 个单元。
  • 一次视频上传需要花费 1600 个单元。

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. 示例 1 返回一个视频资源，其中包含四个部分以及 kind 和 etag 属性。
  2. 示例 2 返回一个包含两部分以及 kind 和 etag 属性的视频资源。
  3. 示例 3 返回的视频资源包含两个部分，但不包含 kind 和 etag 属性。
  4. 示例 4 返回一个视频资源，其中包含两部分，但排除了 kind 和 etag，以及资源的 snippet 对象中的一些嵌套属性。
。 <ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph>
示例 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)