GetBucket接口用于列举存储空间(Bucket)中所有文件(Object)的信息。

说明 Object中自定义的元信息,在GetBucket请求时不会返回。

请求语法

GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

请求参数

名称 类型 是否必选 描述
Delimiter 字符串

对Object名字进行分组的字符。所有Object名字包含指定的前缀,第一次出现Delimiter字符之间的Object作为一组元素(即CommonPrefixes)。

默认值:无

Marker 字符串

设定从Marker之后按字母排序开始返回Object。

Marker用来实现分页显示效果,参数的长度必须小于1024字节。

在做条件查询时,即使Marker在列表中不存在,也会从符合Marker字母排序的下一个开始打印。

默认值:无

Max-keys 字符串

指定返回Object的最大数。

取值:大于0小于1000

默认值:100

说明 如果因为Max-keys的设定无法一次完成列举,返回结果会附加一个<NextMarker>作为下一次列举的Marker。
Prefix 字符串

限定返回文件的Key必须以Prefix作为前缀。

如果把Prefix设为某个文件夹名,就可以列举以此Prefix开头的文件,即该文件夹下递归的所有文件和子文件夹。

在设置Prefix的基础上增加设置Delimiter为 / 时,返回值就只列举该文件夹下的文件,文件夹下的子文件夹名返回在CommonPrefixes中,子文件夹下递归的所有文件和文件夹不显示。

例如,一个Bucket中存在三个Object : fun/test.jpg, fun/movie/001.avi,fun/movie/007.avi。若设定Prefix为 fun/,则返回三个Object;如果增加设定Delimiter为 /,则返回fun/test.jpg和fun/movie/ 。

说明
  • 参数的长度必须小于1024字节。

  • 使用Prefix查询时,返回的Key中仍会包含Prefix。

默认值:无

Encoding-type 字符串

对返回的内容进行编码并指定编码的类型。

默认值:无

可选值:url

说明 Delimiter、Marker、Prefix、NextMarker以及Key使用UTF-8字符。如果Delimiter、Marker、Prefix、NextMarker以及Key中包含XML 1.0标准不支持的控制字符,您可以通过指定Encoding-type对返回结果中的Delimiter、Marker、Prefix、NextMarker以及Key进行编码。

响应元素

名称 类型 描述
Contents 容器

保存每个返回Object元信息的容器。

父节点:ListBucketResult

CommonPrefixes 字符串

如果请求中指定了Delimiter参数,则会在返回的响应中包含CommonPrefixes元素。该元素表明以Delimiter结尾,并有共同前缀的Object名称的集合。

父节点:ListBucketResult

Delimiter 字符串

对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现Delimiter字符之间的Object作为一组元素CommonPrefixes。

父节点:ListBucketResult

EncodingType 字符串

指明了返回结果中编码使用的类型。如果请求的参数中指定了Encoding-type,那会对返回结果中的Delimiter、Marker、Prefix、NextMarker和Key这些元素进行编码。

父节点:ListBucketResult

DisplayName 字符串

Object 拥有者的名字。

父节点:ListBucketResult.Contents.Owner

ETag 字符串

ETag (entity tag) 在每个Object生成的时创建,用于标示一个Object的内容。

父节点:ListBucketResult.Contents

对于PutObject请求创建的Object,ETag值是其内容的MD5值;对于其他方式创建的Object,ETag值是其内容的UUID。ETag值可以用于检查Object内容是否发生变化。不建议您使用ETag来作为Object内容的MD5校验数据完整性。

ID 字符串

Bucket拥有者的用户ID。

父节点:ListBucketResult.Contents.Owner

IsTruncated 枚举字符串

请求中返回的结果是否被截断。

返回值:truefalse
  • true表示本次没有返回全部结果。
  • false表示本次已经返回了全部结果。

父节点:ListBucketResult

Key 字符串

Object的Key。

父节点:ListBucketResult.Contents

LastModified 时间

Object最后被修改的时间。

父节点:ListBucketResult.Contents

ListBucketResult 容器

保存GetBucket请求结果的容器。

子节点:Name、Prefix、 Marker、MaxKeys、 Delimiter、IsTruncated、Nextmarker、Contents

父节点:None

Marker 字符串

标明这次GetBucket(ListObjects)的起点。

父节点:ListBucketResult

MaxKeys 字符串

响应请求内返回结果的最大数目。

父节点:ListBucketResult

Name 字符串

Bucket名字。

父节点:ListBucketResult

Owner 容器

保存Bucket拥有者信息的容器。

子节点:DisplayName、ID

父节点:ListBucketResult

Prefix 字符串

本次查询结果的前缀。

父节点:ListBucketResult

Size 字符串

Object的字节数。

父节点:ListBucketResult.Contents

StorageClass 字符串

Object的存储类型。

父节点:ListBucketResult.Contents

示例

  • 简单请求示例
    GET / HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****

    返回示例

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1866
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>oss-example</Name>
    <Prefix></Prefix>
    <Marker></Marker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
        <IsTruncated>false</IsTruncated>
        <Contents>
            <Key>fun/movie/001.avi</Key>
            <LastModified>2012-02-24T08:43:07.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
        </Contents>
        <Contents>
            <Key>fun/movie/007.avi</Key>
            <LastModified>2012-02-24T08:43:27.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
        </Contents>
    <Contents>
            <Key>fun/test.jpg</Key>
            <LastModified>2012-02-24T08:42:32.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
        </Contents>
        <Contents>
            <Key>oss.jpg</Key>
            <LastModified>2012-02-24T06:07:48.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user-example</DisplayName>
            </Owner>
        </Contents>
    </ListBucketResult>
  • 带Prefix参数的请求示例
    GET /?prefix=fun HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykbo****

    返回示例

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 1464
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>oss-example</Name>
    <Prefix>fun</Prefix>
    <Marker></Marker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
        <IsTruncated>false</IsTruncated>
        <Contents>
            <Key>fun/movie/001.avi</Key>
            <LastModified>2012-02-24T08:43:07.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user_example</DisplayName>
            </Owner>
        </Contents>
        <Contents>
            <Key>fun/movie/007.avi</Key>
            <LastModified>2012-02-24T08:43:27.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user_example</DisplayName>
            </Owner>
        </Contents>
        <Contents>
            <Key>fun/test.jpg</Key>
            <LastModified>2012-02-24T08:42:32.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user_example</DisplayName>
            </Owner>
        </Contents>
    </ListBucketResult>
  • 带Prefix和Delimiter参数的请求示例
    GET /?prefix=fun/&delimiter=/ HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY****

    返回示例

    HTTP/1.1 200 OK
    x-oss-request-id: 534B371674E88A4D8906****
    Date: Fri, 24 Feb 2012 08:43:27 GMT
    Content-Type: application/xml
    Content-Length: 712
    Connection: keep-alive
    Server: AliyunOSS
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Name>oss-example</Name>
    <Prefix>fun/</Prefix>
    <Marker></Marker>
    <MaxKeys>100</MaxKeys>
    <Delimiter>/</Delimiter>
        <IsTruncated>false</IsTruncated>
        <Contents>
            <Key>fun/test.jpg</Key>
            <LastModified>2012-02-24T08:42:32.000Z</LastModified>
            <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&****;</ETag>
            <Type>Normal</Type>
            <Size>344606</Size>
            <StorageClass>Standard</StorageClass>
            <Owner>
                <ID>0022012****</ID>
                <DisplayName>user_example</DisplayName>
            </Owner>
        </Contents>
       <CommonPrefixes>
            <Prefix>fun/movie/</Prefix>
       </CommonPrefixes>
    </ListBucketResult>

SDK

此接口所对应的各语言SDK如下:

错误码

错误码 HTTP 状态码 描述
NoSuchBucket 404 目标Bucket不存在。
AccessDenied 403 没有访问该Bucket的权限。
InvalidArgument 400
  • Max-keys小于0或者大于1000。
  • Prefix,Marker,Delimiter参数的长度不符合要求。