Bucket Operations

Last updated: 2020-06-16 17:52:13

    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

    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

    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

    Parameter Name Description Type
    bucketName Bucket naming rule is BucketName-APPID. For details, see Bucket Overview String

    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

    Parameter Name Description Type
    bucketName Bucket naming rule is BucketName-APPID. For details, see Bucket Overview String

    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

    Parameter Name Description Type
    bucketName Bucket naming rule is BucketName-APPID. For details, see Bucket Overview String

    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.

    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)

    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

    Parameter Name Description Type
    bucketName Bucket naming format is BucketName-APPID. For details, see Bucket Overview String

    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 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?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help