调用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 字符串 MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw== 当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 字符串 MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw== 当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-29T14:50:13.011643661+08:00 Object的最近一次修改时间,遵循RFC 3339标准格式,格式为YYYY-MM-DDTHH:mm:ss.ms+TIMEZONE。其中YYYY-MM-DD表示年月日,T表示time元素的开头,HH:mm:ss.ms表示时分秒毫秒,TIMEZONE表示时区。

父节点:File

OSSObjectType 字符串 Normal Object的类型。取值范围如下:
  • Normal:通过PutObject接口上传或者通过CreateDirectory接口创建的Object类型。
  • Appendable:通过AppendObject接口上传的Object类型。
  • Multipart:通过MultipartUpload接口上传的Object类型。
  • Symlink:通过PutSymlink接口创建的软链接。

父节点:File

OSSStorageClass 字符串 Standard Object的存储类型。取值范围如下:
  • Standard:标准存储类型提供高可靠、高可用、高性能的对象存储服务,能够支持频繁的数据访问。
  • IA:低频访问存储类型适合需要长期存储但不经常被访问的数据(平均每月访问频率1到2次)。
  • Archive:归档存储类型适合需要长期存储(建议半年以上)的归档数据,在存储周期内极少被访问,数据进入到可读取状态需要1分钟的解冻时间。
  • ColdArchive:冷归档存储类型适用于需要长期保存且几乎不访问的数据。

父节点: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 qn6qrrqxo2oawuk53otf****:ceOEyZavKY4QcjoUWYSpYbJ3****
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==</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>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==</NextToken>
  <Files>
    <File>
      <Filename>exampleobject.txt</Filename>
      <Size>120</Size>
      <FileModifiedTime>2021-06-29T14:50:13.011643661+08: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=documentowner=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 内部错误。如果进行多次重试后仍出现该错误,请提交工单。