获取某个 Bucket 的 Objects 信息。可以通过相关的请求参数获取 Bucket 下的某个 Object 子集。
请求语法
GET /bucket-name HTTP/1.1
Authorization: SignatureValue
Date: GMT Date
Host: s3-us-east-1.ossfiles.com
请求参数(Request Parameters)
名称 | 描述 |
---|---|
delimiter | delimiter 是一个用于对 bucket 内具有共同前缀的 objects 进行聚合的分隔符。(“/”为常用的 delimiter,用于表示伪目录) 数据类型:字符串 默认值: 无 |
marker | 设定返回的 objects 中的起始 object。sever 端会对 objects 进行字典序排列。 数据类型:字符串 默认值:无 |
max-keys | 设定此次请求的最大 objects 数量。如果用户设定了 max-keys 且符合条件的 objects 数量大于该值,则 server 端将只返回 max-keys 个 objects。 数据类型:字符串 默认值:1000 |
prefix | 设定 bucket 中 objects 的前缀名,只有包含该前缀的 objects 才会返回。 数据类型:字符串 默认值:无 |
响应元素(Response Elements)
名称 | 描述 |
---|---|
ListBucketResult | 保存 Get Bucket 请求结果的容器. 类型:容器 子节点:Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents 父节点:None |
Name | Bucket 名字 类型:字符串 父节点:ListBucketResult |
Prefix | 本次查询结果的开始前缀。 类型:字符串 父节点:ListBucketResult |
Marker | 标明这次 Get Bucket(List Object)的起点。 类型:字符串 父节点:ListBucketResult |
Delimiter | delimiter 是一个用于对 bucket 内具有共同前缀的 objects 进行聚合的分隔符。 类型:字符串 父节点:ListBucketResult |
IsTruncated | 指明是否所有的结果都已经返回; “true”表示本次没有返回全部结果;“false”表示本次已经返回了全部结果。 类型:枚举字符串 有效值:true、false 父节点:ListBucketResult |
NextMarker | 当一次返回不了全部结果(即响应中 的IsTruncated 元素值为 true)时,可以使用此字段中的键名作为 Marker 后续请求中的一个来获取下一组对象。 类型:字符串 父节点:ListBucketResult |
Contents | 保存每个返回 Object meta 的容器。 类型:容器 父节点:ListBucketResult |
Key | Object 的 Key 。 类型:字符串 父节点:ListBucketResult.Contents |
LastModified | Object 最后被修改的时间。 类型:时间 父节点:ListBucketResult.Contents |
ETag | Object 内容的 MD5 hash 值。 类型:字符串 父节点:ListBucketResult.Contents |
Size | Object 的字节数。 类型:字符串 父节点:ListBucketResult.Contents |
Owner | 保存 Bucket 拥有者信息的容器。 类型:容器 子节点:DisplayName, ID 父节点:ListBucketResult.Contents |
ID | Bucket 拥有者的用户 ID 。 类型:字符串 父节点:ListBucketResult.Contents.Owner |
DisplayName | Bucket 拥有者的名称。(目前和 ID 一致)。 类型:字符串 父节点:ListBucketResult.Contents.Owner |
StorageClass | Object 的存储类型,支持"3R"。 类型:字符串 父节点:ListBucketResult.Contents |
CommonPrefixes | 如果请求中指定了 delimiter 参数,则在 棱束链对象存储 返回的响应中必须包含 CommonPrefixes 元素。该元素标明那些以 delimiter 结尾,并有共同 Prefix 的 object 名称的集合。 类型:字符串 父节点:ListBucketResult |
细节分析
<NextMarker>
,可以将<NextMarker>
里面的值赋值给 marker ,下次查找时将会在给定值后继续查找,返回的结果将不包含 marker 给定的值。<CommonPrefixes>
里返回 dir/,相当于只遍历 Bucket 下一层 object 信息,不递归遍历所有 object。示例
请求示例:
GET /test212/?delimiter=%2F&max-keys=1000&prefix= HTTP/1.1
Authorization: AWS4-HMAC-SHA256 Credential=6a19c6de088ff32ff663287eec8f3b85/20220421/us-east-1/s3/aws4_request,SignedHeaders=host;user-agent;x-amz-content-sha256;x-amz-date, Signature=38d62743b49550811f181ec481cecd4a0bd13cc3e1aa1b1f5b073d2cbb326c3d
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date: 20220421T183607Z
Host: s3-us-east-1.ossfiles.com
返回示例:
HTTP/1.1 200 OK
Date: Thu, 21 Apr 2022 18:36:02 GMT
Content-Type: application/xml
Content-Length: 374
Connection: keep-alive
Expires: Sat, 03 Mar 1990 23:33:33 GMT
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Name>test212</Name>
<Prefix />
<Marker />
<MaxKeys>1000</MaxKeys>
<Delimiter>/</Delimiter>
<IsTruncated>false</IsTruncated>
<CommonPrefixes>
<Prefix>123/</Prefix>
</CommonPrefixes>
<CommonPrefixes>
<Prefix>multipart/</Prefix>
</CommonPrefixes>
</ListBucketResult>