OpenMetaQuery

注意事项

• 阿里云账号默认拥有开启元数据管理功能的权限。如需通过 RAM 用户开启,请确保 RAM 用户拥有 oss:MetaQuery 权限。

• 同一个 Bucket 重复调用本接口会返回 MetaQueryAlreadyExist 错误。如需修改配置,请先调用 CloseMetaQuery 再重新打开。

• 开启过程是异步的。调用成功后,可通过GetMetaQueryStatus查询当前状态、检索模式与已生效配置。

• 配置消息通知时,需要为 RAM 角色授予访问指定 MNS 主题的权限。

• RouteRule、IndexOptions、DatasetConfig 等高级字段仅在 向量检索 时生效;以 标量检索 调用时携带这些字段会返回 InvalidArgument。

• 开启后 RouteRule 不支持修改。是否启用多 Dataset 路由需要在首次 OpenMetaQuery 时决定;如需变更,只能先 CloseMetaQuery 再重新打开,已索引的元数据会被清空。

• WorkflowParameters 为兼容旧版本的基础工作流开关。后续 AI 内容感知细项不再通过该字段演进,新接入建议使用 DatasetConfig 配置。

请求语法

POST /?metaQuery&action=openMetaQuery&mode=semantic HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

<?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>
  <NotificationAttributes>
    <Notifications>
      <Notification>
        <MNS>your-mns-topic-name</MNS>
      </Notification>
    </Notifications>
    <WithFields>
      <WithField>Insights</WithField>
    </WithFields>
  </NotificationAttributes>
  <DatasetConfig>
    <Insights>
      <Language>zh-Hans</Language>
      <Image>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Image>
      <Video>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Video>
    </Insights>
  </DatasetConfig>
  <IndexOptions>
    <IgnoreObjectDelete>True</IgnoreObjectDelete>
  </IndexOptions>
  <RouteRule>
    <Type>OSSTag</Type>
    <AutoCreateDataset>True</AutoCreateDataset>
    <OSSTagKey>routing-dataset</OSSTagKey>
  </RouteRule>
</MetaQuery>

请求头

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

请求元素

响应头

此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。

示例

请求示例

推荐使用 DatasetConfig 配置新版本内容感知能力:

POST /?metaQuery&action=openMetaQuery&mode=semantic 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>
  <NotificationAttributes>
    <Notifications>
      <Notification>
        <MNS>your-mns-topic-name</MNS>
      </Notification>
    </Notifications>
    <WithFields>
      <WithField>Insights</WithField>
    </WithFields>
  </NotificationAttributes>
  <DatasetConfig>
    <Insights>
      <Language>zh-Hans</Language>
      <Image>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Image>
      <Video>
        <Caption>
          <Enable>True</Enable>
        </Caption>
      </Video>
    </Insights>
  </DatasetConfig>
  <RouteRule>
    <Type>OSSTag</Type>
    <AutoCreateDataset>True</AutoCreateDataset>
    <OSSTagKey>routing-dataset</OSSTagKey>
  </RouteRule>
</MetaQuery>

兼容旧版本的 WorkflowParameters 示例。该方式仅用于存量基础开关,后续新功能不再通过 WorkflowParameters 演进:

POST /?metaQuery&action=openMetaQuery&mode=semantic 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>ImageInsightEnable</Name>
      <Value>True</Value>
    </WorkflowParameter>
    <WorkflowParameter>
      <Name>VideoInsightEnable</Name>
      <Value>True</Value>
    </WorkflowParameter>
  </WorkflowParameters>
</MetaQuery>

返回示例

HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Thu, 17 Apr 2025 13:08:38 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

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",
            "Insights": {
                "Video": {
                    "Caption": "室内角落静景",
                    "Description": "这是一个室内场景,画面分为左右两个视角:左边是一扇带白色窗帘的玻璃门,门外隐约可见模糊的室外景象;右边是一个角落,摆放着一张棕色皮质沙发、一把灰色椅子和一个木质柜子。"
                }
            }
        }
    ],
    "UserData": ""
}

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