調用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 | 檢索模式。取值如下：
|
role | 字串 | 否 | my-oss-role | 指定用於訪問 OSS 服務的 RAM 角色名稱，支援在控制台為角色授予許可權，實現安全訪問。當請求中填寫了 |
MetaQuery | 容器 | 否 | 不涉及 | 中繼資料查詢的容器。 子節點：Filters、NotificationAttributes |
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 |
NotificationAttributes | 容器 | 否 | 不涉及 | 訊息通知配置容器。用於設定檔索引訊息通知相關的功能，在單個檔案索引完成時發送訊息通知到MNS主題。 子節點：Notifications、WithFields 父節點：MetaQuery |
Notifications | 容器 | 否 | 不涉及 | 訊息通知配置容器。 子節點：Notification 父節點：NotificationAttributes |
Notification | 容器 | 否 | 不涉及 | 子節點：MNS 父節點：Notifications |
MNS | 字串 | 否 | ipc-test-oss-notification | MNS主題名稱。 父節點：Notification |
WithFields | 容器 | 否 | 不涉及 | 訊息通知容器，用於配置訊息通知返回的欄位。 子節點：WithField 父節點：NotificationAttributes |
WithField | 字串 | 否 | Insights | 訊息通知返回的欄位。取值如下：
父節點：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（即 Base 64 編碼後的路徑 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: 544MNS訊息通知格式
配置了訊息通知參數時，單個檔案索引完成會發送訊息通知到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 | 整型 |
| 檔案大小過濾。 |
|
Filename | 字串 |
| 檔案名稱過濾。檔案名稱需要經過URL safe的Base64編碼。 |
|
FileModifiedTime | 字串 |
| 檔案修改時間過濾，使用RFC3339Nano 時間格式。 |
|
OSSTagging.* | 字串 |
| 標籤過濾。標籤的Key和Value都需要URL safe的Base64編碼。 |
|