YouTube Data API 概览

简介

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

前期准备

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

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

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

   1. 前往 Cloud 控制台，然后选择您刚刚注册的项目。
   2. 访问“已启用的 API”页面。 确保 YouTube Data API 位于已启用 API 的列表中。如果不在，请打开 API 库并启用该 API。

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

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

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

资源和资源类型

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

请注意，在许多情况下，资源包含对其他资源的引用。例如，playlistItem 资源的 snippet.resourceId.videoId 属性标识一个视频资源，该资源反过来又包含有关该视频的完整信息。再举一个例子，搜索结果包含 videoId、playlistId 或 channelId 属性，用于标识特定的视频、播放列表或频道资源。

支持的操作

下表显示了 API 支持的最常用方法。某些资源还支持其他方法，这些方法执行的功能更特定于这些资源。例如，videos.rate 方法将用户评分与视频关联，而 thumbnails.set 方法将视频缩略图上传到 YouTube 并将其与视频关联。

API 目前支持列出每个受支持资源类型的方法，并且还支持许多资源的写入操作。

下表标识了不同类型的资源支持的操作。插入、更新或删除资源的操作始终需要用户授权。在某些情况下，list 方法同时支持已授权和未经授权的请求，其中未经授权的请求仅检索公开数据，而已授权的请求还可以检索有关当前经过身份验证的用户或当前经过身份验证的用户的私有信息。

配额用量

YouTube Data API 使用配额来确保开发者按预期使用该服务，并且不会创建不公平地降低服务质量或限制他人访问权限的应用。所有 API 请求（包括无效请求）至少会产生 1 点配额费用。您可以在 API Console 中找到可供您的应用使用的配额。

启用 YouTube Data API 的项目默认配额分配为 100 个 search.list 调用、100 个 videos.insert 调用，以及所有其他端点每天共 10,000 个单位。默认配额可能会发生变化，有助于我们优化配额分配并扩缩我们的基础架构，从而对 API 用户更有意义。您可以在 API 控制台的“配额”页面上查看配额用量。

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

计算配额用量

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

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

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 对象中的一些嵌套属性。

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

优化性能

Accept-Encoding: gzip
User-Agent: my program (gzip)