简介

本文档提供关于存储桶的基本操作和访问控制列表（ACL）的相关 API 概览以及 SDK 示例代码。

基本操作

访问控制列表

基本操作

查询存储桶列表

功能说明

GET Service 接口是用来查询请求者名下的所有存储桶列表或特定地域下的存储桶列表（Bucket list），详情请参见 GET Service。

使用示例

示例一：列出存储桶列表。

cos.getService(function(err, data) {
    console.log(err || data);
});

示例二：列出指定地域的存储桶列表。

cos.getService({
    Region: 'COS_REGION',
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

创建存储桶

功能说明

PUT Bucket 接口请求可以在指定账号下创建一个存储桶。

使用示例

cos.putBucket({
    Bucket: 'examplebucket-1250000000',
    Region: 'COS_REGION'
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

检索存储桶及其权限

功能说明

HEAD Bucket 请求可以确认该存储桶是否存在，是否有权限访问。有以下几种情况：

• 存储桶存在且有读取权限，返回 HTTP 状态码200。
• 无存储桶读取权限，返回 HTTP 状态码403。
• 存储桶不存在，返回 HTTP 状态码404。

使用示例

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

参数说明

回调函数说明

function(err, data) { ... }

删除存储桶

功能说明

删除指定账号下的空存储桶。注意，如果删除成功，则返回的 HTTP 状态码为200或204。

说明：

删除存储桶前，请确保存储桶内的数据和未完成上传的分块数据已全部清空，否则会无法删除存储桶。

使用示例

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

参数说明

回调函数说明

function(err, data) { ... }

访问控制列表

设置存储桶 ACL

功能说明

PUT Bucket acl 接口用来设置指定存储桶访问权限控制列表（ACL）。

使用示例

设置存储桶公有读：

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

为某个用户赋予存储桶所有权限：

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

通过 AccessControlPolicy 修改存储桶权限：

cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', /* 必须 */
    Region: 'COS_REGION',    /* 必须 */
    AccessControlPolicy: {
        "Owner": { // AccessControlPolicy 里必须有 owner
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 是 Bucket 所属用户的 Uin
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 是 Uin
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});

参数说明

回调函数说明

function(err, data) { ... }

查询存储桶 ACL

功能说明

GET Bucket acl 接口用来查询存储桶的访问控制列表（ACL）。该 API 的请求者需要对存储桶有写入 ACL 权限。

使用示例

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

返回示例

{
    "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": {}
}

参数说明

回调函数说明

function(err, data) { ... }