edit-icon download-icon


Last Updated: Apr 18, 2018

OSS uses buckets as the namespaces of user files. Similarly, buckets are also used as the management objects to perform the advanced functions such as charging, permission control, and log recording.

One application, such as an image sharing website, can correspond to one or more buckets. You can create a maximum of 10 buckets. However, each bucket can have an unlimited number of objects and can store up to 2 PB of data. Every object stored on OSS must be included in a bucket.

Naming rules

The bucket naming rules are as follows:

  • The bucket name must be globally unique and must not match with the bucket names of the other users.
  • It can only contain lower-case letters, numbers, and hyphens (-).
  • It must start with a lower-case letter or number.
  • The Bucket name length must be at least 3 and must not exceed 63 characters.

Create a bucket

You must follow the naming rules when you name a bucket.

You can use the following code to create a bucket:

  1. String bucketName = "my-bucket-name";
  2. // Initializes an OSSClient
  3. OSSClient client = ...;
  4. // Creates a Bucket
  5. client.createBucket(bucketName);

Listing all buckets

The following code lists all the buckets of the user:

  1. // Retrieves the user's bucket list
  2. List<Bucket> buckets = client.listBuckets();
  3. // Traverses buckets
  4. for (Bucket bucket : buckets) {
  5. System.out.println(bucket.getName());
  6. }

CNAME Access

As a user, direct your CNAME domain name to the domain name of one of your buckets and access OSS using your domain name:

  1. // For example, your domain name is "http://cname.com" and you direct the CNAME to your bucket domain name "mybucket.oss-cn-hangzhou.aliyuncs.com"
  2. OSSClient client = new OSSClient("http://cname.com/", /* accessKeyId */, /* accessKeySecret */);
  3. PutObjectResult result = client.putObject("mybucket", /* key */, /* input */, /* metadata */);

You must change the endpoint that is originally expected to be entered in the bucket to the post-CNAME domain name when creating an OSSClient instance. Note that when using this OSSClient instance for the subsequent operations, the bucket name can only be entered by the indicated bucket name.

Note: Being a VPC user, if you want to access OSS through a domain name that does not end with aliyuncs.com, use the setCnameExcludeList in the ClientConfiguration to set an endpoint and avoid using the CNAME method to access OSS.

Determine if a bucket exists

To determine if a bucket exists, use the following code:

  1. String bucketName = "your-bucket-name";
  2. // Gets information on existing buckets
  3. boolean exists = client.doesBucketExist(bucketName);
  4. // Outputs results
  5. if (exists) {
  6. System.out.println("Bucket exists");
  7. } else {
  8. System.out.println("Bucket not exists");
  9. }

Set a bucket ACL

To set the bucket ACL, use the following code:

  1. String bucketName = "your-bucket-name";
  2. //Uses a bucket with private permission as an example
  3. client.setBucketAcl(bucketName,CannedAccessControlList.Private);

Retrieve a bucket ACL

To retrieve the bucket ACL, use the following code:

  1. String bucketName = "your-bucket-name";
  2. AccessControlList accessControlList = client.getBucketAcl(bucketName);
  3. //You can print the results or confirm them on the console
  4. System.out.println(accessControlList.toString());

Retrieve bucket addresses

To retrieve the bucket address, use the following code:

  1. String bucketName = "your-bucket-name";
  2. // Retrieves the bucket address
  3. String location = client.getBucketLocation(bucketName);
  4. System.out.println(location);

Delete a bucket

To delete a bucket, use the following code:

  1. String bucketName = "your-bucket-name";
  2. // Deletes the bucket
  3. client.deleteBucket(bucketName)

You can only delete an empty bucket. A bucket that contains objects, cannot be deleted. Therefore, be sure you delete all objects in a bucket before deleting a bucket.

Thank you! We've received your feedback.