Get Bucket

2022-09-24 21:09:48

Get Bucket(List Object)获取对象列表

获取某个 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

细节分析

  1. 如果访问的 Bucket 不存在,包括试图访问因为命名不规范无法创建 的Bucket ,返回 404 Not Found 错误,错误码:NoSuchBucket。
  2. 如果没有访问该 Bucket 的权限,返回 403 Forbidden 错误,错误码:AccessDenied。
  3. 如果 max-keys 设定值比 棱束链对象存储 系统上限值大,则系统会将按照上限值进行查找,上限值为1000。
  4. 如果 max-keys 没有赋值,则将默认为1000。
  5. 如果因为 max-keys 的设定无法一次得到所有结果,则该次结果会附加一个<NextMarker>,可以将<NextMarker>里面的值赋值给 marker ,下次查找时将会在给定值后继续查找,返回的结果将不包含 marker 给定的值。
  6. 如果把 prefix 设为某个文件夹名,就可以罗列以此 prefix 开头的文件,即该文件夹下递归的所有的文件和子文件夹。如果再把 delimiter 设置为 / 时,返回值就只罗列该文件夹下的文件,该文件夹下的子文件名返回在 CommonPrefixes 部分,子文件夹下递归的文件和文件夹不被显示。例如当不设置 delimiter 时,返回 error.html,index.html,page.html,page1.html,dir/,dir/index.html,相当于递归遍历 bucket 内部所有 object ,当设定 delimiter 为 / 时,将会返回 error.html,index.html,page.html,page1.html ,在<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>