对象存储 GetBucket

GetBucket 接口请求等同于 ListObjects，可以列出指定存储桶下的部分或全部对象。
注意事项
Delimiter 与 Prefix 约束
本接口对 delimiter 和 prefix 参数有以下约束：
delimiter 为必选参数，且取值必须为 /。未携带 delimiter 参数、或取值不为 / 时，将返回 400 InvalidArgument。
若携带 prefix 参数，则 prefix 必须以 / 结尾。即 prefix 必须是一个目录前缀，不支持以文件名前缀进行模糊筛选；不符合该约束时，将返回 400 InvalidArgument。
不携带 prefix 时，默认从存储桶根目录开始列举。
 上述约束意味着每次请求只列举单一目录下的子对象，而不会递归列举子目录中的内容。
文件对象与目录对象的呈现方式
同一次列举的响应中：
文件对象（对象键不以 / 结尾）出现在 <Contents> 中，每项包含 Key、Size、ETag、LastModified、StorageClass 等元信息。
目录对象（对象键以 / 结尾）出现在 <CommonPrefixes> 中，仅以前缀字符串形式呈现，不携带大小、ETag、最后修改时间等元信息。
分页
当未列举完毕时，响应中的 <IsTruncated> 为 true，并通过 <NextMarker> 给出下一页的游标。客户端需在下次请求中将该值原样作为 marker 传入，直到响应中 <IsTruncated> 为 false。
存储类型
存储桶中的所有对象的 StorageClass 固定为 RAPID。
请求
请求语法
GET /?prefix=<prefix>&delimiter=/&marker=<marker>&max-keys=<max-keys> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。
请求参数
参数名称
描述
类型
是否必选
prefix
限定返回的对象键必须以该字符串作为前缀。取值需以 / 结尾，详见上文「Delimiter 与 Prefix 约束」
string
否
delimiter
对象键的分组分隔符。详见上文「Delimiter 与 Prefix 约束」
string
是
marker
分页游标，取值为上一次 GetBucket 响应中的 <NextMarker>；首次请求无需携带
string
否
max-keys
单次请求返回的最大条目数，取值范围 [1, 1000]，默认值为 1000
int
否
请求头部
仅使用 公共请求头部，本接口无私有请求头部。
请求体
此接口无请求体。
响应
响应头部
仅返回 公共响应头部，本接口无私有响应头部。
响应体
响应体为 application/xml 格式：
<ListBucketResult>
    <Name>string</Name>
    <Prefix>string</Prefix>
    <Marker>string</Marker>
    <NextMarker>string</NextMarker>
    <Delimiter>string</Delimiter>
    <MaxKeys>int</MaxKeys>
    <IsTruncated>boolean</IsTruncated>
    <Contents>
        <Key>string</Key>
        <LastModified>string</LastModified>
        <ETag>string</ETag>
        <Size>int</Size>
        <StorageClass>string</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>string</Prefix>
    </CommonPrefixes>
    <CommonPrefixes>
        <Prefix>string</Prefix>
    </CommonPrefixes>
</ListBucketResult>
具体节点说明：
节点名称
父节点
描述
类型
ListBucketResult
无
保存 GetBucket 结果的所有信息
Container
Name
ListBucketResult
存储桶名称
string
Prefix
ListBucketResult
本次列举使用的对象键前缀，与请求参数 prefix 一致
string
Marker
ListBucketResult
本次请求所使用的分页游标，回显请求参数 marker；未指定时为空
string
NextMarker
ListBucketResult
下一页的分页游标，仅在 IsTruncated 为 true 时返回非空
string
Delimiter
ListBucketResult
本次列举使用的分隔符，与请求参数 delimiter 一致，固定为 /
string
MaxKeys
ListBucketResult
本次列举使用的最大条目数，与请求参数 max-keys 一致
int
IsTruncated
ListBucketResult
是否仍有未列举完的条目：true 表示存在下一页，false 表示已全部列举完
boolean
Contents
ListBucketResult
单个文件对象的元信息条目，可能出现 0 条或多条
Container
CommonPrefixes
ListBucketResult
单个目录对象的前缀条目，可能出现 0 条或多条
Container
Contents 节点包含的子节点：
节点名称
父节点
描述
类型
Key
ListBucketResult.Contents
文件对象的对象键
string
LastModified
ListBucketResult.Contents
文件对象的最后修改时间，UTC 时区，格式如 2019-08-20T11:59:35.000Z
string
ETag
ListBucketResult.Contents
文件对象的 ETag，由双引号包裹
string
Size
ListBucketResult.Contents
文件对象的大小，单位为字节
int
StorageClass
ListBucketResult.Contents
文件对象的存储类型，固定为 RAPID
string
CommonPrefixes 节点包含的子节点：
节点名称
父节点
描述
类型
Prefix
ListBucketResult.CommonPrefixes
目录对象的对象键，以 / 结尾
string
错误码
本接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。
实际案例
案例一：列举存储桶根目录下的对象
请求
GET /?delimiter=%2F&max-keys=100 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=date;host&q-url-param-list=delimiter;max-keys&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿
<ListBucketResult>
<Name>examplebucket-x--1250000000</Name>
    <Prefix></Prefix>
    <Marker></Marker>
    <Delimiter>/</Delimiter>
    <MaxKeys>100</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>example-object.jpg</Key>
        <LastModified>2019-05-29T04:00:00.000Z</LastModified>
        <ETag>&quot;d41d8cd98f00b204e9800998ecf8427e&quot;</ETag>
        <Size>10240</Size>
        <StorageClass>RAPID</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>folder-a/</Prefix>
    </CommonPrefixes>
    <CommonPrefixes>
        <Prefix>folder-b/</Prefix>
    </CommonPrefixes>
</ListBucketResult>
案例二：列举指定目录下的对象
请求
GET /?prefix=folder-a%2F&delimiter=%2F&max-keys=100 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=date;host&q-url-param-list=delimiter;max-keys;prefix&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿
<ListBucketResult>
<Name>examplebucket-x--1250000000</Name>
    <Prefix>folder-a/</Prefix>
    <Marker></Marker>
    <Delimiter>/</Delimiter>
    <MaxKeys>100</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>folder-a/file-1.jpg</Key>
        <LastModified>2019-05-29T04:00:00.000Z</LastModified>
        <ETag>&quot;d41d8cd98f00b204e9800998ecf8427e&quot;</ETag>
        <Size>10240</Size>
        <StorageClass>RAPID</StorageClass>
    </Contents>
    <CommonPrefixes>
        <Prefix>folder-a/sub-folder/</Prefix>
    </CommonPrefixes>
</ListBucketResult>
案例三：分页列举（响应被截断）
请求
GET /?prefix=folder-a%2F&delimiter=%2F&max-keys=2 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=date;host&q-url-param-list=delimiter;max-keys;prefix&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿
<ListBucketResult>
<Name>examplebucket-x--1250000000</Name>
    <Prefix>folder-a/</Prefix>
    <Marker></Marker>
    <NextMarker>folder-a/file-2.jpg</NextMarker>
    <Delimiter>/</Delimiter>
    <MaxKeys>2</MaxKeys>
    <IsTruncated>true</IsTruncated>
    <Contents>
        <Key>folder-a/file-1.jpg</Key>
        <LastModified>2019-05-29T04:00:00.000Z</LastModified>
        <ETag>&quot;d41d8cd98f00b204e9800998ecf8427e&quot;</ETag>
        <Size>10240</Size>
        <StorageClass>RAPID</StorageClass>
    </Contents>
    <Contents>
        <Key>folder-a/file-2.jpg</Key>
        <LastModified>2019-05-29T04:00:00.000Z</LastModified>
        <ETag>&quot;d41d8cd98f00b204e9800998ecf8427e&quot;</ETag>
        <Size>20480</Size>
        <StorageClass>RAPID</StorageClass>
    </Contents>
</ListBucketResult>
下一次翻页请求中将上一次响应的 <NextMarker> 原样作为 marker 传入即可继续列举。

参数名称	描述	类型	是否必选
prefix	限定返回的对象键必须以该字符串作为前缀。取值需以 `/` 结尾，详见上文「Delimiter 与 Prefix 约束」	string	否
delimiter	对象键的分组分隔符。详见上文「Delimiter 与 Prefix 约束」	string	是
marker	分页游标，取值为上一次 GetBucket 响应中的 `<NextMarker>`；首次请求无需携带	string	否
max-keys	单次请求返回的最大条目数，取值范围 `[1, 1000]`，默认值为 `1000`	int	否

节点名称	父节点	描述	类型
ListBucketResult	无	保存 GetBucket 结果的所有信息	Container
Name	ListBucketResult	存储桶名称	string
Prefix	ListBucketResult	本次列举使用的对象键前缀，与请求参数 `prefix` 一致	string
Marker	ListBucketResult	本次请求所使用的分页游标，回显请求参数 `marker`；未指定时为空	string
NextMarker	ListBucketResult	下一页的分页游标，仅在 `IsTruncated` 为 `true` 时返回非空	string
Delimiter	ListBucketResult	本次列举使用的分隔符，与请求参数 `delimiter` 一致，固定为 `/`	string
MaxKeys	ListBucketResult	本次列举使用的最大条目数，与请求参数 `max-keys` 一致	int
IsTruncated	ListBucketResult	是否仍有未列举完的条目：`true` 表示存在下一页，`false` 表示已全部列举完	boolean
Contents	ListBucketResult	单个文件对象的元信息条目，可能出现 0 条或多条	Container
CommonPrefixes	ListBucketResult	单个目录对象的前缀条目，可能出现 0 条或多条	Container

GetBucket

本页目录：

注意事项

Delimiter 与 Prefix 约束

文件对象与目录对象的呈现方式

分页

存储类型

请求

请求语法

请求参数

请求头部

请求体

响应

响应头部

响应体

错误码

实际案例

案例一：列举存储桶根目录下的对象

请求

响应

案例二：列举指定目录下的对象

请求

响应

案例三：分页列举（响应被截断）

请求

响应