文档中心

对象存储

媒体处理

SearchBySenseFlow

SearchBySenseFlow

功能描述

调用 SearchBySenseFlow 接口，可根据指定 SenseFlow Rule 对已建立索引的桶内对象执行智能检索。

支持文档、图片和视频检索。

支持组合文本查询与结构化过滤条件，并按需返回相关文本片段。

接口会在执行检索前，依次进行如下校验：

Rule 是否存在。

Rule 是否与请求中的桶关联。

Rule 是否已开启所请求的检索类型。

校验通过后使用该 Rule 对应的数据集执行检索。

注意事项

类型	限制说明
权限控制	调用方需拥有 tos:SearchBySenseFlow 权限，授权资源为 trn:tos::<account-id>:senseflow/rule/<rule-id>。
请求参数	请求路径 /v1/senseflow/search 必须填写 RuleId 和 BucketName。 BucketName 必须与 Rule 关联的桶一致。
返回结果	单次最多返回 100 条结果；未指定或指定非正数时，默认返回 10 条；超过 100 时按 100 条处理。仅单一媒体类型检索支持使用 NextToken 翻页；一次请求包含多个 SearchTypes 时，不返回翻页 Token。当 Rule 对应的检索数据集尚不存在时，接口返回 HTTP 200 和空结果，而非 404。

前提条件

调用接口前，必须已创建 SenseFlow Rule，并为 Rule 开启 Search 能力。

SearchTypes 仅支持 doc、image 和 video，且请求中的每种类型都必须已在 Rule 中开启。其中，doc 类型当前仅支持检索 .txt 格式文件。

请求消息样式

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
Authorization	Header	String	是	authorization string	TOS V4 请求签名。
Content-Type	Header	String	是	application/json	请求消息体类型。 Content-Type 取值固定为 application/json。
x-tos-date	Header	String	是	20260818T020000Z	请求时间，参与 TOS V4 签名。
x-tos-security-token	Header	String	否	-	临时 AK/SK 时携带的安全令牌。

请求元素

名称	参数类型	是否必选	示例值	说明
RuleId	String	是	347716754038276096	SenseFlow Rule ID。Rule 必须存在且处于可用状态。
BucketName	String	是	example-bucket	Rule 关联的存储桶名。必须与 Rule 中记录的桶一致。
SearchTypes	Array of String	是	["doc", "image"]	检索的媒体类型。不区分大小写，重复值自动去重，支持类型如下： doc image video
Query	String	否	年度预算报告	自然语言检索文本。可为空，为空时可配合 Filter 执行纯结构化过滤。
Filter	Object	否	-	结构化过滤表达式。常用字段包括 ContentType、FileName、FilePath、MediaType、Description、Caption、TextContent 和 FileModifiedTime。最终支持范围以目标媒体类型生成的索引字段为准。时间字段 CreateTime、FileCreateTime、FileModifiedTime、TosExpiration、ProduceTime 和 CaptureTime 支持以下 Value 格式： Unix 纳秒时间戳字符串。 RFC 3339 或 RFC 3339 Nano 时间字符串，例如 2026-08-18T10:00:00+08:00。
Operation	String	是	-	操作符。支持如下取值：逻辑操作： and、or、not。叶子操作： eq、gt、gte、lt、lte、prefix、match_phrase、exist。父节点：Filter
Field	String	条件必选	-	叶子条件的索引字段，可用字段取决于媒体类型及底层 Search 索引。父节点：Filter
Value	String	条件必选	-	叶子条件的比较值。对外接口统一接收字符串，并在调用 Search 前按字段进行类型转换。父节点：Filter
SubFilters	Array of Object	条件必选	-	子过滤条件。逻辑操作使用该字段组合多个条件。父节点：Filter
Limit	Integer	否	10	返回结果数量，取值范围为 1 ～ 100，默认值为 10。
NextToken	String	否	next-token	翻页标记，取上一次响应中的 next_token。仅支持单一媒体类型检索。
WithHighlights	Boolean	否	true	是否返回相关文本片段，默认值为 false，取值如下： true false

响应消息头

该请求返回 TOS 公共响应消息头，包括 x-tos-request-id 和 x-tos-id-2，详情请参见公共参数。

响应元素

名称	参数类型	示例值	说明
RequestId	String	85630782fcf6b2f26a82fcf6-ac13ee7*******	本次请求的 TOS Request ID。
items	Array	-	检索结果列表。无匹配结果时为空或不返回。
object_key	String	docs/2026-budget.pdf	对象 Key。父节点：items
media_type	String	doc	结果媒体类型，取值如下： doc image video 父节点：items
content_type	String	application/pdf	对象 Content-Type。父节点：items
size	Integer	1048576	对象大小，单位为字节。父节点：items
last_modified_time_unix	Integer	1786969335	对象最后修改时间，Unix 秒级时间戳。父节点：items
highlights	Array of String	2026 年度预算报告，包含各部门预算明细……	相关文本片段，仅在 WithHighlights=true 时返回。最多从正文、Caption 和 Description 中返回 3 段，每段最大约 4 KiB。父节点：items
description	String	2026 年度预算报告	对象的检索描述信息。
next_token	String	next-token	下一页标记，仅单一媒体类型检索可能返回。
Scope	Object	-	Rule 当前生效范围。该字段为尽力返回，读取失败时不影响检索结果，响应中可能不包含该字段。
ScopeType	String	prefix	Rule 范围类型。父节点：Scope
ScopeExpr	String	docs/	Rule 范围表达式，例如对象 Key 前缀。父节点：Scope
ObjectSetNameList	Array of String	-	Rule 关联的 ObjectSet 名称列表。父节点：Scope

请求示例

按文本和文件类型检索文档

跨图片和视频检索

响应示例

错误码

该接口常见错误码如下：

HTTP 状态码	错误码	典型错误信息	说明
400	InvalidRequest	rule id is required	未填写 RuleId。
400	InvalidRequest	bucket name is required	通过 /v1/senseflow/search 调用时未填写 BucketName。
400	InvalidRequest	SearchTypes is required	未填写有效的 SearchTypes。
400	InvalidRequest	SearchTypes must be one of doc, image, video	SearchTypes 包含不支持的媒体类型。
400	InvalidRequest	rule does not belong to bucket	BucketName 与 Rule 关联的桶不一致。
400	InvalidRequest	capability_not_enabled	Rule 未开启请求指定的检索类型。
400	InvalidRequest	next_token is only supported for single media type search.	多媒体类型检索携带了 NextToken。
403	AccessDenied	Access Denied	调用方无 tos:SearchBySenseFlow 权限，或账号不在功能开放范围内。
404	NoSuchKey	senseflow rule not found	指定 Rule 不存在。
500	InternalError	search failed	检索服务或内部依赖调用失败。

最近更新时间：2026.09.16 10:40:05

这个页面对您有帮助吗？

有用

有用

无用

无用