开启元数据管理功能并选择检索模式-对象存储(OSS)-阿里云帮助中心

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

注意事项

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

请求语法

POST /?metaQuery&comp=add&mode=basic HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
<?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>
  <NotificationAttributes>
    <Notifications>
        <Notification>
            <MNS>your-mns-topic-name</MNS> // MNS主题名称
        </Notification>
    </Notifications>
    <WithFields>
        <WithField>Insights</WithField> // MNS消息返回的字段，可选值有Insights，不传则不返回这些字段
    </WithFields>
  </NotificationAttributes>
</MetaQuery>

请求头

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

请求元素

名称	类型	是否必选	示例值	描述
mode	字符串	是	basic	检索模式。取值如下： basic（默认值）：标量检索 semantic：向量检索
role	字符串	否	my-oss-role	指定用于访问 OSS 服务的 RAM 角色名称，支持在控制台为角色授予权限，实现安全访问。当请求中填写了 `NotificationAttributes` 时，此参数为必填项。
MetaQuery	容器	否	不涉及	元数据查询的容器。子节点：Filters、NotificationAttributes
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
NotificationAttributes	容器	否	不涉及	消息通知配置容器。用于配置文件索引消息通知相关的功能，在单个文件索引完成时发送消息通知到MNS主题。子节点：Notifications、WithFields 父节点：MetaQuery
Notifications	容器	否	不涉及	消息通知配置容器。子节点：Notification 父节点：NotificationAttributes
Notification	容器	否	不涉及	子节点：MNS 父节点：Notifications
MNS	字符串	否	ipc-test-oss-notification	MNS主题名称。父节点：Notification
WithFields	容器	否	不涉及	消息通知容器，用于配置消息通知返回的字段。子节点：WithField 父节点：NotificationAttributes
WithField	字符串	否	Insights	消息通知返回的字段。取值如下： Insights：AI分析后对该文件的简短描述。父节点：WithFields

响应头

此接口仅涉及公共响应头。更多信息，请参见公共响应头（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>
  <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> //配置文件过滤条件：文件大小大于 1024 字节，且文件修改时间晚于 2025-06-03T09:20:47.999Z 
    <Filter>Filename prefix (YWEvYmIv)</Filter>  //配置文件名前缀过滤条件：前缀为 YWEvYmIv（即 Base64 编码后的路径 a/bb/）
  </Filters>
  <NotificationAttributes>
    <Notifications>
        <Notification>
            <MNS>your-mns-topic-name</MNS> // MNS主题名称
        </Notification>
    </Notifications>
    <WithFields>
        <WithField>Insights</WithField> // MNS消息返回的字段，可选值有Insights，不传则不返回这些字段
    </WithFields>
  </NotificationAttributes>
</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

MNS消息通知格式

配置了消息通知参数时，单个文件索引完成会发送消息通知到MNS主题，消息通知格式如下。

{
      "DatasetName": "your_dataset",
      "RequestId": "EC8CC942-BA82-BC29-BB5E-3F193F9964CE",
      "StartTime": "2026-02-27T19:20:35.190142739+08:00",
      "EndTime": "2026-02-27T19:21:44.021599314+08:00",
      "Success": true,
      "Message": "",
      "Files": [
          {
              "URI": "oss://your_bucket/dir/test.mp4",
              "Error": "",
              "ObjectStatus": "Indexed",
              "SequenceNumber": 4,
              "Insights": {
                  "Video": {
                      "Caption": "室内角落静景",
                      "Description": "这是一个室内场景，画面分为左右两个视角：左边是一扇带白色窗帘的玻璃门，门外隐约可见模糊的室外景象；右边是一个角落，摆放着一张棕色皮质沙发、一把灰色椅子和一个木质柜子——沙发旁停着一辆黑色婴儿车，旁边还有一盆绿植，柜子上则放着一个醒目的黄色球。"
                  }
              }
          }
      ],
      "UserData": ""
  }

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/”