调用ListBuckets（GetService）接口列举请求者拥有的所有存储空间（Bucket）。您还可以通过设置prefix、marker或者max-keys参数列举满足指定条件的存储空间。

注意事项

如果您需要列举OSS Bucket，您必须拥有oss:ListBuckets权限。

具体操作，请参见为RAM用户授权自定义的权限策略。

请求语法

GET / HTTP/1.1
Host: oss.example.com
Date: GMT Date
Authorization: SignatureValue

请求头

名称类型是否必选示例值描述
x-oss-resource-group-id字符串否rg-aek27tc********指定资源组ID。
  • 如果在请求中携带该请求头并指定资源组ID，则OSS会返回属于该资源组的所有Bucket。

    当指定的资源组ID为rg-default-id时，OSS会返回属于默认资源组的所有Bucket。

  • 如果在请求中携带了该请求头但未指定资源组ID，则OSS会返回属于默认资源组的所有Bucket。
  • 如果在请求中未携带该请求头，则OSS会返回请求者拥有的所有Bucket。

您可以通过资源管理的控制台或ListResourceGroups接口获取资源组ID。具体操作，请分别参见查看资源组基本信息和ListResourceGroups。

此接口涉及的其他公共请求头，例如Host、Date等的更多信息，请参见公共请求头（Common Request Headers）。

请求参数

名称类型是否必选示例值描述
prefix字符串否my限定返回的Bucket名称必须以prefix作为前缀。如果不设定，则不过滤前缀信息。

默认值：无

marker字符串否mybucket10设定结果从marker之后按字母排序的第一个开始返回。如果不设定，则从头开始返回数据。

默认值：无

max-keysInteger否10限定此次返回Bucket的最大个数。

取值范围：1~1000

默认值：100

响应头

此接口仅涉及公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

响应元素

说明 调用ListBuckets（GetService）接口时，如果所有Bucket已返回，则返回的XML中不包含Prefix、Marker、MaxKeys、IsTruncated和NextMarker响应元素。
名称类型示例值描述
ListAllMyBucketsResult容器不涉及保存ListBuckets（GetService）请求结果的容器。

子节点：Owner、Buckets

父节点：None

Prefix字符串my本次查询结果的前缀。

父节点：ListAllMyBucketsResult

Marker字符串mybucket表示本次ListBuckets（GetService）的起点。

父节点：ListAllMyBucketsResult

MaxKeys字符串10响应请求内返回结果的最大个数。

父节点：ListAllMyBucketsResult

IsTruncated枚举字符串true是否所有的结果都已经返回。 取值范围如下：
  • true：表示本次没有返回全部结果。
  • false：表示本次已经返回了全部结果。

父节点：ListAllMyBucketsResult

NextMarker字符串mybucket10用于继续查询时给marker赋值。表示下一次ListBuckets（GetService）可以以此为marker，将未返回的结果返回。

父节点：ListAllMyBucketsResult

Owner容器不涉及用于存放Bucket拥有者信息的容器。

父节点：ListAllMyBucketsResult

ID字符串ut_test_put_bucketBucket拥有者的用户ID。

父节点：ListAllMyBucketsResult.Owner

DisplayName字符串ut_test_put_bucketBucket拥有者的名称 （目前和ID一致）。

父节点：ListAllMyBucketsResult.Owner

Buckets容器不涉及保存多个Bucket信息的容器。

子节点：Bucket

父节点：ListAllMyBucketsResult

Bucket容器不涉及保存Bucket信息的容器。

子节点：Name, CreationDate, Location

父节点：ListAllMyBucketsResult.Buckets

Name字符串mybucket01Bucket名称。

父节点：ListAllMyBucketsResult.Buckets.Bucket

CreateDate时间2014-05-15T11:18:32.000ZBucket创建时间。格式为yyyy-mm-ddThh:mm:ss.timezone。

父节点：ListAllMyBucketsResult.Buckets.Bucket

Location字符串oss-cn-hangzhouBucket所在的数据中心。

父节点：ListAllMyBucketsResult.Buckets.Bucket

ExtranetEndpoint字符串oss-cn-hangzhou.aliyuncs.comBucket访问的外网域名。

父节点：ListAllMyBucketsResult.Buckets.Bucket

IntranetEndpoint字符串oss-cn-hangzhou-internal.aliyuncs.com同地域ECS访问Bucket的内网域名。

父节点：ListAllMyBucketsResult.Buckets.Bucket

Region字符串cn-hangzhouBucket所在地域。

父节点：ListAllMyBucketsResult.Buckets.Bucket

StorageClass字符串StandardBucket存储类型，支持Standard、IA、Archive和ColdArchive四种存储类型。

父节点：ListAllMyBucketsResult.Buckets.Bucket

ResourceGroupId字符串rg-aek27tc********Bucket所属资源组ID。如果Bucket属于默认资源组，则返回值为rg-defalut-id。

父节点：ListAllMyBucketsResult.Buckets.Bucket

示例

  • 获取请求者拥有的所有Bucket
    请求示例
    GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS nxj7dtlhcyl5hpvnhi:COS3OQkfQPnKmYZTEHYv2******
    返回示例 
    HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 556
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>512**</ID>
    <DisplayName>51264</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-02-17T18:12:43.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-shanghai</Location>
      <Name>app-base-oss</Name>
      <Region>cn-shanghai</Region>
      <StorageClass>Standard</StorageClass>
    </Bucket>
    <Bucket>
      <CreationDate>2014-02-25T11:21:04.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>mybucket</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>IA</StorageClass>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>
  • 根据指定前缀、最大返回个数等获取Bucket
    请求示例
    GET /?prefix=my&max-keys=10 HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS nxj7dtwhcyl5hpvnhi:COS3OQkfQPnKmYZTEHYv2****
    返回示例 
    HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 545
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Prefix>my</Prefix>
  <Marker>mybucket</Marker>
  <MaxKeys>10</MaxKeys>
  <IsTruncated>true</IsTruncated>
  <NextMarker>mybucket10</NextMarker>
  <Owner>
    <ID>ut_test_put_bucket</ID>
    <DisplayName>ut_test_put_bucket</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-05-14T11:18:32.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>mybucket01</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>Standard</StorageClass>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>
  • 获取指定资源组中的所有Bucket
    请求示例
    GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS nxj7dtlhcyl5hpvnhi:COS3OQkfQPnKmYZTEHYv2******
x-oss-resource-group-id: rg-aek27tc********
    返回示例
    HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 556
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>512**</ID>
    <DisplayName>51264</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-02-07T18:12:43.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-shanghai</Location>
      <Name>test-bucket-1</Name>
      <Region>cn-shanghai</Region>
      <StorageClass>Standard</StorageClass>
      <ResourceGroupId>rg-aek27tc********</ResourceGroupId>
    </Bucket>
    <Bucket>
      <CreationDate>2014-02-05T11:21:04.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>test-bucket-2</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>IA</StorageClass>
      <ResourceGroupId>rg-aek27tc********</ResourceGroupId>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>
  • 获取默认资源组中的所有Bucket
    请求示例
    GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS nxj7dtlhcyl5hpvnhi:COS3OQkfQPnKmYZTEHYv2******
x-oss-resource-group-id：rg-default-id
    返回示例
    HTTP/1.1 200 OK
Date: Thu, 15 May 2014 11:18:32 GMT
Content-Type: application/xml
Content-Length: 556
Connection: keep-alive
Server: AliyunOSS
x-oss-request-id: 5374A2880232A65C2300****
<?xml version="1.0" encoding="UTF-8"?>
<ListAllMyBucketsResult>
  <Owner>
    <ID>512**</ID>
    <DisplayName>51264</DisplayName>
  </Owner>
  <Buckets>
    <Bucket>
      <CreationDate>2014-02-07T18:12:43.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-shanghai.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-shanghai-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-shanghai</Location>
      <Name>test-bucket-3</Name>
      <Region>cn-shanghai</Region>
      <StorageClass>Standard</StorageClass>
      <ResourceGroupId>rg-default-id</ResourceGroupId>
    </Bucket>
    <Bucket>
      <CreationDate>2014-02-05T11:21:04.000Z</CreationDate>
      <ExtranetEndpoint>oss-cn-hangzhou.aliyuncs.com</ExtranetEndpoint>
      <IntranetEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</IntranetEndpoint>
      <Location>oss-cn-hangzhou</Location>
      <Name>test-bucket-4</Name>
      <Region>cn-hangzhou</Region>
      <StorageClass>IA</StorageClass>
      <ResourceGroupId>rg-default-id</ResourceGroupId>
    </Bucket>
  </Buckets>
</ListAllMyBucketsResult>

SDK

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

错误码

错误码HTTP状态码描述
AccessDenied403请求中没有用户验证信息（即匿名访问）。