Videos: list

返回与 API 请求参数匹配的视频列表。

配额影响： 调用此方法会消耗 1 个配额单位。

常见应用场景

请求

HTTP 请求

GET https://www.googleapis.com/youtube/v3/videos

参数

下表列出了此查询支持的参数。列出的所有参数都是查询参数。

参数
必需参数
part string
part 参数指定一个或多个 video 资源属性的英文逗号分隔列表，API 响应将包含这些属性。

如果该参数标识的属性包含子属性，则子属性将包含在响应中。例如，在 video 资源中，snippet 属性包含 channelId、title、description、tags 和 categoryId 属性。因此，如果您设置 part=snippet，API 响应将包含所有这些属性。

以下列表包含您可以包含在参数值中的 part 名称：
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
过滤条件 （准确指定以下参数之一）
chart string
chart 参数用于标识您要检索的图表。

可接受的值包括：
id string
id 参数指定要检索的资源的 YouTube 视频 ID 的英文逗号分隔列表。在 video 资源中，id 属性指定视频的 ID。
myRating string

此参数只能在经过适当授权的请求中使用。将此参数的值设置为 like 或 dislike，以指示 API 仅返回经过身份验证的用户喜欢或不喜欢的视频。



API 将返回的结果集限制为最多 1000 个视频。即使响应的 pageInfo.totalResults 属性指示的总数更高，使用 pageToken 参数进行分页也只能检索最近的 1000 个项。



该参数接受以下值：

  • dislike：仅返回经过身份验证的用户不喜欢的视频。
  • like：仅返回经过身份验证的用户喜欢的视频。
可选参数
hl string
hl 参数指示 API 检索 YouTube 网站支持的特定 应用语言的本地化资源元数据。参数值必须是 i18nLanguages.list 方法返回的列表中包含的语言代码。

如果该语言提供了本地化资源详细信息，则资源的 snippet.localized 对象将包含本地化值。但是，如果没有本地化详细信息，snippet.localized 对象将包含资源默认语言的资源详细信息。
maxHeight unsigned integer
maxHeight 参数指定 player.embedHtml 属性中返回的嵌入式播放器的最大高度。您可以使用此参数指定嵌入代码应使用适合您的应用布局的高度，而不是默认尺寸。如果还提供了 maxWidth 参数，则播放器的宽度可能会小于 maxHeight，以避免违反最大宽度。可接受的值介于 72 到 8192（含）之间。
maxResults unsigned integer
maxResults 参数指定结果集中应返回的最大项数。

注意： 此参数支持与 myRating 参数结合使用，但不支持与 id 参数结合使用。可接受的值介于 1 到 50（含）之间。默认值为 5。
maxWidth unsigned integer
maxWidth 参数指定 player.embedHtml 属性中返回的嵌入式播放器的最大宽度。您可以使用此参数指定嵌入代码应使用适合您的应用布局的宽度，而不是默认尺寸。

如果还提供了 maxHeight 参数，则播放器的宽度可能会小于 maxWidth，以避免违反最大高度。可接受的值介于 72 到 8192（含）之间。
onBehalfOfContentOwner string
此参数只能在经过适当授权的请求中使用。注意： 此参数仅供 YouTube 内容合作伙伴使用。

onBehalfOfContentOwner 参数表示请求的授权凭据标识的是代表参数值中指定的内容所有者行事的 YouTube 内容管理系统 用户。此参数适用于拥有和管理许多不同 YouTube 频道的 YouTube 内容合作伙伴。它允许内容所有者进行一次身份验证，即可访问其所有视频和频道数据，而无需为每个频道提供身份验证凭据。用户进行身份验证时使用的 CMS 账号必须与指定的 YouTube 内容所有者相关联。
pageToken string
pageToken 参数用于标识结果集中应返回的特定页面。在 API 响应中，nextPageToken 和 prevPageToken 属性用于标识可以检索的其他页面。

注意： 此参数支持与 myRating 参数结合使用，但不支持与 id 参数结合使用。
regionCode string
regionCode 参数指示 API 选择指定区域中提供的视频图表。此参数只能与 chart 参数结合使用。参数值是 ISO 3166-1 alpha-2 国家/地区代码。
videoCategoryId string
videoCategoryId 参数用于标识应检索图表的 视频类别。此参数只能与 chart 参数结合使用。默认情况下，图表不限于特定类别。默认值为 0。

请求正文

调用此方法时，请勿提供请求正文。

响应

如果成功，此方法将返回采用以下结构的响应正文：

{
  "kind": "youtube#videoListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    video Resource
  ]
}

属性

下表定义了此资源中显示的属性：

属性
kind string
标识 API 资源的类型。该值将为 youtube#videoListResponse。
etag etag
此资源的 ETag。
nextPageToken string
可用作 pageToken 参数值的令牌，用于检索结果集中的下一页。
prevPageToken string
可用作 pageToken 参数值的令牌，用于检索结果集中的上一页。
pageInfo object
The pageInfo 对象封装了结果集的分页信息。
pageInfo.totalResults integer
结果集中的结果总数。
pageInfo.resultsPerPage integer
API 响应中包含的结果数。
items[] list
与请求条件匹配的视频列表。

错误

下表列出了 API 在响应对此方法的调用时可能会返回的出错提示。如需了解详情，请参阅出错提示文档。

错误类型 错误详情 说明
badRequest (400) videoChartNotFound 所请求的视频图表不受支持或不可用。
forbidden (403) forbidden 请求未获得适当授权，无法访问视频文件或处理信息。请注意，fileDetails、processingDetails 和 suggestions 部分仅适用于该视频的所有者。
forbidden (403) forbidden 请求无法访问用户评分信息。出现此错误的原因可能是请求未获得适当授权，无法使用 myRating 参数。
notFound (404) videoNotFound 找不到您尝试检索的视频。检查请求的 id 参数的值，确保其正确无误。

试试看！

使用 APIs Explorer 调用此 API，查看 API 请求和响应。