Manage a bucket

Last Updated: Aug 08, 2017

Create a bucket

You can use OSSClient.createBucket to create a bucket. The following code creates a bucket:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // The Alibaba Cloud account AccessKey gives you permission to access all APIs, so we suggest you follow Alibaba Cloud Best Practices and create and use an RAM sub-account for API access or daily O&M. To create an RAM sub-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 = "<your-oss-bucket-name>";
  10. ossClient.createBucket(bucketName);
  11. // Disable the client
  12. ossClient.shutdown();

Note:

  • For the bucket naming rules, refer to Basic concepts.
  • Because each bucket name must be globally unique, you should ensure that your bucket name is different from all others.

For the bucket created using the preceding code, the ACL is private-read-write. The Storage Class is Standard. You can specify Bucket ACL and Storage Class when creating a bucket. The example code is as below:

  1. CreateBucketRequest createBucketRequest= new CreateBucketRequest(bucketName);
  2. // Set the bucket ACL to public-read. The default ACL policy is private-read-write
  3. createBucketRequest.setCannedACL(CannedAccessControlList.PublicRead);
  4. // Set the bucket storage class as Low-frequency Access (IA). The default class is Standard
  5. createBucketRequest.setStorageClass(StorageClass.IA);
  6. ossClient.createBucket(createBucketRequest);

Notice: To create a bucket of a specified storage class, use Java SDK 2.6.0 or later versions.

List a bucket

You can use OSSClient.listBuckets to list buckets of a specified user.

Notice: If buckets of IA or Archive storage class exist, use Java SDK 2.6.0 or later versions.

Simple list

The following code lists the buckets of a specified user in simple mode:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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. // Disable the client
  14. ossClient.shutdown();

The code above can return a maximum of 100 buckets, which should meet users’ demands. When listing buckets, you can specify prefix, marker and maxkeys parameters and filter the list of buckets to implement flexible query features.

Parameter Role
prefix Only the buckets whose names match a specified prefix are returned. If this parameter is not specified, prefix information will not be used as a filter
marker Set the returned result to start with the first entry after the marker in alphabetical order. If this parameter is not specified, all entries are returned from the start
max-keys Limit the maximum number of buckets returned for one request. If this parameter is not specified, the default value 100 will apply. The value of max-keys cannot exceed 1,000

Specify a prefix for listing

  1. ListBucketsRequest listBucketsRequest = new ListBucketsRequest();
  2. listBucketsRequest.setPrefix("<yourBucketPrefix>");
  3. for (Bucket bucket : ossClient.listBuckets()) {
  4. System.out.println(" - " + bucket.getName());
  5. }

Specify the max keys for listing

  1. ListBucketsRequest listBucketsRequest = new ListBucketsRequest();
  2. listBucketsRequest.setMaxKeys(500);
  3. for (Bucket bucket : ossClient.listBuckets()) {
  4. System.out.println(" - " + bucket.getName());
  5. }

Delete a bucket

You can use OSSClient.deleteBucket to delete a bucket. The following code deletes a bucket:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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 the bucket
  9. ossClient.deleteBucket("<bucketName>");
  10. // Disable the client
  11. ossClient.shutdown();

Notice:

  • A non-empty bucket (which contains objects or object fragments from mulitpart uploads) cannot be deleted.
  • To delete a non-empty bucket, you must first delete all objects in it.

Determine whether a bucket exists

You can use the OSSClient.doesBucketExist interface to check whether the bucket already exists.

The following code checks whether a specified bucket exists:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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("<bucketName>");
  9. // Disable the client
  10. ossClient.shutdown();

Set the bucket ACL

Bucket ACLs are classified into three types: private, public-read and private-write, and public-read-write. You can use OSSClient.setBucketAcl to configure the ACL policy of a bucket.

ACL Java SDK values
Private-read-write CannedAccessControlList.Private
Public-read and private-write CannedAccessControlList.PublicRead
Public-read-write CannedAccessControlList.PublicReadWrite

The following code sets the ACL of a bucket:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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 bucket ACL
  9. ossClient.setBucketAcl("<bucketName>", CannedAccessControlList.Private);
  10. // Disable the client
  11. ossClient.shutdown();

Get the bucket ACL

You can use OSSClient.getBucketAcl to get the ACL policy of a bucket. The following code gets the ACL of a bucket:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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. AccessControlList acl = ossClient.getBucketAcl("<bucketName>");
  9. // Bucket ACL
  10. System.out.println(acl.toString());
  11. // Disable the client
  12. ossClient.shutdown();

Get the bucket location

The bucket location is also the bucket region. For details, see Region in the Basic concepts.

You can use OSSClient.getBucketLocation to get the bucket ACL. The following code gets the location of a bucket:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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("<bucketName>");
  9. System.out.println(location);
  10. // Disable the client
  11. ossClient.shutdown();

Get the bucket information

The bucket information includes the Location, CreationDate, Owner and ACL information.

The following code gets the info of a bucket:

  1. // Take the Hangzhou endpoint for example. Other regions can be filled in based on actual conditions
  2. String endpoint = "http://oss-cn-hangzhou.aliyuncs.com";
  3. // To view the accessKey, log on to https://ak-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. BucketInfo info = ossClient.getBucketInfo("<bucketName>");
  9. // Location
  10. info.getBucket().getLocation();
  11. // Date created
  12. info.getBucket().getCreationDate();
  13. // owner
  14. info.getBucket().getOwner();
  15. // ACL
  16. info.getGrants();
  17. // Disable the client
  18. ossClient.shutdown();
Thank you! We've received your feedback.