YouTubeData API参考 Videos: list

Videos: list

bookmark_border

返回与 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` 参数用于标识您要检索的图表。可接受的值包括： `mostPopular` – 返回指定内容区域和视频类别中最热门的视频。
`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` 参数的值，确保其正确无误。

YouTubeData API参考 Videos: list

Videos: list

常见使用场景

请求

HTTP 请求

参数

请求正文

响应

属性

错误

悦读