调用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 | 检索模式。取值如下:
|
请求元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
MetaQuery | 容器 | 否 | 不涉及 | 元数据查询的容器。 子节点:Filters |
WorkflowParameters | 容器 | 否 | 不涉及 | 工作流参数容器,用于配置与AI 内容感知相关的功能。 |
WorkflowParameter | 容器 | 否 | 不涉及 | 单个工作流参数的容器。 父节点:WorkflowParameters |
Name | 字符串 | 否 | VideoInsightEnable | 工作流参数的名称。
|
Value | 字符串 | 否 | True | 工作流参数的值。
|
Filters | 容器 | 否 | 不涉及 | 过滤条件的容器,支持逻辑运算 AND 和 OR 以及比较运算符,最多允许 5 个 OR 和 4 个 AND。
以下用于筛选出文件大小大于 1024 字节且修改时间晚于2025-06-03T09:20:47.999Z,或者前缀是aa/bb/的文件(YWEvYmIv是aa/bb/的URL safe的Base64编码)
子节点:Filter 父节点:MetaQuery |
Filter | 字符串 | 否 |
| 过滤条件表达式,支持的字段和比较运算符见附录: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 | 整型 |
| 文件大小过滤。 |
|
Filename | 字符串 |
| 文件名过滤。文件名需要经过URL safe的Base64编码。 |
|
FileModifiedTime | 字符串 |
| 文件修改时间过滤,使用RFC3339Nano 时间格式。 |
|
OSSTagging.* | 字符串 |
| 标签过滤。标签的Key和Value都需要URL safe的Base64编码。 |
|