GetBucket
更新时间：2023-08-17 17:36:57
列举指定空间的对象列表。需要IAM wos:GetBucket权限
请求语法
GET /?prefix=Prefix&marker=Marker&max-keys=Max-Keys&delimiter=Delimiter&start-time=Start-Time&end-time=End-Time
Host: BucketName.Endpoint
Date: Date
Authorization: <Authorization>
请求参数
参数名称 | 是否必填 | 描述 |
prefix | 否 | 列举以指定的字符串prefix开头的对象。可以指定前缀将空间对象分组，就像文件系统中使用文件夹一样。 类型：字符串。 |
marker | 否 | 列举空间内对象列表时，指定一个标识符，返回的对象列表将是按照字典顺序排序后这个标识符以后的所有对象。 类型：字符串。 |
max-keys | 否 | 指定返回的最大对象数，返回的对象列表将是按照字典顺序的最多前max-keys个对象，范围是[1，1000]，超出最大范围时，按照默认的1000进行处理。 类型：整型。 |
delimiter | 否 | 用来指定将对象名按照特定字符分割的分割符。如果指定了prefix参数，按delimiter对所有对象命名进行分割，多个对象分割后prefix到第一个delimiter间都相同的对象会形成一条CommonPrefixes；如果没有携带prefix参数，按delimiter对所有对象命名进行分割，多个对象分割后从对象名开始到第一个delimiter之间相同的部分形成一条CommonPrefixes。 类型：字符串。 |
注：参数名大小写敏感。例如：设置PREFIX=abc，该参数虽然参与鉴权，但实际作用不生效。
请求头部
使用公共请求头部。
请求主体
无请求主体。
响应语法
HTTP/1.1 StatusCode
x-wos-request-id: RequestId
Date: Date
Content-Type: type
Content-Length: length
Server: WS-web-server
<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="https://www.wangsu.com/document">
<ListBucketResult>
<IsTruncated>boolean</IsTruncated>
<Marker>string</Marker>
<NextMarker>string</NextMarker>
<Contents>
<ETag>string</ETag>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<ExpirationDate>timestamp</ExpirationDate>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<Size>integer</Size>
<StorageClass>string</StorageClass>
</Contents>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
</ListBucketResult>
响应头部
使用公共响应头部。
响应主体
该请求的响应消息中，会以XML形式将用户拥有的空间列出来，元素的具体含义如下表所示。
| 元素名称 | 描述 |
|---|---|
ListBucketResult | 空间内对象列表。 类型：XML |
Contents | 对象的元数据信息。 类型： XML 父节点：ListBucketResult |
CommonPrefixes | 如果请求中带delimiter参数时，则返回消息带CommonPrefixes分组信息。CommonPrefixes表明以delimiter结尾，拥有共同Prefix的对象的分组。 类型：XML 父节点：ListBucketResult |
Delimiter | 请求中携带的delimiter参数。 类型：字符串 父节点：ListBucketResult |
ETag | 对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。 实际的ETag是对象的哈希值，ETag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，通过MD5加密后都有唯一的ETag。 类型：字符串 父节点：ListBucketResult.Contents |
ID | 对象拥有者的用户ID。 类型：字符串 父节点：ListBucketResult.Contents.Owner |
DisplayName | 对象拥有者的用户名。 |
IsTruncated | 表明是否本次返回的ListBucketResult结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。 类型：Boolean 父节点：ListBucketResult |
Key | 对象名。 类型：字符串 父节点：ListBucketResult.Contents |
LastModified | 对象最近一次被修改的时间。 类型：Date 父节点：ListBucketResult.Contents |
Marker | 列举对象时的起始位置。 类型：字符串 父节点：ListBucketResult |
NextMarker | 如果本次没有返回全部结果，响应请求中将包含此字段，用于标明本次请求列举到的最后一个对象。后续请求可以指定Marker等于该值来列举剩余的对象。 类型：字符串 父节点：ListBucketResult |
MaxKeys | 列举时最多返回的对象个数。 类型：字符串 父节点：ListBucketResult |
Name | 本次请求的空间名。 类型：字符串 父节点：ListBucketResult |
Owner | 用户信息，包含用户ID和用户名。 类型：XML 父节点：ListBucketResult.Contents |
Prefix | 对象名的前缀，表示本次请求只列举对象名能匹配该前缀的所有对象。 类型：字符串 父节点：ListBucketResult |
Size | 对象大小。 类型：字符串 父节点：ListBucketResult.Contents |
StorageClass | 对象的存储类型。 类型：枚举值 有效值：STANDARD 父节点：ListBucketResult.Contents |
ExpirationDate | 文件过期时间。 类型：Date 父节点：ListBucketResult.Contents |
异常场景
| Situation | Http Status | Error Code | Message |
|---|---|---|---|
max-keys为负数 | 400 Bad Request | InvalidArgument | max-keys cannot be negative |
max-keys为小数或者超过最大整型上限 | 400 Bad Request | InvalidArgument | Provided max-keys not an integer or within integer range |