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.