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:向量检索

请求元素

名称

类型

是否必选

示例值

描述

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/的文件(YWEvYmIvaa/bb/的URL safeBase64编码

<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 safeBase64编码

  • 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 :不在集合中

标签过滤。标签的KeyValue都需要URL safeBase64编码

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