前期准备
开始操作前,确保您已经完成了 SDK 初始化。如果您还没有初始化 SDK,请先参考快速入门文档完成。
注意事项:
本接口 QPS 使用上限为 10,不可用于业务的高频操作页面(如空间首页列表查询),如有更大 QPS 需求请提工单联系腾讯云智能媒资托管团队。
本接口(含 type=filename 基础检索)需开通白名单后使用,未开通时返回 HTTP 4xx(错误信息通常含
metainsight query is not enabled);type=filecontent 全文检索还需额外开通全文索引能力(同属白名单范畴),未开通时返回 HTTP 4xx(错误信息通常含 space does not support file content search)。搜索目录与文件 - 基本检索(MI)
功能说明:
SearchFs 实现搜索目录与文件功能,支持
type=filename(按文件名命中)和 type=filecontent(按文件正文内容全文检索)两种子模式,并支持按关键字、文件类型、文件大小、修改时间等多种条件进行搜索,支持分页(排序字段当前版本暂不支持,传入不报错但实际无效)。使用示例:
type=filename(默认,按文件名检索)
ctx := context.Background()searchRequest := client.SearchFsRequest{Keywords: []string{"test", "example"},InExtnames: []string{".jpg", ".pdf"},FileTypes: []string{"file"},MinFileSize: client.PtrInt32(1024),MaxFileSize: client.PtrInt32(10485760),}searchRequest.SetType("filename")searchRequest.SetScope("/documents")resp, httpRes, err := apiClient.SearchAPI.SearchFs(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").SearchFsRequest(searchRequest).UserId("user-id").Limit(20).WithFavoriteStatus(1).WithInode(1).Execute()if err != nil {panic(err)}for _, item := range resp.Contents {if item.Name != nil {fmt.Printf("Found: %s (%s)\\n", *item.Name, *item.Type)}if item.Inode != nil {fmt.Printf(" Inode: %s\\n", *item.Inode)}}// 如果返回了 nextMarker,说明还有更多结果,可携带继续搜索if resp.NextMarker != nil {nextResp, _, err := apiClient.SearchAPI.SearchFs(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").Marker(*resp.NextMarker).Execute()if err != nil {panic(err)}fmt.Printf("Additional results: %d items\\n", len(nextResp.Contents))}
type=filecontent(全文关键字检索)
注意:
此功能需联系腾讯云开通白名单后方可使用。
ctx := context.Background()searchRequest := client.SearchFsRequest{Keywords: []string{"会议纪要"},}searchRequest.SetType("filecontent")resp, httpRes, err := apiClient.SearchAPI.SearchFs(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").SearchFsRequest(searchRequest).UserId("user-id").Limit(10).WithInode(1).Execute()if err != nil {panic(err)}for _, item := range resp.Contents {if item.Name != nil {fmt.Printf("Found: %s\\n", *item.Name)}if item.Text != nil {fmt.Printf(" Text snippet: %s (page %d)\\n", *item.Text, *item.TextPage)}if item.ContentHighlight != nil && item.ContentHighlight.Fragments != nil {fmt.Printf(" Highlight: %v\\n", item.ContentHighlight.Fragments)}}
参数说明:
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | string | 是 |
accessToken | 访问令牌 | string | 否 |
searchFsRequest | 搜索请求对象,包含详细的搜索条件 | SearchFsRequest | 否 |
userId | 用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份 | string | 否 |
marker | 用于顺序列出分页的标识,建议将 marker 放入请求体中传入 | string | 否 |
limit | 用于顺序列出分页时本地列出的项目数限制,取值范围 [1,100],默认值为 20 | int32 | 否 |
withFavoriteStatus | 0 或 1,是否返回收藏状态;仅 type=filename 生效,type=filecontent 下即使传入 1 也不会返回 isFavorite | int32 | 否 |
withInode | 0 或 1,是否返回文件或目录 ID(inode) | int32 | 否 |
SearchFsRequest 对象说明
字段 | 类型 | 是否必填 | 说明 |
type | string | 否 | 搜索子模式,取值 filename(基础检索,按文件名命中)或 filecontent(全文关键字检索,按文件正文内容命中);默认 filename |
keywords | []string | 否 | 搜索关键字,字符串数组(元素间为"或"关系),数组长度上限 100;type=filename 下按文件名命中,不做停用词过滤;type=filecontent 下按文件正文内容全文检索,服务端会自动过滤停用词 |
scope | string | 否 | 搜索范围,指定搜索的目录,如搜索根目录可指定为空字符串、"/"或不指定该字段;type=filecontent 下路径匹配能力有限,建议不填 |
inExtnames | []string | 否 | 包含的搜索文件后缀,或的关系,数组长度上限 20,单元素 rune 长度上限 10 |
excludeExtnames | []string | 否 | 不包含的搜索文件后缀,与的关系,数组长度上限 20,单元素 rune 长度上限 10 |
fileTypes | []string | 否 | 文件类型,取值 all/dir/file/symlink,或的关系 |
minFileSize | int32 | 否 | 搜索文件大小范围最小值,单位 Byte |
maxFileSize | int32 | 否 | 搜索文件大小范围最大值,单位 Byte |
modificationTimeStart | time.Time | 否 | 搜索更新时间范围起始,RFC3339 格式;若起始时间晚于结束时间返回 HTTP 4xx |
modificationTimeEnd | time.Time | 否 | 搜索更新时间范围结束,RFC3339 格式 |
orderBy | string | 否 | 排序字段;当前版本暂不支持按字段排序,字段传入不会报错但实际无效 |
orderByType | string | 否 | 排序方式,升序为 asc,降序为 desc;当前版本暂不支持,字段传入不会报错但实际无效 |
labels | []string | 否 | 简易文件标签,或的关系,数组长度上限 20,单元素 rune 长度上限 32 |
categories | []string | 否 | 文件自定义分类信息,或的关系,数组长度上限 20,取值必须属于该媒体库已声明的类目集合 |
返回值说明:
HTTP 状态码:200
搜索成功。
响应字段说明
字段 | 说明 | 类型 |
nextMarker | 用于获取后续页的分页标识,没有更多结果时不返回该字段 | String |
contents | 搜索结果,可能为空数组 | Array |
Contents 数组元素说明
字段 | 说明 | 类型 | 备注 |
type | 条目类型:dir-目录或相簿;file-文件;image-图片,仅用于媒体类型媒体库;video-视频,仅用于媒体类型媒体库;symlink-符号链接;virtual-虚拟文件 | String | |
inode | 文件或目录 ID | String | 需带 withInode=1 才会返回 |
name | 目录或相簿名或文件名 | String | |
creationTime | 创建时间或上传时间(ISO 8601) | String | |
modificationTime | 最近修改时间 | String | |
contentType | 媒体类型 | String | 仅 file 类型返回 |
versionId | 版本号 | Integer | 仅 file 类型返回 |
size | 文件大小,字符串格式避免数字精度问题 | String | 仅 file 类型返回 |
isFavorite | 是否被收藏 | Boolean | 仅 type=filename 且 withFavoriteStatus=1 时返回 |
eTag | 文件 ETag | String | 仅 file 类型返回 |
crc64 | 文件的 CRC64-ECMA182 校验值 | String | 仅 file 类型返回 |
metaData | 文件元数据信息 | Object | 仅 file 类型返回 |
userId | 创建/更新者用户 ID | String | |
previewByDoc | 是否可通过 WPS 预览 | Boolean | |
previewByCI | 是否可通过万象预览 | Boolean | |
previewAsIcon | 是否可使用预览图当做 icon | Boolean | |
fileType | 文件类别,如 doc/image/video/archive 等 | String | |
labels | 简易文件标签,字符串数组 | Array[String] | |
category | 自定义文件分类,比如 image、video、doc 等 | String | |
localCreationTime | 文件对应的本地创建时间 | DateTime | |
localModificationTime | 文件对应的本地修改时间 | DateTime | |
text | 命中的正文片段 | String | 仅 type=filecontent 返回 |
textPage | 命中片段所在文档页码(整数);PDF/DOCX/PPTX 等有分页的文档才有意义,纯文本类文档为 0 | Integer | 仅 type=filecontent 返回 |
contentHighlight | 服务端侧的正文高亮片段 | Object | 仅 type=filecontent 返回 |
ContentHighlight 字段说明
字段 | 说明 | 类型 |
fragments | 高亮片段数组,关键词用 <em> 标签包裹 | Array[String] |
搜索文件 - 混合检索(MI)
功能说明:
SearchAI 实现 AI 语义搜索功能,支持
type=text(文本语义搜索)和 type=pic(图片语义搜索)两种模式。此接口为高级搜索能力,使用前需联系 SMH 开发团队申请开通白名单
文本语义搜索(type=text)会对文件正文内容进行语义级别的匹配,返回与搜索语句语义相关的文档片段
图片语义搜索(type=pic)会对图片内容进行语义级别的匹配,返回与搜索语句语义相关的图片
keywords 为字符串类型(不是数组),服务端会自动做空白与特殊字符清洗,清洗后 rune 长度上限 60
若清洗后 keywords 为空,HTTP 200 返回空 contents
接口 QPS 上限与具体白名单套餐挂钩,以实际开通配额为准
注意:
此功能需联系腾讯云开通白名单后方可使用。
使用示例:
type=text(文本语义搜索)
ctx := context.Background()now := time.Now()startTime := now.AddDate(0, -1, 0)searchAIRequest := client.SearchAIRequest{Type: "text",Keywords: "项目文档",FileTypes: []string{"file"},InExtnames: []string{".txt", ".doc", ".docx"},ExcludeExtnames: []string{".tmp"},Categories: []string{"document"},Labels: []string{"重要"},ModificationTimeStart: &startTime,ModificationTimeEnd: &now,}resp, httpRes, err := apiClient.SearchAPI.SearchAI(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").UserId("user-id").SearchAIRequest(searchAIRequest).Limit(10).Execute()if err != nil {panic(err)}for _, item := range resp.Contents {if item.Inode != nil {fmt.Printf("Inode: %s, Score: %d\\n", *item.Inode, *item.Score)}if item.Text != nil {fmt.Printf("Text: %s (page %d)\\n", *item.Text, *item.TextPage)}}
type=pic(图片语义搜索)
ctx := context.Background()searchAIRequest := client.SearchAIRequest{Type: "pic",Keywords: "猫 动物",}resp, httpRes, err := apiClient.SearchAPI.SearchAI(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").UserId("user-id").SearchAIRequest(searchAIRequest).Limit(20).Execute()if err != nil {panic(err)}for _, item := range resp.Contents {fmt.Printf("Inode: %s, Score: %d\\n", *item.Inode, *item.Score)}
参数说明:
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | string | 是 |
accessToken | 访问令牌 | string | 否 |
searchAIRequest | AI 搜索请求对象,包含详细的搜索条件 | SearchAIRequest | 是 |
userId | 用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份 | string | 否 |
limit | 用于顺序列出分页时本地列出的项目数限制 | int32 | 否 |
SearchAIRequest 对象说明
字段 | 类型 | 是否必填 | 说明 |
type | string | 是 | 子模式,取值 text(文本语义搜索)或 pic(图片语义搜索);非法值返回 HTTP 4xx |
keywords | string | 是 | 搜索语句,字符串(不是数组),服务端会自动做空白与特殊字符清洗,清洗后 rune 长度上限 60;若清洗后为空则 HTTP 200 返回空 contents |
fileTypes | []string | 否 | 文件类型,字符串数组 |
inExtnames | []string | 否 | 包含的后缀,字符串数组,数组长度上限 20,单元素 rune 长度上限 10 |
excludeExtnames | []string | 否 | 不包含的后缀,字符串数组,数组长度上限 20,单元素 rune 长度上限 10 |
categories | []string | 否 | 文件自定义分类,字符串数组,数组长度上限 20,取值必须属于该媒体库已声明的类目集合 |
labels | []string | 否 | 简易文件标签,字符串数组,数组长度上限 20,单元素 rune 长度上限 32 |
modificationTimeStart | time.Time | 否 | 搜索更新时间范围起始,RFC3339 格式;若起始时间晚于结束时间返回 HTTP 4xx |
modificationTimeEnd | time.Time | 否 | 搜索更新时间范围结束,RFC3339 格式 |
返回值说明:
HTTP 状态码:200
搜索成功。
响应字段说明
字段 | 说明 | 类型 |
contents | 命中结果数组,数组长度 ≤ 本次请求的 limit | Array |
Contents 数组元素说明
字段 | 说明 | 类型 | 备注 |
inode | 命中文件的 inode | String | 两种 type 均返回 |
score | 服务端计算的语义匹配得分,整数,分数越高越相关 | Integer | 两种 type 均返回 |
text | 命中文档片段(字符串) | String | 仅 type=text 返回 |
textPage | 命中片段所在页码(整数);PDF/DOCX/PPTX 等有分页的文档才有意义,纯文本类文档为 0 | Integer | 仅 type=text 返回 |
搜索聚合统计
功能说明:
SearchFsStats 实现搜索聚合统计功能,对搜索结果进行聚合分析,支持按文件后缀、分类、大小、媒体类型、用户 ID、文件名、文件类型等字段进行分组、计数、去重、求和、最小值、最大值、平均值等聚合操作。
使用示例:
基本聚合统计(按文件后缀分组)
ctx := context.Background()aggregations := []client.SearchFsStatsRequestAggregationsInner{{Field: "extName",Operation: "group",},{Field: "size",Operation: "sum",},}scope := "/"searchFsStatsRequest := client.SearchFsStatsRequest{Keywords: []string{"项目"},Scope: &scope,Aggregations: aggregations,}resp, httpRes, err := apiClient.SearchAPI.SearchFsStats(ctx, "your-library-id", "your-space-id").AccessToken("your-access-token").UserId("user-id").SearchFsStatsRequest(searchFsStatsRequest).Execute()if err != nil {panic(err)}fmt.Printf("Is truncated: %v\\n", *resp.IsTruncated)for _, agg := range resp.Aggregations {fmt.Printf("Field: %s, Operation: %s\\n", *agg.Field, *agg.Operation)if agg.Value != nil {fmt.Printf(" Value: %f\\n", *agg.Value)}if agg.Groups != nil {for _, group := range agg.Groups {fmt.Printf(" Group: %s, Count: %d\\n", *group.Value, *group.Count)}}}
参数说明:
参数名 | 参数描述 | 类型 | 是否必填 |
libraryId | 媒体库 ID | string | 是 |
spaceId | 空间 ID,如果媒体库为单租户模式,则该参数固定为连字符(-);如果媒体库为多租户模式,则必须指定该参数 | string | 是 |
accessToken | 访问令牌 | string | 否 |
searchFsStatsRequest | 搜索聚合统计请求对象,包含搜索条件和聚合配置 | SearchFsStatsRequest | 是 |
userId | 用户身份识别,当访问令牌对应的权限为管理员权限且申请访问令牌时的用户身份识别为空时用来临时指定用户身份 | string | 否 |
SearchFsStatsRequest 对象说明
字段 | 类型 | 是否必填 | 说明 |
keywords | []string | 否 | 搜索关键字,字符串数组,或的关系 |
scope | string | 否 | 搜索范围,指定搜索的目录,如搜索根目录可指定为空字符串、"/"或不指定该字段 |
inExtnames | []string | 否 | 搜索文件后缀,字符串数组,或的关系 |
excludeExtnames | []string | 否 | 不包含的搜索文件后缀,字符串数组,与的关系 |
fileTypes | []string | 否 | 文件类型,字符串数组,file:文件,dir:目录,symlink:符号链接,或的关系 |
minFileSize | int32 | 否 | 搜索文件大小范围最小值,整数,单位 Byte |
maxFileSize | int32 | 否 | 搜索文件大小范围最大值,整数,单位 Byte |
modificationTimeStart | time.Time | 否 | 搜索更新时间范围起始,时间戳字符串,与时区无关 |
modificationTimeEnd | time.Time | 否 | 搜索更新时间范围结束,时间戳字符串,与时区无关 |
labels | []string | 否 | 简易文件标签,字符串数组,或的关系 |
categories | []string | 否 | 文件自定义分类信息,字符串数组,或的关系 |
aggregations | []SearchFsStatsRequestAggregationsInner | 是 | 聚合统计数组,最多 5 个聚合项 |
Aggregations 聚合项字段说明
字段 | 类型 | 是否必填 | 说明 |
field | string | 是 | 聚合字段名 |
operation | string | 是 | 聚合操作 |
subAggregations | []SubAggregationsInner | 否 | 子聚合数组,仅当 operation 为 group 时有效,最多 3 个子聚合项,子聚合不支持 group |
SubAggregations 子聚合项字段说明
字段 | 类型 | 是否必填 | 说明 |
field | string | 是 | 子聚合字段名 |
operation | string | 是 | 子聚合操作,不支持 group |
支持的聚合字段
字段 | 说明 | 支持的操作 |
extName | 文件后缀 | group, count, distinct |
category | 文件分类 | group, count, distinct |
size | 文件大小(Byte) | count, distinct, sum, min, max, average |
contentType | 媒体类型 | group, count, distinct |
userId | 创建/更新者用户 ID | group, count, distinct |
name | 文件名 | count, distinct |
fileType | 文件类型(内部数值) | group, count, distinct |
支持的聚合操作
操作 | 说明 |
group | 分组聚合,按字段值分组 |
count | 计数,统计匹配的文档数 |
distinct | 去重计数,统计字段的不同值数量 |
sum | 求和(仅适用于数值类型字段,如 size) |
min | 最小值(仅适用于数值类型字段) |
max | 最大值(仅适用于数值类型字段) |
average | 平均值(仅适用于数值类型字段) |
返回值说明:
HTTP 状态码:200
搜索聚合统计成功。
响应示例:
{"isTruncated": false,"aggregations": [{"field": "extName","operation": "group","groups": [{"value": ".pdf","count": 120,"subAggregations": [{"field": "size","operation": "sum","value": 1073741824}]},{"value": ".docx","count": 85}]},{"field": "size","operation": "sum","value": 5368709120}]}
响应字段说明
字段 | 说明 | 类型 |
isTruncated | 分组数据是否被截断,当实际分组数量超过最大限制(默认2000)时返回 true | Boolean |
aggregations | 聚合统计结果数组,与请求中的 aggregations 一一对应 | Array |
Aggregations 响应字段说明
字段 | 说明 | 类型 |
field | 聚合字段名 | String |
operation | 聚合操作名 | String |
value | 当 operation 为 sum、min、max、average、count、distinct 时返回,表示聚合计算结果 | Float |
groups | 当 operation 为 group 时返回,分组结果数组 | Array |
Groups 分组字段说明
字段 | 说明 | 类型 |
value | 分组的键值(如后缀名 ".pdf"、分类名 "image" 等) | String |
count | 该分组下的文档数量 | Integer |
subAggregations | 子聚合结果,当请求中指定了子聚合时返回 | Array |
SubAggregations 子聚合响应字段说明
字段 | 说明 | 类型 |
field | 子聚合字段名 | String |
operation | 子聚合操作名 | String |
value | 子聚合计算结果 | Float |