Actions on Buckets

Introduction

This document provides an overview of APIs and SDK code samples related to basic operations on buckets and bucket access control list (ACL).

Basic Operations

ACL

Basic Operations

Querying bucket list

Feature

This API is used to query the list of all buckets under the specified account.

Method Prototype

public List<Bucket> listBuckets() throws CosClientException, CosServiceException;

Parameter Description

None.

Returned Result

-Success: A list of all Bucket classes will be returned. The Bucket class contains information about bucket member, location and more.
-Failure: An error occurs (such as the bucket does not exist), with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

Request Samples

List<Bucket> buckets = cosClient.listBuckets();
for (Bucket bucketElement : buckets) {
    String bucketName = bucketElement.getName();
    String bucketLocation = bucketElement.getLocation();
}

Creating a Bucket

Feature

This API is used to create a bucket under the specified account. You can create multiple buckets under the same user account. The maximum number is 200 (regardless of region). There is no limit to the number of objects in the bucket. Bucket creation is a low-frequency operation. We recommended you create a bucket in the console and perform object operations in the SDK.

Method Prototype

public Bucket createBucket(String  bucketName) throws CosClientException, CosServiceException;

Parameter Description

Returned Result

Successful: Bucket type, including the description of Bucket (bucket name, owner, and creation date).
-Failure: An error occurs (such as authentication failure), with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

Request Samples

String bucket = "examplebucket-1250000000"; // Bucket name in the format of BucketName-APPID
CreateBucketRequest createBucketRequest = new CreateBucketRequest(bucket);
// Set the bucket permission to PublicRead (public read and private write). Other options include private read/write and public read/write
createBucketRequest.setCannedAcl(CannedAccessControlList.PublicRead);
Bucket bucketResult = cosClient.createBucket(createBucketRequest);

Retrieving information on a bucket and its permission

Feature

This API is used to check whether a bucket exists and you have permission to access it.

Method Prototype

public boolean doesBucketExist(String bucketName) 
  throws CosClientException, CosServiceException;

Parameter Description

Returned Result

• Successful: "true" is returned if the queried bucket exists. Otherwise, "false" is returned.
• Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

Request Samples

The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
boolean bucketExistFlag = cosClient.doesBucketExist(bucketName);

Deleting a bucket

Feature

This API is used to delete the empty bucket under the specified account.

Method Prototype

public void deleteBucket(String bucketName) throws CosClientException, CosServiceException;

Parameter Description

Returned Result

• Successful: No value is returned.
• Failure: An error (such as authentication failure) occurs, with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

Request Samples

The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
cosClient.deleteBucket(bucketName);

ACL

Setting Bucket ACL

Feature

This API (PUT Bucket acl) is used to set the access control list (ACL) for a specified bucket. This operation will overwrite existing permission configurations. ACL includes a predefined permission policy (CannedAccessControlList) or a custom permission control (AccessControlList). When two types of permissions are configured at the same time, predefined policies are ignored and custom policies will be used.

Method Prototype

// Method 1 (Set custom policy)
public void setBucketAcl(String bucketName, AccessControlList acl)
  throws CosClientException, CosServiceException;
// Method 2 (Set predefined policy)
public void setBucketAcl(String bucketName, CannedAccessControlList acl) throws CosClientException, CosServiceException;
// Method 3 (Encapsulation of the two methods above, including setting of these two policies. If both of them are set, the custom policy prevails.)
public void setBucketAcl(SetBucketAclRequest setBucketAclRequest) 
  throws CosClientException, CosServiceException;

Parameter Description

Parameters in the third method include that in method 1 and 2. Method 3 is used as an example.

Request member description:

Grant type members description:

Owner type member description:

CannedAccessControlList represents a preset policy for everyone. It is an enumeration type with the following enumerated values.

Returned Result

• Successful: No value is returned.
• Failure: An error occurs (such as authentication failure), with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

Request Samples

The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
// Setting a custom ACL
AccessControlList acl = new AccessControlList();
Owner owner = new Owner();
owner.setId("qcs::cam::uin/100000000001:uin/100000000001");
acl.setOwner(owner);
<ID>qcs::cam::uin/100000000002:uin/100000000002</ID>
UinGrantee uinGrantee = new UinGrantee("qcs::cam::uin/2779643970:uin/2779643970");
uinGrantee.setIdentifier(id);
acl.grantPermission(uinGrantee, Permission.FullControl);
cosClient.setBucketAcl(bucketName, acl);

// Setting a predefined ACL
// Setting private read and write (New buckets are configured with private read and write by default)
cosClient.setBucketAcl(bucketName, CannedAccessControlList.Private);
// Setting public read and private write
cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicRead);
// Setting public read and write
cosClient.setBucketAcl(bucketName, CannedAccessControlList.PublicReadWrite);

Querying bucket ACL

Feature

This API is used to query the access control list of the specified bucket.

Method Prototype

public AccessControlList getBucketAcl(String bucketName)
       throws CosClientException, CosServiceException

Parameter Description

Returned Result

• Successful: The ACL of a Bucket is returned.
• Failure: An error occurs (such as authentication failure), with a CosClientException or CosServiceException exception. For details, see Troubleshooting.

Request Samples

The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
AccessControlList acl = cosClient.getBucketAcl(bucketName);