简介
本文档提供关于存储桶基本操作的 API 概览以及 SDK 示例代码。
API | 操作名 | 操作描述 |
---|---|---|
GET Service(List Buckets) | 查询存储桶列表 | 查询指定账号下所有的存储桶列表 |
PUT Bucket | 创建存储桶 | 在指定账号下创建一个存储桶 |
HEAD Bucket | 检索存储桶及其权限 | 检索存储桶是否存在且是否有权限访问 |
DELETE Bucket | 删除存储桶 | 删除指定账号下的空存储桶 |
查询存储桶列表
功能说明
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 | 存储桶的名称,格式为 |
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'
}, 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 | 否 |
回调函数说明
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 |