Videos: list

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

对配额的影响：调用此方法的配额费用为 1 个单位。

常见使用场景

请求

HTTP 请求

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

参数

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

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

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

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

可接受的值包括：
id string
id 参数指定要检索的资源的 YouTube 视频 ID 列表（以英文逗号分隔）。在 video 资源中，id 属性用于指定视频的 ID。
myRating string
此参数只能在正确授权的请求中使用。将此参数的值设为 like 或 dislike，以指示 API 仅返回经过身份验证的用户顶过或踩过的视频。

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

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

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

如果还提供了 maxHeight 参数，播放器可能会比 maxWidth 窄一点，以免超出最大高度。可接受的值包括72到8192（含 0 和 10000）。
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
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 请求和响应。