帮你快速理解、总结文档立即下载

搜索文件

最近更新时间:2026-09-30 16:51:33
我的收藏

前期准备

开始操作前,确保您已经完成了 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