Access Control

Last updated: 2020-06-04 15:49:04

    Overview

    This document provides an overview of APIs and SDK code samples related to bucket and object access control lists (ACL).

    Bucket ACL

    API Operation Description
    PUT Bucket acl Setting a bucket ACL Sets the ACL for a specified bucket
    GET Bucket acl Querying a bucket ACL Gets the ACL of a specified bucket

    Object ACL

    API Operation Description
    PUT Object acl Setting object ACL Sets the ACL for a specified object in a bucket
    GET Object acl Querying object ACL Queries the ACL of an object

    Bucket ACL

    Setting bucket ACL

    Feature

    This API (PUT Bucket acl) is used to set the access control list (ACL) for a specified bucket.

    Method prototype

    PutBucketACLResult putBucketACL(PutBucketACLRequest request) throws CosXmlClientException, CosXmlServiceException;
    
    void putBucketACLAsync(PutBucketACLRequest request, CosXmlResultListener cosXmlResultListener);

    Request samples

    String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
    PutBucketACLRequest putBucketACLRequest = new PutBucketACLRequest(bucket);
    
    // Set the bucket's access permission
    putBucketACLRequest.setXCOSACL("public-read");
    
    // Grant read permission to the grantee
    ACLAccount readACLS = new ACLAccount();
    readACLS.addAccount("100000000001", "100000000001");
    putBucketACLRequest.setXCOSGrantRead(readACLS);
    
    // Grant write permission to the grantee
    ACLAccount writeACLS = new ACLAccount();
    writeACLS.addAccount("100000000001", "100000000001");
    putBucketACLRequest.setXCOSGrantWrite(writeACLS);
    
    // Grant read and write permissions to the grantee
    ACLAccount writeandReadACLS = new ACLAccount();
    writeandReadACLS.addAccount("100000000001", "100000000001");
    putBucketACLRequest.setXCOSReadWrite(writeandReadACLS);
    // Set the host for signature verification, which verifies all headers by default
    Set<String> headerKeys = new HashSet<>();
    headerKeys.add("Host");
    putBucketACLRequest.setSignParamsAndHeaders(null, headerKeys);
    // Use the sync method
    try {
        PutBucketACLResult putBucketACLResult = cosXmlService.putBucketACL(putBucketACLRequest);
    } catch (CosXmlClientException e) {
        e.printStackTrace();
    } catch (CosXmlServiceException e) {
        e.printStackTrace();
    }
    
    // Use async callback to make requests
    cosXmlService.putBucketACLAsync(putBucketACLRequest, new CosXmlResultListener() {
        @Override
        public void onSuccess(CosXmlRequest request, CosXmlResult result) {
            PutBucketACLResult putBucketACLResult = (PutBucketACLResult) result;
        }
    
        @Override
        public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException) {
            // todo Put Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
        }
    });

    When initiating a request, if you want to use a calculated signature string, you can do so by calling putBucketACLRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Name of the bucket on which the ACL is set. Format: BucketName-APPID string
    cosAcl SetCosAcl Sets the ACL permissions for the bucket string
    grantAccount SetXCosGrantRead, SetXCosGrantWrite, or SetXCosReadWrite Grants users read and write permissions GrantAccount
    headerKeys setSignParamsAndHeaders Indicates whether to verify the headers for the signature Set<String>
    queryParameterKeys setSignParamsAndHeaders Indicates whether to verify the query parameters in the request URL for the signature Set<String>
    cosXmlResultListener putBucketACLAsync Result callback CosXmlResultListener

    Response description

    The result of the request is returned through PutBucketACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code between 200-300 indicates a successful operation. Other values indicate a failure.

    If the operation fails, the SDK will throw CosXmlClientException or CosXmlServiceException.

    Querying bucket ACL

    Feature

    This API (GET Bucket acl) is used to query the access control list (ACL) of a specified bucket.

    Method prototype

    GetBucketACLResult getBucketACL(GetBucketACLRequest request) throws CosXmlClientException, CosXmlServiceException;
    
    void getBucketACLAsync(GetBucketACLRequest request, CosXmlResultListener cosXmlResultListener);

    Request samples

    String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
    GetBucketACLRequest getBucketACLRequest = new GetBucketACLRequest(bucket);
    // Set the host for signature verification, which verifies all headers by default
    Set<String> headerKeys = new HashSet<>();
    headerKeys.add("Host");
    getBucketACLRequest.setSignParamsAndHeaders(null, headerKeys);
    // Use the sync method
    try {
        GetBucketACLResult getBucketACLResult = cosXmlService.getBucketACL(getBucketACLRequest);
    } catch (CosXmlClientException e) {
        e.printStackTrace();
    } catch (CosXmlServiceException e) {
        e.printStackTrace();
    }
    
    // Use async callback to make requests
    cosXmlService.getBucketACLAsync(getBucketACLRequest, new CosXmlResultListener() {
        @Override
        public void onSuccess(CosXmlRequest request, CosXmlResult result) {
            GetBucketACLResult getBucketACLResult = (GetBucketACLResult) result;
        }
    
        @Override
        public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException) {
            // todo Get Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
        }
    });

    When initiating a request, if you want to use a calculated signature string, you can do so by calling getBucketACLRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Bucket name. Format: BucketName-APPID string
    headerKeys setSignParamsAndHeaders Indicates whether to verify the headers for the signature Set<String>
    queryParameterKeys SetSign Indicates whether to verify the query parameters in the request URL for the signature Set<String>
    cosXmlResultListener getBucketACLAsync Result callback CosXmlResultListener

    Response description

    The result of the request is returned through GetBucketACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code between 200-300 indicates a successful operation. Other values indicate a failure.
    accessControlPolicy AccessControlPolicy The information of the bucket ACL is returned

    If the operation fails, the SDK will throw CosXmlClientException or CosXmlServiceException.

    Object ACL

    Setting object ACL

    Feature

    This API (PUT Object acl) is used to set an access control list (ACL) for an object in a bucket.

    Method prototype

    PutObjectACLResult putObjectACL(PutObjectACLRequest request) throws CosXmlClientException, CosXmlServiceException;
    
    void putObjectACLAsync(PutObjectACLRequest request, final CosXmlResultListener cosXmlResultListener);

    Request samples

    String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
    String cosPath = "exampleobject"; // The location identifier of the object in the bucket, i.e. the object key. For example, cosPath = "text.txt";
    PutObjectACLRequest putObjectACLRequest = new PutObjectACLRequest(bucket, cosPath);
    
    // Set the bucket's access permission
    putObjectACLRequest.setXCOSACL("public-read");
    
    // Grant read permission to the grantee
    ACLAccount readACLS = new ACLAccount();
    readACLS.addAccount("100000000001", "100000000001");
    putObjectACLRequest.setXCOSGrantRead(readACLS);
    
    // Grant read and write permissions to the grantee
    ACLAccount writeandReadACLS = new ACLAccount();
    writeandReadACLS.addAccount("100000000001", "100000000001");
    putObjectACLRequest.setXCOSReadWrite(writeandReadACLS);
    // Set the host for signature verification, which verifies all headers by default
    Set<String> headerKeys = new HashSet<>();
    headerKeys.add("Host");
    putObjectACLRequest.setSignParamsAndHeaders(null, headerKeys);
    // Use the sync method
    try {
        PutObjectACLResult putObjectACLResult = cosXmlService.putObjectACL(putObjectACLRequest);
    } catch (CosXmlClientException e) {
        e.printStackTrace();
    } catch (CosXmlServiceException e) {
        e.printStackTrace();
    }
    
    // Use async callback to make requests
    cosXmlService.putObjectACLAsync(putObjectACLRequest, new CosXmlResultListener() {
        @Override
        public void onSuccess(CosXmlRequest request, CosXmlResult result) {
            PutObjectACLResult putObjectACLResult = (PutObjectACLResult) result;
        }
    
        @Override
        public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException) {
            // todo Put Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
        }
    });

    When initiating a request, you can use a calculated signature string by calling putObjectACLRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Name of the bucket where the object resides. Format: BucketName-APPID String
    cosPath Constructor or SetCosPath The location identifier (object key) of the object in the bucket String
    cosAcl SetCosAcl Sets the ACL permissions for a bucket String
    grantAccount SetXCosGrantRead or SetXCosReadWrite Grants users read and write permissions GrantAccount
    headerKeys setSignParamsAndHeaders Indicates whether to verify the headers for the signature Set<String>
    queryParameterKeys SetSign Indicates whether to verify the query parameters in the request URL for the signature Set<String>
    cosXmlResultListener putObjectACLAsync Result callback CosXmlResultListener

    Response description

    The result of the request is returned through PutObjectACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code between [200, 300) indicates a successful operation. Other values indicate a failure.

    If the operation fails, the SDK will throw CosXmlClientException or CosXmlServiceException.

    Querying object ACL

    Feature

    This API (GET Object acl) is used to query the ACL of an object.

    Method prototype

    GetObjectACLResult getObjectACL(GetObjectACLRequest request) throws CosXmlClientException, CosXmlServiceException;
    
    void getObjectACLAsync(GetObjectACLRequest request, CosXmlResultListener cosXmlResultListener);

    Request samples

    String bucket = "examplebucket-1250000000"; // Format: BucketName-APPID
    String cosPath = "exampleobject"; //The location identifier of the object in the bucket, i.e. the object key. For example, cosPath = "text.txt";
    GetObjectACLRequest getBucketACLRequest = new GetObjectACLRequest(bucket, cosPath);
    // Set the host for signature verification, which verifies all headers by default
    Set<String> headerKeys = new HashSet<>();
    headerKeys.add("Host");
    getBucketACLRequest.setSignParamsAndHeaders(null, headerKeys);
    // Use the sync method
    try {
        GetObjectACLResult getObjectACLResult = cosXmlService.getObjectACL(getBucketACLRequest);
    } catch (CosXmlClientException e) {
        e.printStackTrace();
    } catch (CosXmlServiceException e) {
        e.printStackTrace();
    }
    
    // Use async callback to make requests
    cosXmlService.getObjectACLAsync(getBucketACLRequest, new CosXmlResultListener() {
        @Override
        public void onSuccess(CosXmlRequest request, CosXmlResult result) {
            GetObjectACLResult getObjectACLResult = (GetObjectACLResult) result;
        }
    
        @Override
        public void onFail(CosXmlRequest cosXmlRequest, CosXmlClientException clientException, CosXmlServiceException serviceException) {
            // todo Get Bucket ACL failed because of CosXmlClientException or CosXmlServiceException...
        }
    });

    When initiating a request, if you want to use a calculated signature string, you can do so by calling getBucketACLRequest.setSign ("calculated signature string"). The signature string will be calculated by the SDK by default.

    Parameter description

    Parameter Name Setting Method Description Type
    bucket Constructor Name of the bucket where the object resides. Format: BucketName-APPID String
    cosPath Constructor or SetCosPath The location identifier (object key) of the object in the bucket String
    headerKeys setSignParamsAndHeaders Indicates whether to verify the headers for the signature Set<String>
    queryParameterKeys SetSign Indicates whether to verify the query parameters in the request URL for the signature Set<String>
    cosXmlResultListener getObjectACLAsync Result callback CosXmlResultListener

    Response description

    The result of the request is returned through GetObjectACLResult.

    Member Variable Type Description
    httpCode int HTTP Code. A code between [200, 300) indicates a successful operation. Other values indicate a failure.
    accessControlPolicy AccessControlPolicy The information of the object ACL is returned

    If the operation fails, the SDK will throw CosXmlClientException or CosXmlServiceException.

    Was this page helpful?

    Was this page helpful?

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