edit-icon download-icon

Manage a bucket

Last Updated: Aug 08, 2018

A bucket serves as a container that stores objects. Objects belong to a bucket.

Create a bucket

Use the following code to create a bucket:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // Create a bucket.
  9. String bucketName = "<yourBucketName>";
  10. // The default storage class and ACL of the created bucket are set to standard and private read respectively.
  11. ossClient.createBucket(bucketName);
  12. // Close your OSSClient.
  13. ossClient.shutdown();

For more information about bucket naming rules, see naming conventions in Basic concepts.

You can specify the ACL and the storage class when you create a bucket, as shown in Bucket-level permissions and Storage class. To create Infrequent Access or archive buckets, use Java SDK versions 2.6.0 or later. The sample code is as follows:

  1. CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucketName);
  2. // Set the ACL to public read for a bucket. The default value is Private.
  3. createBucketRequest.setCannedACL(CannedAccessControlList.PublicRead);
  4. // Set the storage class to Infrequent Access for a bucket. The default value is Standard.
  5. createBucketRequest.setStorageClass(StorageClass.IA);
  6. ossClient.createBucket(createBucketRequest);

List buckets

Buckets are listed alphabetically. You can list all buckets or buckets that meet the specified conditions. To list Infrequent Access or archive buckets, use Java SDK versions 2.6.0 or later.

List all buckets

Use the following code to list all buckets:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // List buckets.
  9. List<Bucket> buckets = ossClient.listBuckets();
  10. for (Bucket bucket : buckets) {
  11. System.out.println(" - " + bucket.getName());
  12. }
  13. // Close your OSSClient.
  14. ossClient.shutdown();

List buckets with a specified prefix

Use the following code to list buckets with a specified prefix:

  1. ListBucketsRequest listBucketsRequest = new ListBucketsRequest();
  2. // List buckets by a specified prefix. If no prefix is specified, list all buckets.
  3. listBucketsRequest.setPrefix("<yourBucketPrefix>");
  4. BucketList bucketList = ossClient.listBuckets(listBucketsRequest);
  5. for (Bucket bucket : bucketList.getBucketList()) {
  6. System.out.println(" - " + bucket.getName());
  7. }

List buckets by marker

The value of the marker parameter indicates the name of a bucket. Use the following code to list buckets after the specified bucket (the value of marker):

  1. ListBucketsRequest listBucketsRequest = new ListBucketsRequest();
  2. // List buckets after the specified marker. If the marker is not specified, list all buckets.
  3. listBucketsRequest.setMarker("<yourBucketMarker>");
  4. BucketList bucketList = ossClient.listBuckets(listBucketsRequest);
  5. for (Bucket bucket : bucketList.getBucketList()) {
  6. System.out.println(" - " + bucket.getName());
  7. }

List a specified number of buckets

Use the following code to list a specified number of buckets:

  1. ListBucketsRequest listBucketsRequest = new ListBucketsRequest();
  2. // Set the number of buckets that can be listed to 500. The default value is 100. The maximum value is 1,000.
  3. listBucketsRequest.setMaxKeys(500);
  4. BucketList bucketList = ossClient.listBuckets(listBucketsRequest);
  5. for (Bucket bucket : bucketList.getBucketList()) {
  6. System.out.println(" - " + bucket.getName());
  7. }

Determine whether a bucket exists

Use the following code to determine whether a specified bucket exists:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. boolean exists = ossClient.doesBucketExist("<yourBucketName>");
  9. // Close your OSSClient.
  10. ossClient.shutdown();

Configure an ACL for a bucket

The ACL of a bucket includes the following permissions.

Permission Value in Java SDK
private(private read and write) CannedAccessControlList.Private
public-read(publci read and private write) CannedAccessControlList.PublicRead
public-read-write (private read and write) CannedAccessControlList.PublicReadWrite

Use the following code to configure the ACL for a bucket:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // Set the ACL for a bucket to private read and write.
  9. ossClient.setBucketAcl("<yourBucketName>", CannedAccessControlList.Private);
  10. // Close your OSSClient.
  11. ossClient.shutdown();

Obtain an ACL for a bucket

Use the following code to obtain the ACL for a bucket:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // Obtain an ACL for a bucket.
  9. AccessControlList acl = ossClient.getBucketAcl("<yourBucketName>");
  10. System.out.println(acl.toString());
  11. // Close your OSSClient.
  12. ossClient.shutdown();

Obtain the region of a bucket

Use the following code to obtain the region for a bucket:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. String location = ossClient.getBucketLocation("<yourBucketName>");
  9. System.out.println(location);
  10. // Close your OSSClient.
  11. ossClient.shutdown();

For more information about regions, see Region in Basic concepts.

Obtain bucket information

Use the following code to obtain bucket information:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // Bucket information includes regions (region or location), creation dates (CreationDate), owners (Owner), and permissions (Grants).
  9. BucketInfo info = ossClient.getBucketInfo("<yourBucketName>");
  10. // Obtain region information.
  11. info.getBucket().getLocation();
  12. // Obtain the creation date.
  13. info.getBucket().getCreationDate();
  14. // Obtain owner information.
  15. info.getBucket().getOwner();
  16. // Obtain permission information.
  17. info.getGrants();
  18. // Close your OSSClient.
  19. ossClient.shutdown();

Delete a bucket

Use the following code to delete a bucket:

  1. // This example uses endpoint China (Hangzhou). Specify the actual endpoint based on your requirements.
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
  4. String accessKeyId = "<yourAccessKeyId>";
  5. String accessKeySecret = "<yourAccessKeySecret>";
  6. // Create an OSSClient instance.
  7. OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
  8. // Delete a bucket. Before a bucket is deleted, ensure that all objects in the bucket, LiveChannel, and fragments that are generated from multipart upload are deleted.
  9. ossClient.deleteBucket("<yourBucketName>");
  10. // Close your OSSClient.
  11. ossClient.shutdown();
Thank you! We've received your feedback.