调用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。
您可以通过资源管理的控制台或ListResourceGroups接口获取资源组ID。具体操作,请分别参见查看资源组基本信息和ListResourceGroups。 |
此接口涉及的其他公共请求头,例如Host、Date等的更多信息,请参见公共请求头(Common Request Headers)。
请求参数
名称 | 类型 | 是否必选 | 示例值 | 描述 |
prefix | 字符串 | 否 | my | 限定返回的Bucket名称必须以prefix作为前缀。如果不设定,则不过滤前缀信息。 默认值:无 |
marker | 字符串 | 否 | mybucket10 | 设定结果从marker之后按字母排序的第一个开始返回。如果不设定,则从头开始返回数据。 默认值:无 |
max-keys | Integer | 否 | 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 | 是否所有的结果都已经返回。 取值范围如下:
父节点:ListAllMyBucketsResult |
NextMarker | 字符串 | mybucket10 | 用于继续查询时给marker赋值。表示下一次ListBuckets(GetService)可以以此为marker,将未返回的结果返回。 父节点:ListAllMyBucketsResult |
Owner | 容器 | 不涉及 | 用于存放Bucket拥有者信息的容器。 父节点:ListAllMyBucketsResult |
ID | 字符串 | ut_test_put_bucket | Bucket拥有者的用户ID。 父节点:ListAllMyBucketsResult.Owner |
DisplayName | 字符串 | ut_test_put_bucket | Bucket拥有者的名称 (目前和ID一致)。 父节点:ListAllMyBucketsResult.Owner |
Buckets | 容器 | 不涉及 | 保存多个Bucket信息的容器。 子节点:Bucket 父节点:ListAllMyBucketsResult |
Bucket | 容器 | 不涉及 | 保存Bucket信息的容器。 子节点:Name, CreationDate, Location 父节点:ListAllMyBucketsResult.Buckets |
Name | 字符串 | mybucket01 | Bucket名称。 父节点:ListAllMyBucketsResult.Buckets.Bucket |
CreationDate | 时间 | 2014-05-15T11:18:32.000Z | Bucket创建时间。格式为 父节点:ListAllMyBucketsResult.Buckets.Bucket |
Location | 字符串 | oss-cn-hangzhou | OSS专用Region ID。 父节点:ListAllMyBucketsResult.Buckets.Bucket |
ExtranetEndpoint | 字符串 | oss-cn-hangzhou.aliyuncs.com | 外网访问域名。 父节点:ListAllMyBucketsResult.Buckets.Bucket |
IntranetEndpoint | 字符串 | oss-cn-hangzhou-internal.aliyuncs.com | 内网访问域名。 父节点:ListAllMyBucketsResult.Buckets.Bucket |
Region | 字符串 | cn-hangzhou | 阿里云通用Region ID。 父节点:ListAllMyBucketsResult.Buckets.Bucket |
StorageClass | 字符串 | Standard | Bucket存储类型,支持Standard、IA、Archive、ColdArchive和DeepColdArchive多种存储类型。 父节点:ListAllMyBucketsResult.Buckets.Bucket |
ResourceGroupId | 字符串 | rg-aek27tc******** | Bucket所属资源组ID。如果Bucket属于默认资源组,则返回值为rg-default-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 qn6q**************:77Dv****************
返回示例
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 qn6q**************:77Dv****************
返回示例
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 qn6q**************:77Dv**************** 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 qn6q**************:77Dv**************** 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状态码 | 描述 |
AccessDenied | 403 | 请求中没有用户验证信息(即匿名访问)。 |