使用OpenMetaQuery开启元数据管理并选择检索模式-对象存储-阿里云

调用OpenMetaQuery接口为存储空间（Bucket）开启元数据管理功能并选择检索模式。开启元数据管理功能并选择检索模式后，OSS会为Bucket创建元数据索引库并为Bucket中的所有文件（Object）建立元数据索引。元数据索引库创建完成后，OSS会继续对Bucket中新增文件进行准实时的增量追踪扫描并为增量文件建立元数据索引。

注意事项

阿里云账号默认拥有开启元数据管理功能的权限。如果您希望通过RAM用户开启元数据管理功能，需确保RAM用户拥有oss:OpenMetaQuery权限。具体操作，请参见为RAM用户授予自定义的权限策略。
关于数据索引的更多信息，请参见数据索引。

请求语法

POST /?metaQuery&comp=add&mode=basic HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 13:08:38 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<MetaQuery>
  <WorkflowParameters>
   <WorkflowParameter>
	<Name>VideoInsightEnable</Name> 
	<Value>True</Value>  //是否开启视频内容感知
   </WorkflowParameter>
   <WorkflowParameter>
	<Name>ImageInsightEnable</Name>
	<Value>True</Value>  //是否开启图片内容感知
   </WorkflowParameter>
 </WorkflowParameters>
  <Filters>
    <Filter>Size > 1024, FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter> //配置文件过滤条件
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
</MetaQuery>

请求头

名称

类型

是否必选

示例值

描述

mode

字符串

是

basic

检索模式。取值如下：

basic（默认值）：标量检索
semantic：向量检索

role

字符串

否

my-oss-role

指定用于访问 OSS 服务的 RAM 角色名称，支持在控制台为角色授予权限，实现安全访问。

请求元素

名称	类型	是否必选	示例值	描述
MetaQuery	容器	否	不涉及	元数据查询的容器。子节点：Filters
WorkflowParameters	容器	否	不涉及	工作流参数容器，用于配置与AI 内容感知相关的功能。
WorkflowParameter	容器	否	不涉及	单个工作流参数的容器。父节点：WorkflowParameters
Name	字符串	否	VideoInsightEnable	工作流参数的名称。 VideoInsightEnable：视频内容感知开关。 ImageInsightEnable：图片内容感知开关。
Value	字符串	否	True	工作流参数的值。 True：开启 False：关闭
Filters	容器	否	不涉及	过滤条件的容器，支持逻辑运算 AND 和 OR 以及比较运算符，最多允许 5 个 OR 和 4 个 AND。每个`Filter`表达式之间为 OR 关系。单个`Filter`表达式中多个条件之间使用英文逗号（`,`）分隔，表示 AND 关系。以下用于筛选出文件大小大于 1024 字节且修改时间晚于2025-06-03T09:20:47.999Z，或者前缀是aa/bb/的文件（YWEvYmIv是aa/bb/的URL safe的Base64编码） `<Filters> <Filter>Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter> <Filter>Filename prefix (YWEvYmIv)</Filter> </Filters>` 子节点：Filter 父节点：MetaQuery
Filter	字符串	否	`Size > 1024,FileModifiedTime > 2025-06-03T09:20:47.999Z`	过滤条件表达式，支持的字段和比较运算符见附录：Filters字段支持的变量和操作符。示例值表示：筛选出文件大小大于 1024 字节且修改时间晚于2025-06-03T09:20:47.999Z的文件。父节点：Filters

响应头

此接口仅涉及公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

示例

请求示例

POST /?metaQuery&comp=add&mode=basic HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 13:08:38 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<MetaQuery>
  <Filters>
    <Filter>Size > 1024, FileModifiedTime > 2025-06-03T09:20:47.999Z</Filter>
    <Filter>Filename prefix (YWEvYmIv)</Filter>
  </Filters>
</MetaQuery>

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
x-oss-server-time: 544

SDK

本接口对应的各语言SDK如下：

命令行工具ossutil

OpenMetaQuery接口所对应的ossutil命令，请参见open-meta-query。

附录：Filters字段支持的变量和操作符

名称	类型	支持的操作符	描述	过滤示例值
Size	整型	`=` ：等于，等同于`==` `!=` ：不等于 `>` ：大于 `>=` ：大于等于 `<` ：小于 `<=` ：小于等于	文件大小过滤。	`Size > 9` ：文件大小大于9
Filename	字符串	`=` ：等于，等同于`==` `!=` ：不等于 `prefix` ：包含前缀 `suffix` ：包含后缀 `in` ：在集合中 `notin` ：不在集合中	文件名过滤。文件名需要经过URL safe的Base64编码。	`Filename == YWEvYmIvY2MuanBn` ：文件名为 aa/bb/cc.jpg `Filename != YWEvYmIvY2MuanBn`：文件名不为 aa/bb/cc.jpg `Filename notin (YWEvYmIvY2MuanBn, YWEvYmIvZGQuanBn)`：文件名不为 aa/bb/cc.jpg 或 aa/bb/dd.jpg `Filename in (YWEvYmIvY2MuanBn, YWEvYmIvZGQuanBn`：文件名为 aa/bb/cc.jpg 或aa/bb/dd.jpg。 `Filename prefix (YWEvYmIv, YWEvY2Mv)`：文件名前缀为“aa/bb/”或“aa/cc/” `Filename suffix (LmpwZw, LnBuZw)`：文件名后缀为“.jpg”或“.png”
FileModifiedTime	字符串	`=` ：等于，等同于`==` `!=` ：不等于 `>` ：大于 `>=` ：大于等于 `<` ：小于 `<=` ：小于等于	文件修改时间过滤，使用RFC3339Nano 时间格式。	`FileModifiedTime > 2025-06-03T09:20:47.999Z` ：文件时间大于2025-06-03T09:20:47.999Z
OSSTagging.*	字符串	`=` ：等于，等同于`==` `!=` ：不等于 `!` ：不存在key `exists` ：存在key `prefix` ：包含前缀 `suffix` ：包含后缀 `in` ：在集合中 `notin` ：不在集合中	标签过滤。标签的Key和Value都需要URL safe的Base64编码。	`OSSTagging.Zm9v == YWJj`：存在标签 Key 为“foo”且其 Value 为 “abc” `!OSSTagging.Zm9v`：不存在标签 Key 为“foo” `OSSTagging.Zm9v`：存在标签 Key 为 “foo” 说明无需使用 exists 关键字，仅填写 Key 即可 `OSSTagging.Zm9v in (YWJj, ZWZn)`：存在标签 Key 为 “foo”，Value 值为 “abc” 或“efg” `OSSTagging.Zm9v prefix (YWEvYmIv, YWEvY2Mv)`：存在标签 Key 为 “foo”，且其 Value 的前缀为 “aa/bb/” 或 “aa/cc/”