Lists all buckets owned by your Alibaba Cloud account. 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 Attach a custom policy to 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
Element | Type | Example | Description |
---|---|---|---|
ListAllMyBucketsResult | Container | N/A | The container used to store the results of the GetService (ListBuckets) 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:
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 responsesHTTP/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 responsesHTTP/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. |