Lists all buckets that belong to 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 Object Storage Service (OSS) buckets, you must have the oss: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 headers
Header | Type | Required | Example | Description |
x-oss-resource-group-id | String | No | rg-aek27tc******** | The ID of the resource group.
You can obtain the ID of a resource group in the Resource Management console or by calling the ListResourceGroups operation. For more information, see View basic information of a resource group and ListResourceGroups. |
For more information about other common request headers included in a ListBuckets (GetService) request, such as Host and Date, see Common request headers.
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. By default, this parameter is left empty. |
marker | String | No | mybucket10 | The name of the bucket after which the ListBuckets (GetService) operation starts. Buckets whose names are alphabetically greater than the value of the marker parameter are returned. If this parameter is not specified, all buckets are returned. By default, this parameter is left empty. |
max-keys | Integer | No | 10 | The maximum number of buckets that can be returned for the request. Valid values: 1 to 1000. Default value: 100. |
Response headers
All headers in the response to a ListBuckets (GetService) request are common response headers. For more information, see Common response headers.
Response elements
When you call the ListBuckets (GetService) operation, the XML body of the response does not include the Prefix, Marker, MaxKeys, IsTruncated, or NextMarker parameter if all buckets are returned.
Element | Type | Example | Description |
ListAllMyBucketsResult | Container | N/A | The container that stores the results of the ListBuckets (GetService) request. Child nodes: Owner and Buckets Parent nodes: none. |
Prefix | String | my | The prefix contained in the names of the returned buckets. Parent nodes: ListAllMyBucketsResult |
Marker | String | mybucket | The name of the bucket after which the ListBuckets (GetService) operation starts. Parent nodes: ListAllMyBucketsResult |
MaxKeys | String | 10 | The maximum number of buckets that can be returned for the request. 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 request, which can be used to return the remaining results. Parent nodes: ListAllMyBucketsResult |
Owner | Container | N/A | The container that stores information about the bucket owner. Parent nodes: ListAllMyBucketsResult |
ID | String | ut_test_put_bucket | The ID of the bucket owner. Parent nodes: ListAllMyBucketsResult.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.Owner |
Buckets | Container | N/A | The container that stores information about multiple buckets. Child nodes: Bucket Parent nodes: ListAllMyBucketsResult |
Bucket | Container | N/A | The container that stores information about the bucket. Child nodes: Name, CreationDate, and Location Parent nodes: ListAllMyBucketsResult.Buckets |
Name | String | mybucket01 | The name of the bucket. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
CreateDate | Time | 2014-05-15T11:18:32.000Z | The time when the bucket was created. Format: Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
Location | String | oss-cn-hangzhou | The region in which the bucket is located. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
ExtranetEndpoint | String | oss-cn-hangzhou.aliyuncs.com | The public endpoint used to access the bucket over the Internet. Parent nodes: ListAllMyBucketsResult.Buckets.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 that reside in the same region as the bucket. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
Region | String | cn-hangzhou | The region in which the bucket is located. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
StorageClass | String | Standard | The storage class of the bucket. Valid values: Standard, IA, Archive, ColdArchive, and DeepColdArchive. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
ResourceGroupId | String | rg-aek27tc******** | The ID of the resource group to which the bucket belongs. If the bucket belongs to the default resource group, the resource group ID is rg-default-id. Parent nodes: ListAllMyBucketsResult.Buckets.Bucket |
Examples
Query all buckets owned by the requester
Sample request
GET / HTTP/1.1 Date: Thu, 15 May 2014 11:18:32 GMT Host: oss-cn-hangzhou.aliyuncs.com Authorization: OSS nxj7dtlhcyl5hpvnhi:COS3OQkfQPnKmYZTEHYv2******
Sample response
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 request
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 response
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>
Query all buckets that belong to a specific resource group
Sample request
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********
Sample response
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>
Query all buckets in the default resource group
Sample request
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
Sample response
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>
OSS SDKs
You can use OSS SDKs for the following programming languages to call the ListBuckets (GetService) operation:
Error codes
Error code | HTTP status code | Description |
AccessDenied | 403 | The request is from an anonymous user and does not include user authentication information. |