Actions on Buckets

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

ACL

Basic Operations

Retrieving Information on a Bucket and Its Permission

Feature Description

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

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

Samples

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 (DELETE Bucket) is used to delete an empty bucket under a specified account. If the deletion succeeds, HTTP status code 200 or 204 will be returned.

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.

Samples

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 (PUT Bucket ACL) is used to set the access control list ( ACL) for the specified bucket.

Samples

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 (GET Bucket ACL) is used to get the ACL of the specified bucket. To make this request, you need to have the permission to access the ACL of the bucket.

Samples

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

Parameter Description

Callback Function Description

function(err, data) { ... }