有奖捉虫:云通信与企业服务文档专题,速来> HOT

简介

本文档提供关于存储桶基本操作的 API 概览以及 SDK 示例代码。
API
操作名
操作描述
查询存储桶列表
查询指定账号下所有的存储桶列表
创建存储桶
在指定账号下创建一个存储桶
检索存储桶及其权限
检索存储桶是否存在且是否有权限访问
删除存储桶
删除指定账号下的空存储桶

查询存储桶列表

功能说明

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);
});

参数说明

参数名
参数描述
类型
是否必填
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
- 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

创建存储桶

功能说明

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

使用示例

cos.putBucket({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION',
// 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

检索存储桶及其权限

功能说明

HEAD Bucket 请求可以确认该存储桶是否存在,是否有权限访问。有以下几种情况:
存储桶存在且有读取权限,返回 HTTP 状态码200。
无存储桶读取权限,返回 HTTP 状态码403。
存储桶不存在,返回 HTTP 状态码404。

使用示例

检索存储桶信息:
cos.headBucket({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
}, function(err, data) {
console.log(err || data);
});
判断存储桶是否存在:
function doesBucketExist() {
cos.headBucket({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */
}, function(err, data) {
if (data) {
console.log('存储桶存在');
} else if (err.statusCode == 404) {
console.log('存储桶不存在');
} else if (err.statusCode == 403) {
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

删除存储桶

功能说明

删除指定账号下的空存储桶。注意,如果删除成功,则返回的 HTTP 状态码为200或204。
说明
删除存储桶前,请确保存储桶内的数据和未完成上传的分块数据已全部清空,否则会无法删除存储桶。

使用示例

cos.deleteBucket({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION' /* 必须 */
}, 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