API 请求示例

此页面显示了对 YouTube Data API 的示例请求。您可以使用 YouTube Data API 来检索和操纵 YouTube 资源，例如视频、频道和播放列表。每个示例均链接到并填充 Google API Explorer，以便您执行示例并查看响应。

如需了解如何使用 YouTube Data API 上传内容，请参阅可续传上传。

概览

为了清楚起见，本页面上的示例显示了每个请求的独特元素，并简要介绍了处理 Data API 请求 (https://www.googleapis.com/youtube/v3) 的主机的基准网址。如果要在示例之外提出该请求，您需要提供完整网址。

例如，以下是此页面上显示的请求示例：

GET {base-URL}/channels?part=contentDetails
                       &mine=true

此请求的完整网址为：

GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails
                                                  &mine=true

有些请求会检索只有 YouTube 频道的所有者才能访问的数据，例如订阅者列表。这些请求要求频道所有者授予 Google API Explorer 代表他们执行 YouTube Data API 请求的权利。（如需详细了解如何授权访问私有通道数据，请参阅实现 OAuth 2.0 身份验证）。关联到 API Explorer 后，点击使用 OAuth 2.0 授权请求按钮。此步骤可授权 API Explorer 代表所有者发出请求。您还需要选择授权范围，以指定 API Explorer 可以执行的请求类型。

每个请求的响应都是 YouTube 资源的 JSON 表示形式。请求中的 part 参数指定响应中要包含资源的哪些部分。参数用于标识响应中应包含的一个或多个顶级（非嵌套）资源属性。例如，视频资源的部分内容如下：

• 摘要
• contentDetails
• 球员
• 统计学
• status

所有这些部分都是包含嵌套属性的对象，您可以将这些对象视为 API 服务器可能（也可能不会）检索的元数据字段组。因此，part 参数要求您选择应用实际使用的资源组件。如需了解详情，请参阅 YouTube Data API 使用入门。

检索频道信息

此请求使用 channels.list 方法来检索属于经过身份验证的用户的频道的详细信息。

GET {base_URL}/channels?part=contentDetails
                       &mine=true

此请求的响应包含经过身份验证的用户的频道的频道 ID 和 contentDetails。contentDetails 包含与频道相关联的多个由系统生成的播放列表。很多后续请求都需要用到频道 ID 或某个播放列表 ID，因此请务必记录这些请求。

{
  "id": {CHANNEL_ID},
  "kind": "youtube#channel",
  "etag": etag,
  "contentDetails": {
    "relatedPlaylists": {
      "likes": {LIKES_PLAYLIST_ID},
      "favorites": {FAVORITES_PLAYLIST_ID},
      "uploads": {UPLOADS_PLAYLIST_ID},
      "watchHistory": {WATCHHISTORY_PLAYLIST_ID},
      "watchLater": {WATCHLATER_PLAYLIST_ID}
    },
    "googlePlusUserId": string
  },
}

上传的视频和系统生成的播放列表

YouTube 会将所有上传的视频添加到与该频道相关联的播放列表中。如需获取已上传视频的列表，您可以查询在上面显示的针对频道信息的响应中返回的“uploads”播放列表，并使用 playlistItems.list 方法检索该播放列表中的视频。

在 Google API Explorer 中执行以下示例请求之前，将 {UPLOADS_PLAYLIST_ID} 替换为之前请求中的播放列表 ID。

GET {base_URL}/playlistItems?part=contentDetails
                            &playlistId={UPLOADS_PLAYLIST_ID}

请注意，每个返回项的 "id" 值是其播放列表项 ID。播放列表项的视频 ID 是 contentDetails 部分中的 videoId。

您可以利用以上请求检索用户收藏的内容、顶过的内容、观看记录或稍后观看列表，只需替换频道信息响应中相应的播放列表 ID 即可。

用户创建的播放列表

此请求使用 playlists.list 方法来检索与经过身份验证的频道相关联的播放列表。请注意，此请求不会检索频道信息中包含的系统生成的播放列表（上传内容、watchHistory 等）。只检索用户创建的播放列表。

GET {base_URL}/playlists?part=snippet
                        &mine=true

获得播放列表 ID 后，您就可以使用上一部分中显示的请求检索播放列表中的内容。

您可以在未进行身份验证的情况下请求有关频道公开播放列表的信息。在提交未经身份验证的请求时，您需要添加 key 参数，以指定发出请求的应用的唯一 API 密钥。例如，此请求会检索与 GoogleDevelopers 频道相关联的播放列表。

GET {base_URL}/playlists?part=snippet
                        &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw
                        &key={YOUR_API_KEY}

检索订阅

subscription 资源定义了 YouTube 用户（订阅者）与频道之间的关系。subscriptions.list 方法可检索特定频道的订阅者或特定用户的订阅，具体取决于您在请求中包含的参数。

频道订阅人数

此请求会检索经过身份验证的频道的订阅者列表。

GET {base_URL}/subscriptions?part=snippet
                            &mySubscribers=true

用户订阅

列出订阅者订阅的频道的方法 (subscriptions.list) 也可用于列出用户订阅的频道。此请求使用 mine 参数来检索经过身份验证的用户订阅的 YouTube 频道的列表。

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

检索用户活动

activity 资源包含有关特定频道或用户在 YouTube 上执行的操作（例如上传视频、订阅频道等）的信息。activities.list 方法可检索与请求条件相符的频道或用户相关联的操作。例如，您可以检索与特定频道、用户的订阅或用户的自定义 YouTube 首页相关联的操作。

某个时间段内的活动

此请求检索通过身份验证的用户在 2013 年 4 月执行的所有操作。

GET {base_URL}/activities?part=snippet,contentDetails
                         &mine=true
                         &publishedAfter=2013-04-01T00%3A00%3A00Z
                         &publishedBefore=2013-05-01T00%3A00%3A00Z

首页活动

此请求会检索在经过身份验证的用户的 YouTube 首页上显示的自定义活动 Feed。 

GET {base_URL}/activities?part=snippet,contentDetails
                         &home=true

要获取 YouTube 视频和频道的观看统计信息、热门程度指标和受众特征信息，您可以使用 YouTube Analytics API。API 请求示例页面显示了如何从 YouTube 数据分析中检索常见报告。

搜索

借助 search.list 方法，您可以搜索符合指定条件的 YouTube 视频、频道或播放列表。您可以根据视频属性、关键字或主题（或这些条件的组合）进行搜索，还可以根据创建日期、观看次数或评分等因素对结果进行排序。

与其他 YouTube Data API 请求一样，search.list 方法会返回 YouTube 资源的 JSON 表示法。不过，与其他 YouTube 资源不同，搜索结果不是具有唯一 ID 的持久对象。

许多请求会搜索公开的内容，因此不需要身份验证。在下方示例中，只有第一个广告素材需要身份验证，因为它明确要求提供“my”视频。在提交未经身份验证的请求时，您需要添加 key 参数，以指定您的应用的唯一 API 密钥。

我的观看次数最多的视频

此请求会检索所有经过身份验证的用户的视频，并按观看次数降序列出这些视频。

GET {base_URL}/search?part=snippet
                     &forMine=true
                     &order=viewCount
                     &type=video

可嵌入的高清视频

此请求会搜索具有特定属性的视频，即可嵌入其他网站的高清视频。结果按评分降序排列。

GET {base_URL}/search?part=snippet
                     &order=rating
                     &type=video
                     &videoDefinition=high
                     &videoEmbeddable=true
                     &key={YOUR_API_KEY}

与特定主题有关的视频

此请求对 YouTube 视频 API 中包含字幕的视频执行关键字搜索。

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

基于主题的搜索

搜索特定主题的视频的更复杂方式是使用 Freebase 主题，而不是关键字。YouTube 频道和视频资源均包含 topicDetails 对象，其中包含与资源相关联的 Freebase 主题 ID 列表。基于主题的搜索比关键字搜索更加智能，因为 Freebase 主题代表现实世界概念或事物的所有方面。

如需使用 Freebase 主题进行搜索，您首先需要使用 Freebase API 检索主题 ID。此请求返回与 Python 的 Freebase 主题（主题 ID 为 /m/05z1_）关联的视频。

GET {base_URL}/search?part=snippet
                     &topicId=/m/05z1_
                     &type=video
                     &key={YOUR_API_KEY}

搜索播放列表或频道

搜索并不仅限于视频。您还可以搜索播放列表或频道。此请求检索与关键字“足球”匹配的播放列表。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

如果您想找到足球频道，只需更改 type 参数即可。

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=channel
                     &key={YOUR_API_KEY}

如果您想要观看所有与足球相关的内容（频道、播放列表和视频），可以进行全局搜索。如果您省略 type 参数，则请求会检索所有类型的内容

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &key={YOUR_API_KEY}

创建和更新资源

到目前为止，我们看到的请求都使用 HTTP GET 方法检索 YouTube 数据。YouTube Data API 还提供了一些使用 HTTP POST 来创建或更新 YouTube 资源（例如视频、播放列表或频道）的方法。以下请求提供了示例。

POST 方法包含一个 Request body，这是正在创建或更新的资源的 JSON 表示法。您可以在 Google API Explorer 中使用交互式工具创建 JSON 表示法。

创建订阅

此请求会为经过身份验证的用户订阅 GoogleDevelopers 频道。换句话说，它会创建一个订阅资源。

POST {base_URL}/subscriptions?part=snippet
 Request body:
  {
    'snippet': {
      'resourceId': {
        'kind': 'youtube#channel',
        'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' 
       }
     }
  }

创建播放列表

此请求会创建一个新的公开播放列表。

POST {base_URL}/playlists?part=snippet
 Request body:
  {
    'snippet': {
      'title': 'New playlist', 
      'description': 'Sample playlist for Data API',
     }
  }

向播放列表添加视频

创建播放列表后，我们来向其添加一个视频。此请求会在播放列表 ('position': 0) 的开头添加视频。

POST {base_URL}/playlistItems?part=snippet
  Request body:
  {
    'snippet': {
      'playlistId': '{PLAYLIST_ID}', 
      'resourceId': {
          'kind': 'youtube#video',
          'videoId': '{VIDEO_ID}'
        }
     'position': 0
      }
   }