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
| API | Operation | Description |
|---|---|---|
| GET Service | Querying bucket list | Queries the list of all buckets under the specified account |
| PUT Bucket | Creating a bucket | Creates a bucket under the specified account |
| HEAD Bucket | Checking a bucket and its permission | Checks whether a bucket exists and you have permission to access it |
| DELETE Bucket | Deleting a bucket | Deletes an empty bucket under the specified account |
ACL
| API | Operation | Description |
|---|---|---|
| PUT Bucket acl | Sets a bucket ACL | Sets an ACL for a bucket |
| GET Bucket acl | Gets the bucket ACL | Gets the ACL of a bucket |
This API is used to query the list of all buckets under the specified account.
public List<Bucket> listBuckets() throws CosClientException, CosServiceException;None.
-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.
List<Bucket> buckets = cosClient.listBuckets();
for (Bucket bucketElement : buckets) {
String bucketName = bucketElement.getName();
String bucketLocation = bucketElement.getLocation();
}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.
public Bucket createBucket(String bucketName) throws CosClientException, CosServiceException;| Parameter Name | Description | Type |
|---|---|---|
| bucketName | Bucket naming rule is BucketName-APPID. For details, see Bucket Overview | String |
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.
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);This API is used to check whether a bucket exists and you have permission to access it.
public boolean doesBucketExist(String bucketName)
throws CosClientException, CosServiceException;| Parameter Name | Description | Type |
|---|---|---|
| bucketName | Bucket naming rule is BucketName-APPID. For details, see Bucket Overview | String |
The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
boolean bucketExistFlag = cosClient.doesBucketExist(bucketName);This API is used to delete the empty bucket under the specified account.
public void deleteBucket(String bucketName) throws CosClientException, CosServiceException;| Parameter Name | Description | Type |
|---|---|---|
| bucketName | Bucket naming rule is BucketName-APPID. For details, see Bucket Overview | String |
The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
cosClient.deleteBucket(bucketName);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 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;Parameters in the third method include that in method 1 and 2. Method 3 is used as an example.
| Parameter Name | Description | Type |
|---|---|---|
| setBucketAclRequest | Class for requesting permission configuration | SetBucketAclRequest |
Request member description:
| Request Member | Set Method | Description | Type |
|---|---|---|---|
| bucketName | Constructor or set method | Bucket naming rule is BucketName-APPID. For details, see Bucket Overview | String |
| acl | Constructor or set method | Custom permission policy | AccessControlList |
| cannedAcl | Constructor or set method | Predefined policies, such as public read, public read and write, private read | CannedAccessControlList |
| Member Name | Description | Type |
|---|---|---|
| List<Grant> | Contains information of all users to be authorized | Array |
| owner | The owner of the Object or Owner | Owner class |
Grant type members description:
| Member Name | Description | Type |
|---|---|---|
| grantee | Grantee identity information | Grantee |
| permission | Authorized permission information (such as readable, writable, readable & writable) | Permission |
Owner type member description:
| Member Name | Description | Type |
|---|---|---|
| id | Identity information of an owner | String |
| displayname | Owner's name (same as id) | String |
CannedAccessControlList represents a preset policy for everyone. It is an enumeration type with the following enumerated values.
| Enumerated Value | Description |
|---|---|
| Private | Private read and write (only owner can read and write) |
| PublicRead | Public read and private write (owner can read and write, and other users can read) |
| PublicReadWrite | Public read and write (everyone can read and write) |
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);This API is used to query the access control list of the specified bucket.
public AccessControlList getBucketAcl(String bucketName)
throws CosClientException, CosServiceException| Parameter Name | Description | Type |
|---|---|---|
| bucketName | Bucket naming format is BucketName-APPID. For details, see Bucket Overview | String |
The bucket name entered must be in a format of {name}-{appid}
String bucketName = "examplebucket-1250000000";
AccessControlList accessControlList = cosClient.getBucketAcl(bucketName);
// Get bucket permission in the form of preset ACL. Valid values: Private, PublicRead, PublicReadWrite
CannedAccessControlList cannedAccessControlList = accessControlList.getCannedAccessControl();
Was this page helpful?