Actions on Buckets

Overview

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

Basic operations

ACL

Basic Operations

Checking a Bucket and Its Permission

Feature Description

This API (Head Bucket) is used to confirm whether a bucket exists and you have permission to access it. The permission of Head is the same as that of Read. If the bucket exists, HTTP status code 200 is returned. If you have no permission to access it, HTTP status code 403 is returned. If it does not exist, HTTP status code 404 is returned.

Use Cases

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

Parameter Descriptions

Callback Function Description

function(err, data) { ... }

Deleting a Bucket

Feature Description

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

Use Cases

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

Parameter Descriptions

Callback Function Description

function(err, data) { ... }

ACL

Setting Bucket ACL

Feature Description

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

Use Cases

Set a bucket to public-read:

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

Grant a user read/write permission to a bucket:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /* Required */
    Region: 'ap-beijing',    /* 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);
});

Grant a user read/write permission to a bucket:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /* Required */
    Region: 'ap-beijing',    /* 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 permissions with AccessControlPolicy:

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /* Required */
    Region: 'ap-beijing',    /* Required */
    AccessControlPolicy: {
        "Owner": { // There must be an owner in AccessControlPolicy
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the Uin of the user owning the bucket
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is Uin
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});

Parameter Descriptions

Callback Function Description

function(err, data) { ... }

Querying Bucket ACL

Feature Description

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

Use Cases

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

Return Example

{
    "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/100000000011:uin/100000000011",
            "DisplayName": "qcs::cam::uin/100000000011:uin/100000000011"
        },
        "Permission": "READ"
    }],
    "statusCode": 200,
    "headers": {}
}

Parameter Descriptions

Callback Function Description

function(err, data) { ... }