調用DoMetaQuery介面查詢滿足指定條件的檔案(Object),並按照指定欄位和排序方式列出檔案資訊。您也可以通過Query的嵌套使用實現複雜查詢,以及通過彙總操作實現對不同欄位的值進行統計和分析。
注意事項
要查詢滿足指定條件的檔案,您必須有oss:DoMetaQuery
許可權。具體操作,請參見為RAM使用者授權自訂的權限原則。
請求文法
POST /?metaQuery&comp=query HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
<NextToken></NextToken>
<MaxResults>5</MaxResults>
<Query>{"Field": "Size","Value": "1048576","Operation": "gt"}</Query>
<Sort>Size</Sort>
<Order>asc</Order>
<Aggregations>
<Aggregation>
<Field>Size</Field>
<Operation>sum</Operation>
</Aggregation>
<Aggregation>
<Field>Size</Field>
<Operation>max</Operation>
</Aggregation>
</Aggregations>
</MetaQuery>
要求標頭
此介面僅涉及公用要求標頭。更多資訊,請參見公用要求標頭(Common Request Headers)。
請求元素
名稱 | 類型 | 是否必選 | 樣本值 | 描述 |
MetaQuery | 容器 | 是 | 不涉及 | 查詢條件的容器。 子節點:NextToken、MaxResults、Query、Sort、Order、Aggregations |
NextToken | 字串 | 否 | MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw**** | 當Object總數大於設定的MaxResults時,用於翻頁的token。 從NextToken開始按字典序返回Object資訊列表。 第一次調用此介面時,設定此欄位為空白。 父節點:MetaQuery |
MaxResults | 整型 | 否 | 5 | 返回Object的最大個數,取值範圍為0~100。 不設定此參數或者設定為0時,則預設值為100。 父節點:MetaQuery |
Query | 字串 | 是 | {"Field": "Size","Value": "1048576","Operation": "gt"} | 查詢條件。包括如下選項:
關於Query樣本的更多資訊,請參見Query樣本。 父節點:MetaQuery |
Sort | 字串 | 否 | Size | 對指定欄位排序。關於支援排序的欄位列表,請參見附錄:欄位和操作符的支援列表。 父節點:MetaQuery |
Order | 字串 | 否 | asc | 排序方式。取值範圍如下:
父節點:MetaQuery |
Aggregations | 容器 | 否 | 不涉及 | 彙總操作資訊的容器。 子節點:Aggregation 父節點:MetaQuery |
Aggregation | 容器 | 否 | 不涉及 | 單個彙總操作資訊的容器。 子節點:Field、Operation 父節點:Aggregations |
Field | 字串 | 否 | Size | 欄位名稱。關於支援的欄位以及欄位對操作符的支援情況,請參見附錄:欄位和操作符的支援列表。 父節點:Aggregation |
Operation | 字串 | 否 | sum | 彙總操作中的操作符。取值範圍如下:
父節點:Aggregation |
回應標頭
此介面僅涉及公用回應標頭。更多資訊,請參見公用回應標頭(Common Response Headers)。
響應元素
名稱 | 類型 | 樣本值 | 描述 |
MetaQuery | 容器 | 不涉及 | 查詢結果的容器。 子節點:NextToken、Files、Aggregations |
NextToken | 字串 | MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw**** | 當Object總數大於設定的MaxResults時,用於翻頁的token。 下一次列出Object資訊時以此值為NextToken,將未返回的結果返回。 當Object未全部返回時,此參數才有值。 父節點:MetaQuery |
Files | 容器 | 不涉及 | Object資訊的容器。 子節點:File 父節點:MetaQuery |
File | 容器 | 不涉及 | 單個Object資訊的容器。 子節點:Filename、Size、FileModifiedTime、OSSObjectType、OSSStorageClass、ObjectACL、ETag、OSSTaggingCount、OSSTagging、OSSUserMeta、OSSCRC64、ServerSideEncryption 父節點:Files |
Filename | 字串 | exampleobject.txt | Object完整路徑。 父節點:File |
Size | 整型 | 120 | Object大小。單位為位元組。 父節點:File |
FileModifiedTime | 字串 | 2021-06-29T15:04:05.000000000Z07:00 | Object的最近一次修改時間,遵循RFC 3339標準格式。 父節點:File |
OSSObjectType | 字串 | Normal | Object的類型。取值範圍如下:
父節點:File |
OSSStorageClass | 字串 | Standard | Object的儲存類型。取值範圍如下:
父節點:File |
ObjectACL | 字串 | default | Object的存取權限。取值範圍如下:
父節點:File |
ETag | 字串 | "fba9dede5f27731c9771645a3986****" | Object產生時會建立相應的ETag ,ETag用於標識一個Object的內容。
說明 ETag值可以用於檢查Object內容是否發生變化。不建議使用ETag作為Object內容的MD5來校正資料完整性。 父節點:File |
OSSTaggingCount | 整型 | 2 | Object的標籤個數。 父節點:File |
OSSTagging | 容器 | 不涉及 | 標籤資訊的容器。 子節點:Tagging 父節點:File |
Tagging | 容器 | 不涉及 | 單個標籤資訊的容器。 子節點:Key、Value 父節點:OSSTagging |
Key | 字串 | owner | 標籤或者使用者自訂中繼資料的Key。 使用者自訂中繼資料必須以 父節點:Tagging、UserMeta |
Value | 字串 | John | 標籤或者使用者自訂中繼資料的Value。 父節點:Tagging、UserMeta |
OSSUserMeta | 容器 | 不涉及 | 使用者自訂中繼資料的容器。 子節點:UserMeta 父節點:File |
UserMeta | 容器 | 不涉及 | 單個使用者自訂中繼資料的容器。 子節點:Key、Value 父節點:OSSUserMeta |
OSSCRC64 | 字串 | 4858A48BD1466884 | Object的64位CRC值。該64位CRC根據ECMA-182標準計算得出。 |
ServerSideEncryption | 字串 | AES256 | OSS建立檔案時的伺服器端加密編碼演算法。取值範圍為AES256。 父節點:File |
ServerSideEncryptionCustomerAlgorithm | 字串 | SM4 | 使用者在本地用戶端加密檔案時使用的加密編碼演算法。 父節點:File |
Aggregations | 容器 | 不涉及 | 彙總操作資訊的容器。 子節點:Field、Operation、Operation、Value、Groups 父節點:MetaQuery |
Field | 字串 | Size | 欄位名稱。 父節點:Aggregations |
Operation | 字串 | sum | 彙總操作符。 父節點:Aggregations |
Value | 浮點數 | 200 | 彙總操作的結果值。 父節點:Aggregations |
Groups | 容器 | 不涉及 | 分組彙總的結果清單。 子節點:Value、Count 父節點:Aggregations |
Value | 字串 | 100 | 分組彙總的值。 父節點:Groups |
Count | 整型 | 5 | 分組彙總的總個數。 父節點:Groups |
樣本
請求樣本
POST /?metaQuery&comp=query HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Mon, 26 Jul 2021 13:08:38 GMT
Authorization: OSS qn6q**************:77Dv****************
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
<NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw****</NextToken>
<MaxResults>5</MaxResults>
<Query>{"Field": "Size","Value": "1048576","Operation": "gt"}</Query>
<Sort>Size</Sort>
<Order>asc</Order>
<Aggregations>
<Aggregation>
<Field>Size</Field>
<Operation>sum</Operation>
</Aggregation>
<Aggregation>
<Field>Size</Field>
<Operation>max</Operation>
</Aggregation>
</Aggregations>
</MetaQuery>
響應樣本
HTTP/1.1 200 OK
x-oss-request-id: 5C1B138A109F4E405B2D****
Date: Mon, 26 Jul 2021 13:08:38 GMT
Content-Length: 118
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
<NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw****</NextToken>
<Files>
<File>
<Filename>exampleobject.txt</Filename>
<Size>120</Size>
<FileModifiedTime>2021-06-29T15:04:05.000000000Z07:00</FileModifiedTime>
<OSSObjectType>Normal</OSSObjectType>
<OSSStorageClass>Standard</OSSStorageClass>
<ObjectACL>default</ObjectACL>
<ETag>"fba9dede5f27731c9771645a3986****"</ETag>
<OSSCRC64>4858A48BD1466884</OSSCRC64>
<OSSTaggingCount>2</OSSTaggingCount>
<OSSTagging>
<Tagging>
<Key>owner</Key>
<Value>John</Value>
</Tagging>
<Tagging>
<Key>type</Key>
<Value>document</Value>
</Tagging>
</OSSTagging>
<OSSUserMeta>
<UserMeta>
<Key>x-oss-meta-location</Key>
<Value>hangzhou</Value>
</UserMeta>
</OSSUserMeta>
</File>
</Files>
</MetaQuery>
Query樣本
Query支援嵌套使用,您可以通過Query的嵌套構建複雜的查詢條件,精確查詢到所需內容。
如果要搜尋名稱為exampleobject.txt且大小小於1000位元組的檔案,則Query填寫樣本如下:
{ "SubQueries":[ { "Field":"Filename", "Value": "exampleobject.txt", "Operation":"eq" }, { "Field":"Size", "Value":"1000", "Operation":"lt" } ], "Operation":"and" }
如果要搜尋以
exampledir/
為首碼,包含type=document
或owner=John
標籤且大小大於10 MB的檔案,則Query填寫樣本如下:{ "SubQueries": [ { "Field": "Filename", "Value": "exampledir/", "Operation": "prefix" }, { "Field": "Size", "Value": "1048576", "Operation": "gt" }, { "SubQueries": [ { "Field": "OSSTagging.type", "Value": "document", "Operation": "eq" }, { "Field": "OSSTagging.owner", "Value": "John", "Operation": "eq" } ], "Operation": "or" } ], "Operation": "and" }
結合以上搜尋條件,您還可以通過彙總操作實現不同資料的統計和分析,例如計算符合搜尋條件的所有檔案的大小總和、數量、平均值或者最值,統計所有符合搜尋條件圖片的尺寸分布情況。
錯誤碼
錯誤碼 | HTTP狀態代碼 | 描述 |
MetaQueryNotExist | 400 | Bucket不存在中繼資料索引庫,請確保已為Bucket開啟中繼資料管理功能並等待中繼資料索引庫建立成功後重試。 |
EntityTooLarge | 400 | 請求中查詢條件(即Query參數)的字串大小超過最大允許的位元組數。請修改後再重試。 |
InvalidArgument | 400 | 設定的參數值無效或格式錯誤,請設定正確的參數值。 |
InvalidParameter | 400 | 設定的參數值不合法,請設定正確的參數值。 |
MissingParameter | 400 | 未佈建要求中的必選參數,請設定必選參數。 |
Throttling.Api | 403 | 被流控,請降低請求QPS後重試。如果進行多次重試後仍出現該錯誤,請提交工單。 |
Throttling.User | 403 | 被流控,請降低請求QPS後重試。如果進行多次重試後仍出現該錯誤,請提交工單。 |
AccessDenied | 403 | 沒有訪問該Bucket的許可權,請確保已為RAM使用者授予訪問該Bucket的許可權。 |
NoSuchBucket | 404 | 目標Bucket不存在,請設定正確的Bucket名稱。 |
InternalServerError | 500 | 內部錯誤。如果進行多次重試後仍出現該錯誤,請提交工單。 |