DoMetaQuery - Object Storage Service

調用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"}	查詢條件。包括如下選項： Operation：操作符。取值範圍為eq（等於）、gt（大於）、gte（大於等於）、lt（小於）、 lte（小於等於）、match（模糊查詢）、prefix（首碼查詢）、and（邏輯與）、or（邏輯或）和not（邏輯非）。 Field：欄位名稱。支援的欄位以及欄位對操作符的支援情況請參見附錄：欄位和操作符的支援列表。 Value：欄位值。 SubQueries：子查詢條件，包括的選項與簡單查詢條件相同。只有當Operations為邏輯運算子（and、or和not）時，才需要設定子查詢條件。關於Query樣本的更多資訊，請參見Query樣本。父節點：MetaQuery
Sort	字串	否	Size	對指定欄位排序。關於支援排序的欄位列表，請參見附錄：欄位和操作符的支援列表。父節點：MetaQuery
Order	字串	否	asc	排序方式。取值範圍如下： asc：升序 desc（預設值）：降序父節點：MetaQuery
Aggregations	容器	否	不涉及	彙總操作資訊的容器。子節點：Aggregation 父節點：MetaQuery
Aggregation	容器	否	不涉及	單個彙總操作資訊的容器。子節點：Field、Operation 父節點：Aggregations
Field	字串	否	Size	欄位名稱。關於支援的欄位以及欄位對操作符的支援情況，請參見附錄：欄位和操作符的支援列表。父節點：Aggregation
Operation	字串	否	sum	彙總操作中的操作符。取值範圍如下： min：最小值 max：最大值 average：平均數 sum：求和 count：計數 distinct：去重統計 group：分組計數父節點：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的類型。取值範圍如下： Normal：通過PutObject介面上傳或者通過CreateDirectory介面建立的Object類型。 Appendable：通過AppendObject介面上傳的Object類型。 Multipart：通過MultipartUpload介面上傳的Object類型。 Symlink：通過PutSymlink介面建立的軟連結。父節點：File
OSSStorageClass	字串	Standard	Object的儲存類型。取值範圍如下： Standard：標準儲存類型提供高可靠、高可用、高效能的Object Storage Service服務，能夠支援頻繁的資料訪問。 IA：低頻訪問儲存類型適合需要長期儲存但不經常被訪問的資料（平均每月訪問頻率1到2次）。 Archive：Archive Storage類型適合需要長期儲存（建議半年以上）的歸檔資料，在儲存周期內極少被訪問，資料進入到可讀取狀態需要1分鐘的解凍時間。 ColdArchive：冷Archive Storage類型適用於需要長期儲存且幾乎不訪問的資料。父節點：File
ObjectACL	字串	default	Object的存取權限。取值範圍如下： default：Object遵循所在儲存空間的存取權限。 private：Object是私人資源。只有Object的擁有者和授權使用者有該Object的讀寫權限，其他使用者沒有許可權操作該Object。 public-read：Object是公用讀取資源。只有Object的擁有者和授權使用者有該Object的讀寫權限，其他使用者只有該Object的讀許可權。請謹慎使用該許可權。 public-read-write：Object是公用讀寫資源。所有使用者都有該Object的讀寫權限。請謹慎使用該許可權。父節點：File
ETag	字串	"fba9dede5f27731c9771645a3986****"	Object產生時會建立相應的ETag ，ETag用於標識一個Object的內容。對於PutObject請求建立的Object，ETag值是其內容的MD5值。對於其他方式建立的Object，ETag值是基於一定計算規則產生的唯一值，但不是其內容的MD5值。說明 ETag值可以用於檢查Object內容是否發生變化。不建議使用ETag作為Object內容的MD5來校正資料完整性。父節點：File
OSSTaggingCount	整型	2	Object的標籤個數。父節點：File
OSSTagging	容器	不涉及	標籤資訊的容器。子節點：Tagging 父節點：File
Tagging	容器	不涉及	單個標籤資訊的容器。子節點：Key、Value 父節點：OSSTagging
Key	字串	owner	標籤或者使用者自訂中繼資料的Key。使用者自訂中繼資料必須以`x-oss-meta-`為首碼。父節點：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	內部錯誤。如果進行多次重試後仍出現該錯誤，請提交工單。