Lists buckets owned by your Alibaba Cloud account or all buckets that belong to the specified . You can specify the prefix, marker, or max-keys parameter to list buckets that meet specific conditions.

Usage notes

To list buckets, you must have the oss:GetService (ListBuckets) permission. For more information, see Assign a custom RAM policy for a RAM user.

Request syntax

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

Request parameters

Parameter Type Required Example Description
prefix String No my The prefix that the names of returned buckets must contain. If this parameter is not specified, prefixes are not used to filter returned buckets.

Default value: null
marker String No mybucket10 The name of the bucket from which the list operation begins. Buckets whose names are alphabetically greater than the marker parameter value are returned. If this parameter is not specified, all buckets are returned.

Default value: null
max-keys Integer No 10 The maximum number of buckets that can be returned in the single query.

Valid values: 1 to 1000.

Default value: 100.

Response elements

Note When you call the GetService (ListBuckets) operation, the XML body of the response does not include the Prefix, Marker, MaxKeys, IsTruncated, or NextMarker element if all buckets are returned.
Element Type Example Description
ListAllMyBucketsResult Container N/A The container used to store the results of the GetService request.

Child nodes: Owner and Buckets

Parent nodes: none
Prefix String my The prefix that the returned bucket names must contain in the single query.

Parent nodes: ListAllMyBucketsResult
Marker String mybucket The name of the bucket after which the list operation begins in the single query.

Parent nodes: ListAllMyBucketsResult
MaxKeys String 10 The maximum number of buckets returned in the single query.

Parent nodes: ListAllMyBucketsResult
IsTruncated Enumerated string true Indicates whether all results are returned. Valid values:
  • true: Only part of the results are returned in the single query.
  • false: All of the results are returned in the single query.

Parent nodes: ListAllMyBucketsResult
NextMarker String mybucket10 The marker for the next GetService (ListBuckets) request. The element indicates the position from which the next list operation starts.

Parent nodes: ListAllMyBucketsResult
Owner Container N/A The container that stores the information about the bucket owner.

Parent nodes: ListAllMyBucketsResult
ID String ut_test_put_bucket The user ID of the bucket owner.

Parent nodes: ListAllMyBucketsResult and Owner
DisplayName String ut_test_put_bucket The name of the bucket owner. The name of the bucket owner is the same as the user ID.

Parent nodes: ListAllMyBucketsResult and Owner
Buckets Container N/A The container that stores the information of multiple buckets.

Child nodes: Bucket

Parent nodes: ListAllMyBucketsResult
Bucket Container N/A The container that stores the bucket information.

Child nodes: Name, CreationDate, and Location

Parent nodes: ListAllMyBucketsResult and Buckets
Name String mybucket01 The name of the bucket.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket
CreateDate Time 2014-05-15T11:18:32.000Z The time when the bucket was created. Format: yyyy-mm-ddThh:mm:ss.timezone.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket
Location String oss-cn-hangzhou The data center in which the bucket is located.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket
ExtranetEndpoint String oss-cn-hangzhou.aliyuncs.com The public endpoint used to access the bucket over the Internet.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket
IntranetEndpoint String oss-cn-hangzhou-internal.aliyuncs.com The internal endpoint that is used to access the bucket from Elastic Compute Service (ECS) instances in the same region as the bucket.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket
Region String cn-hangzhou The region in which the bucket is located.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket
StorageClass String Standard The storage class of the bucket. Valid values: Standard, IA, Archive, and ColdArchive.

Parent nodes: ListAllMyBucketsResult, Buckets, and Bucket

Examples

  • Query all buckets owned by the requester
    Sample requests
    GET / HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: oss-cn-hangzhou.aliyuncs.com
Authorization: OSS nxj7dtlhcyl5hpvnhi:COS3OQkfQPnKmYZTEHYv2******
    Sample responses 
    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>
  • Query buckets by specifying a prefix and the maximum number of returned buckets
    Sample requests
    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****
    Sample responses 
    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>

SDK

You can use OSS SDKs for the following programming languages to call the GetBucket (ListObjects) operation:

Error codes

Error code HTTP status code Description
AccessDenied 403 The error message returned because the request is from anonymous access and includes no user authentication information.