Search: list
bookmark_border
返回与 API 请求中指定的查询参数匹配的搜索结果集合。默认情况下,搜索结果集会标识匹配的 video
、channel
和 playlist
资源,但您也可以将查询配置为仅检索特定类型的资源。
对配额的影响:调用此方法的配额费用为 100 个单元。
常见使用场景
请求
HTTP 请求
GET https://www.googleapis.com/youtube/v3/search
参数
下表列出了此查询支持的参数。列出的所有参数都是查询参数。
参数 | ||
---|---|---|
必需参数 | ||
part | string part 参数指定一个逗号分隔列表,其中包含 API 响应将包含的一个或多个 search 资源属性。将参数值设为 snippet 。 | |
过滤条件(指定以下参数中的 0 个或 1 个) | ||
forContentOwner | boolean 此参数只能在适当授权的请求中使用,并且专用于 YouTube 内容合作伙伴。 forContentOwner 参数用于限制搜索,以便仅检索由 onBehalfOfContentOwner 参数标识的内容所有者所拥有的视频。如果 forContentOwner 设置为 true,请求还必须满足以下要求:
| |
forDeveloper | boolean 此参数只能在正确授权的请求中使用。 forDeveloper 参数用于将搜索限制为仅检索通过开发者的应用或网站上传的视频。API 服务器使用请求的授权凭据标识开发者。forDeveloper 参数可以与 q 参数等可选搜索参数结合使用。对于此功能,系统会自动使用 Google Developers Console 中与开发者的应用相关联的项目编号标记上传的视频。 随后,如果搜索请求将 forDeveloper 参数设置为 true ,API 服务器会使用该请求的授权凭据来识别开发者。因此,开发者可以将搜索结果范围限定为通过开发者自己的应用或网站上传的视频,而无法仅显示通过其他应用或网站上传的视频。 | |
forMine | boolean 此参数只能在正确授权的请求中使用。 forMine 参数用于将搜索限制为仅检索由经过身份验证的用户拥有的视频。如果将此参数设置为 true ,则 type 参数的值也必须设置为 video 。此外,无法在同一个请求中设置以下任何其他参数:videoDefinition 、videoDimension 、videoDuration 、videoEmbeddable 、videoLicense 、videoPaidProductPlacement 、videoSyndicated 和 videoType 。 | |
可选参数 | ||
channelId | string channelId 参数表示 API 响应应仅包含该频道创建的资源。注意:如果您的请求指定了 channelId 参数的值并将 type 参数值设置为 video ,但并未设置 forContentOwner 、forDeveloper 或 forMine 过滤条件之一,则搜索结果最多只能包含 500 个视频。 | |
channelType | string channelType 参数可让您将搜索范围限制为特定类型的频道。可接受的值包括:
| |
eventType | string eventType 参数将搜索限制为广播事件。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
location | string location 参数与 locationRadius 参数结合使用可以定义圆形地理区域,还会将搜索范围限制为在其元数据中指定了该区域内地理位置的视频。参数值是一个字符串,用于指定纬度/经度坐标,例如 (37.42307,-122.08427 )。
location 形参指定了值,但没有为 locationRadius 形参指定值,则 API 会返回错误。注意:如果您为此参数指定了值,还必须将 type 参数的值设为 video 。 | |
locationRadius | string locationRadius 参数与 location 参数搭配使用时,定义了圆形地理区域。此参数值必须是浮点数加测量单位。有效的计量单位包括 m 、km 、ft 和 mi 。例如,有效的参数值包括 1500m 、5km 、10000ft 和 0.75mi 。该 API 不支持大于 1,000 公里的 locationRadius 参数值。注意:如需了解详情,请参阅 location 参数的定义。 | |
maxResults | unsigned integer maxResults 参数指定结果集中应返回的商品数量上限。可接受的值包括0 到50 (含 0 和 10000)。默认值为 5 。 | |
onBehalfOfContentOwner | string 此参数只能在正确授权的请求中使用。注意:此参数仅适用于 YouTube 内容合作伙伴。 onBehalfOfContentOwner 参数用于指明该请求的授权凭据会标识代表参数值中指定的内容所有者执行操作的 YouTube 内容管理系统用户。此参数适用于拥有和管理众多不同 YouTube 频道的 YouTube 内容合作伙伴。它可让内容所有者在一次身份验证后获得访问其所有视频和频道数据的权限,而无需为每个频道提供身份验证凭据。用户进行身份验证时所用的 CMS 账号必须与指定的 YouTube 内容所有者相关联。 | |
order | string order 参数指定在 API 响应中对资源进行排序的方法。默认值为 relevance 。可接受的值包括:
| |
pageToken | string pageToken 参数用于标识结果集中应返回的特定网页。在 API 响应中,nextPageToken 和 prevPageToken 属性用于标识可检索到的其他页面。 | |
publishedAfter | datetime publishedAfter 参数表示 API 响应应仅包含指定时间当天或之后创建的资源。该值是 RFC 3339 格式的日期时间值 (1970-01-01T00:00:00Z)。 | |
publishedBefore | datetime publishedBefore 参数表示 API 响应应仅包含在指定时间之前或时间创建的资源。该值是 RFC 3339 格式的日期时间值 (1970-01-01T00:00:00Z)。 | |
q | string q 参数指定了要搜索的查询字词。您的请求还可以使用布尔运算符 NOT ( - ) 和 OR (| ) 运算符排除视频或查找与多个搜索字词中的一个相关联的视频。例如,如需搜索与“船舶”或“帆船”匹配的视频,请将 q 参数值设置为 boating|sailing 。同样,如需搜索与“划船”或“帆船”匹配但与“钓鱼”不匹配的视频,请将 q 参数值设为 boating|sailing -fishing 。请注意,竖线字符在 API 请求中发送时必须经过网址转义。竖线字符的网址转义值为 %7C 。 | |
regionCode | string regionCode 参数用于指示 API 返回可在指定国家/地区观看的视频的搜索结果。此参数值是 ISO 3166-1 alpha-2 国家/地区代码。 | |
relevanceLanguage | string relevanceLanguage 参数用于指示 API 返回与指定语言最相关的搜索结果。此参数值通常为两个字母的 ISO 639-1 语言代码。不过,您应针对简体中文使用 zh-Hans 值,针对繁体中文使用 zh-Hant 值。请注意,如果其他语言的结果与搜索查询字词高度相关,则仍会返回这些结果。 | |
safeSearch | string safeSearch 参数用于指明搜索结果是否应同时包含受限内容和标准内容。可接受的值为:
| |
topicId | string topicId 参数表示 API 响应应仅包含与指定主题相关联的资源。该值用于标识 Freebase 主题 ID。重要提示:由于 Freebase 和 Freebase API 已被弃用,自 2017 年 2 月 27 日起, topicId 参数的工作方式开始有所不同。当时,YouTube 开始支持一小部分精选主题 ID,因此您只能使用这组较小的 ID 作为此参数的值。查看自 2017 年 2 月 15 日起支持的主题 ID | |
type | string type 参数将搜索查询限制为仅检索特定类型的资源。该值是以英文逗号分隔的资源类型列表。默认值为 video,channel,playlist 。可接受的值包括:
| |
videoCaption | string videoCaption 参数用于指明 API 是否应根据视频搜索结果是否具有字幕来过滤视频搜索结果。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoCategoryId | string videoCategoryId 参数会根据视频的类别过滤视频搜索结果。如果您为此参数指定了值,则还必须将 type 参数的值设置为 video 。 | |
videoDefinition | string videoDefinition 参数可让您将搜索结果限制为仅包含高清 (HD) 或标清 (SD) 视频。您能以至少 720p 的分辨率播放高清视频,不过,您也可以使用更高的分辨率,例如 1080p。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoDimension | string 您可以使用 videoDimension 参数将搜索限制为仅检索 2D 或 3D 视频。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoDuration | string videoDuration 参数会根据时长来过滤视频搜索结果。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoEmbeddable | string 您可以使用 videoEmbeddable 参数将搜索范围限定为可以嵌入到网页中的视频。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoLicense | string videoLicense 参数用于过滤搜索结果,使其仅包含具有特定许可的视频。YouTube 允许视频上传者选择为每个视频附加知识共享许可或标准 YouTube 许可。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoPaidProductPlacement | string videoPaidProductPlacement 参数会过滤搜索结果,以便仅包含创作者标示为提供付费宣传内容的视频。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
| |
videoSyndicated | string videoSyndicated 参数可让您将搜索范围限定为可在 youtube.com 以外的地方播放的视频。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值包括:
| |
videoType | string videoType 参数可让您将搜索范围限定为特定类型的视频。如果您为此参数指定值,则还必须将 type 参数的值设为 video 。可接受的值为:
|
请求正文
调用此方法时,请勿提供请求正文。
响应
如果成功,此方法将返回采用以下结构的响应正文:
{ "kind": "youtube#searchListResponse", "etag": etag, "nextPageToken": string, "prevPageToken": string, "regionCode": string, "pageInfo": { "totalResults": integer, "resultsPerPage": integer }, "items": [ search Resource ] }
属性
下表定义了搜索结果中显示的属性:
属性 | |
---|---|
kind | string 标识 API 资源的类型。其值为 youtube#searchListResponse 。 |
etag | etag 此资源的 Etag。 |
nextPageToken | string 可用作 pageToken 参数值的令牌,用于检索结果集中的下一页。 |
prevPageToken | string 可用作 pageToken 参数值的令牌,用于检索结果集中的上一页。 |
regionCode | string 搜索查询所用的地区代码。属性值是标识区域的两个字母 ISO 国家/地区代码。 i18nRegions.list 方法会返回支持的区域列表。默认值为 US 。如果指定了不受支持的区域,YouTube 可能仍会选择其他区域(而非默认值)来处理查询。 |
pageInfo | object pageInfo 对象可封装结果集的分页信息。 |
pageInfo.totalResults | integer 结果集中的结果总数。请注意,该值是近似值,可能并不代表确切值。此外,最大值为 1,000,000。 您不应使用此值创建分页链接。而应改用 nextPageToken 和 prevPageToken 属性值来确定是否显示分页链接。 |
pageInfo.resultsPerPage | integer API 响应中包含的结果数量。 |
items[] | list 与搜索条件匹配的结果列表。 |
示例
注意:以下代码示例可能并未涵盖所有受支持的编程语言。有关受支持语言的列表,请参阅客户端库文档。
此函数用于搜索与关键字“dogs”相关的视频。搜索结果的视频 ID 和标题会记录到 Apps 脚本的日志中。
请注意,此示例将结果限制为 25 个。如需返回更多结果,请传递其他参数(如 https://developers.google.com/youtube/v3/docs/search/list)
function searchByKeyword() { var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25}); for(var i in results.items) { var item = results.items[i]; Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title); } }
错误
下表列出了 API 在响应对此方法的调用时可能会返回的错误消息。如需了解详情,请参阅错误消息文档。
错误类型 | 错误详情 | 说明 |
---|---|---|
badRequest (400) | invalidChannelId | channelId 参数指定的频道 ID 无效。 |
badRequest (400) | invalidLocation | location 和/或 locationRadius 参数值格式不正确。 |
badRequest (400) | invalidRelevanceLanguage | relevanceLanguage 参数值的格式不正确。 |
badRequest (400) | invalidSearchFilter | 请求包含无效的搜索过滤条件和/或限制组合。请注意,如果您将 forContentOwner 或 forMine 参数设置为 true ,则必须将 type 参数设置为 video 。如果您为 eventType 、videoCaption 、videoCategoryId 、videoDefinition 、videoDimension 、videoDuration 、videoEmbeddable 、videoLicense 、videoSyndicated 或 videoType 形参设置了值,则还必须将 type 形参设为 video 。 |