对象存储存储桶操作-SDK 文档-文档中心-腾讯云

简介
本文介绍对象存储 COS 通过 Node.js SDK 实现查询存储桶列表、创建存储桶、检索存储桶、删除存储桶的示例代码和描述。
注意事项
在您使用存储桶相关操作之前，需要先具有相关权限，具体而言：
若想查询存储桶列表，在您进行 授权策略 时，action 需要设置为 cos:GetService ，更多授权请参见 支持CAM的业务接口。
若想创建存储桶，在您进行 授权策略 时，action 需要设置为 cos:PutBucket ，更多授权请参见 支持CAM的业务接口。
若想检索存储桶，在您进行 授权策略 时，action 需要设置为 cos:HeadBucket ，更多授权请参见 支持CAM的业务接口。
若想删除存储桶，在您进行 授权策略 时，action 需要设置为 cos:DeleteBucket ，更多授权请参见 支持CAM的业务接口。
前期准备
开始上传前，确保您已经完成了 SDK 初始化。
使用案例
查询存储桶列表
列出存储桶列表
cos.getService(function(err, data) {
    console.log(err || data);
});
列出指定地域的存储桶列表
cos.getService({
    Region: 'COS_REGION',
}, function(err, data) {
    console.log(err || data);
});
列出指定标签的存储桶列表。（sdk v2.13.4 版本开始支持）
cos.getService({
    TagKey: 'type',
    TagValue: 'app',
    MaxKeys: 10, // 只返回 10 条记录
}, function(err, data) {
    console.log(err || data);
});
列出指定日期前创建的存储桶列表。（sdk v2.13.4 版本开始支持）
cos.getService({
    // 查询 2024-01-01前创建的存储桶列表
    CreateTime: 1704038400,
    CreateRange: 'lt',
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
否
Tagkey
支持根据存储桶标签过滤存储桶，仅支持传入一个存储桶标签，tagkey 用于传入标签键。（ sdk v2.13.4 版本开始支持）
string
否
Tagvalue
支持根据存储桶标签过滤存储桶，仅支持传入一个存储桶标签，tagvalue 用于传入标签值。（sdk v2.13.4 版本开始支持）
string
否
CreateTime
GMT 时间戳，和 CreateRange 参数一起使用，支持根据创建时间过滤存储桶，例如 CreateTime=1642662645 。（sdk v2.13.4 版本开始支持）
number
否
CreateRange
和 create-time 参数一起使用，支持根据创建时间过滤存储桶，支持枚举值 lt（创建时间早于 create-time）、gt（创建时间晚于 create-time）、lte（创建时间早于或等于 create-time）、gte（创建时间晚于或等于create-time）。（sdk v2.13.4 版本开始支持）
string
否
Marker
起始标记，从该标记之后（不含）按照 UTF-8 字典序返回存储桶条目。（sdk v2.13.4 版本开始支持）
string
否
MaxKeys
单次返回最大的条目数量，默认值为2000，最大为2000。如果单次响应中未列出所有存储桶，COS 会返回 NextMarker 节点，其值作为下次 GetService 请求的 marker 参数。（sdk v2.13.4 版本开始支持）
number
否
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误，如果请求成功则为空，更多详情请参见 错误码
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- RequestId
请求 ID
String
- Owner
代表存储桶所有者的对象
Object
- - ID
存储桶持有者的完整 ID，格式为qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]，
例如qcs::cam::uin/100000000001:uin/100000000001，其中100000000001为 uin
String
- - DisplayName
存储桶持有者的名称
String
- Buckets
存储桶信息列表
Object
- - Name
存储桶的名称，格式为 <BucketName-APPID>，例如 examplebucket-1250000000
String
- - Location
存储桶所在地域。枚举值请参见 地域和访问域名 文档，例如 ap-guangzhou，ap-beijing，ap-hongkong 等
String
- - CreationDate
存储桶创建时间，为 ISO8601 格式，例如2019-05-24T10:56:40Z
String
创建存储桶
cos.putBucket({
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION',  // 存储桶所在地域，例如 ap-beijing，必须字段
    // BucketAZConfig: 'MAZ', // 可选，支持设置存储桶为多az
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
ACL
定义存储桶的访问控制列表（ACL）属性。枚举值请参见 ACL 概述 文档中存储桶的预设 ACL 部分，例如 private，public-read 等，默认为 private
String
否
GrantRead
赋予被授权者读取存储桶的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantWrite
赋予被授权者写入存储桶的权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantReadAcp
赋予被授权者读取存储桶的访问控制列表（ACL）和存储桶策略（Policy）的权限。可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantWriteAcp
赋予被授权者写入存储桶的访问控制列表（ACL）和存储桶策略（Policy）的权限，可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
GrantFullControl
赋予被授权者操作存储桶的所有权限，格式：id="[OwnerUin]"，可使用半角逗号（,）分隔多组被授权者：
当需要给子账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
当需要给主账号授权时，id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
例如'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
否
BucketAZConfig
设置存储桶为多az
String
否
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误，如果请求成功则为空，更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- RequestId
请求 ID
String
检索存储桶及其权限
cos.headBucket({
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION',  // 存储桶所在地域，例如 ap-beijing，必须字段
}, function(err, data) {
    if (err && err.statusCode == 403) {
        console.log('没有该存储桶读权限');
    }
});
判断存储桶是否存在
function doesBucketExist() {
    cos.headBucket({
        Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
        Region: 'COS_REGION',  // 存储桶所在地域，例如 ap-beijing，必须字段
    }, function(err, data) {
        if (data) {
            console.log('存储桶存在');
        }
    });
}
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误，如果请求成功则为空，更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- RequestId
请求 ID
String
返回结果说明
当该存储桶存在且有读取权限时，返回 HTTP 状态码200。
当该存储桶无读取权限时，返回 HTTP 状态码403。
当该存储桶不存在时，返回 HTTP 状态码404。
删除存储桶
说明：
删除存储桶前，请确保存储桶内的数据和未完成上传的分块数据已全部清空，否则会无法删除存储桶。
cos.deleteBucket({
    Bucket: 'examplebucket-1250000000', // 填入您自己的存储桶，必须字段
    Region: 'COS_REGION',  // 存储桶所在地域，例如 ap-beijing，必须字段
}, function(err, data) {
    console.log(err || data);
});
参数说明
参数名
参数描述
类型
是否必填
Bucket
存储桶的名称，命名格式为 BucketName-APPID，此处填写的存储桶名称必须为此格式
String
是
Region
存储桶所在地域，枚举值请参见 地域和访问域名
String
是
回调函数说明
function(err, data) { ... }
参数名
参数描述
类型
err
请求发生错误时返回的对象，包括网络错误和业务错误，如果请求成功则为空，更多详情请参见 错误码 文档
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
data
请求成功时返回的对象，如果请求发生错误，则为空
Object
- statusCode
请求返回的 HTTP 状态码，例如200、403、404等
Number
- headers
请求返回的头部信息
Object
- RequestId
请求 ID
String
返回结果说明
如果删除成功，返回的 HTTP 状态码为200或204。
API 操作
关于查询存储桶列表的API 接口说明，请参见 GET Service (List Buckets) 文档。
关于创建存储桶的API 接口说明，请参见 PUT Bucket 文档。
关于检索存储桶的API 接口说明，请参见 HEAD Bucket 文档。
关于删除存储桶的API 接口说明，请参见 DELETE Bucket 文档。

参数名	参数描述	类型	是否必填
Region	存储桶所在地域，枚举值请参见地域和访问域名	String	否
Tagkey	支持根据存储桶标签过滤存储桶，仅支持传入一个存储桶标签，tagkey 用于传入标签键。（ sdk v2.13.4 版本开始支持）	string	否
Tagvalue	支持根据存储桶标签过滤存储桶，仅支持传入一个存储桶标签，tagvalue 用于传入标签值。（sdk v2.13.4 版本开始支持）	string	否
CreateTime	GMT 时间戳，和 CreateRange 参数一起使用，支持根据创建时间过滤存储桶，例如 `CreateTime=1642662645` 。（sdk v2.13.4 版本开始支持）	number	否
CreateRange	和 create-time 参数一起使用，支持根据创建时间过滤存储桶，支持枚举值 lt（创建时间早于 create-time）、gt（创建时间晚于 create-time）、lte（创建时间早于或等于 create-time）、gte（创建时间晚于或等于create-time）。（sdk v2.13.4 版本开始支持）	string	否
Marker	起始标记，从该标记之后（不含）按照 UTF-8 字典序返回存储桶条目。（sdk v2.13.4 版本开始支持）	string	否
MaxKeys	单次返回最大的条目数量，默认值为2000，最大为2000。如果单次响应中未列出所有存储桶，COS 会返回 NextMarker 节点，其值作为下次 GetService 请求的 marker 参数。（sdk v2.13.4 版本开始支持）	number	否

存储桶操作

本页目录：

简介

注意事项

前期准备

使用案例

查询存储桶列表

列出存储桶列表

列出指定地域的存储桶列表

列出指定标签的存储桶列表。（sdk v2.13.4 版本开始支持）

列出指定日期前创建的存储桶列表。（sdk v2.13.4 版本开始支持）

参数说明

回调函数说明

创建存储桶

参数说明

回调函数说明

检索存储桶及其权限

判断存储桶是否存在

参数说明

回调函数说明

返回结果说明

删除存储桶

参数说明

回调函数说明

返回结果说明

API 操作