Overview

This document provides an overview of APIs and SDK sample codes related to basic bucket operations and access control lists (ACL).

Basic operations

ACL

Basic operations

Retrieving information on a bucket and its permissions

Feature description

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

• HTTP status code 200 will be returned if the bucket exists and you have access permission.
• HTTP status code 403 will be returned if you do not have permission to access the bucket.
• HTTP status code 404 will be returned if the bucket does not exist.

Use case

cos.headBucket({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',     /* Bucket region. Required */
},function (err,data) {
    console.log(err || data);
});

Parameter description

Callback function description

},function (err,data) {

Deleting a bucket

Feature description

This API is used to delete an empty bucket under a specified account. Note that if the deletion is successful, the returned HTTP status code will be 200 or 204.

Before deleting a bucket, please make sure that all the data and incomplete multipart uploads in the bucket have been deleted; otherwise, the bucket cannot be deleted.

Use case

cos.deleteBucket({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',     /* Bucket region. Required */
},function (err,data) {
    console.log(err || data);
});

Parameter description

Callback function description

},function (err,data) {

ACL

Setting bucket ACL

Feature description

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

Use case

Set a bucket to allow public-read:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',     /* Bucket region. Required */
    ACL: 'public-read'
},function (err,data) {
    console.log(err || data);
});

Grant a user full access to a bucket:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',     /* Bucket region. Required */
    GrantFullControl: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000011:uin/100000000011"' // 100000000001 is UIN
},function (err,data) {
    console.log(err || data);
});

Modify bucket permission with AccessControlPolicy:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',     /* Bucket region. Required */
    AccessControlPolicy={
        "Owner": { // `Owner` is required in `AccessControlPolicy`
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
        },
        "Grants": [{
            'Grantee': {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is UIN
            },
            "Permission": "WRITE"
        }]
    }
},function (err,data) {
    console.log(err || data);
});

Parameter description

Callback function description

},function (err,data) {

Querying bucket ACL

Feature description

This API is used to query the ACL of a specified bucket. To make this request, you need to have permission to access the ACL of the bucket.

Use case

cos.getBucketAcl({
    Bucket: 'examplebucket-1250000000', /*Required*/
    Region: 'COS_REGION',     /* Bucket region. Required */
},function (err,data) {
    console.log(err || data);
});

Sample Response

{
    "GrantFullControl": "",
    "GrantWrite": "",
    "GrantRead": "",
    "GrantReadAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
    "GrantWriteAcp": "id=\"qcs::cam::uin/100000000011:uin/100000000011\"",
    "ACL": "private",
    'Owner': {
        "ID": "qcs::cam::uin/100000000001:uin/100000000001",
        [DisplayName] => qcs::cam::uin/100000000001:uin/100000000001
    },
    "Grants": [{
        'Grantee': {
            "ID": "qcs::cam::uin/100000000001:uin/100000000001",
            [DisplayName] => qcs::cam::uin/100000000001:uin/100000000001
        },
        "Permission": "READ"
    }],
    "statusCode": 200,
    "headers": {}
}

Parameter description

Callback function description

},function (err,data) {