Get Bucket-帮助中心-低成本的云存储-棱束链

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

细节分析

如果访问的 Bucket 不存在，包括试图访问因为命名不规范无法创建的Bucket ，返回 404 Not Found 错误，错误码：NoSuchBucket。
如果没有访问该 Bucket 的权限，返回 403 Forbidden 错误，错误码：AccessDenied。
如果 max-keys 设定值比棱束链对象存储系统上限值大，则系统会将按照上限值进行查找，上限值为1000。
如果 max-keys 没有赋值，则将默认为1000。
如果因为 max-keys 的设定无法一次得到所有结果，则该次结果会附加一个<NextMarker>，可以将<NextMarker>里面的值赋值给 marker ，下次查找时将会在给定值后继续查找，返回的结果将不包含 marker 给定的值。
如果把 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>

文档 & 帮助中心

文档 & 帮助中心

Get Bucket

Get Bucket（List Object）获取对象列表