本文档提供关于存储桶的基本操作和访问控制列表(ACL)的相关 API 概览以及 SDK 示例代码。
基本操作
API | 操作名 | 操作描述 |
---|---|---|
GET Service | 查询存储桶列表 | 查询指定账号下所有的存储桶列表 |
PUT Bucket | 创建存储桶 | 在指定账号下创建一个存储桶 |
HEAD Bucket | 检索存储桶及其权限 | 检索存储桶是否存在且是否有权限访问 |
DELETE Bucket | 删除存储桶 | 删除指定账号下的空存储桶 |
访问控制列表
API | 操作名 | 操作描述 |
---|---|---|
PUT Bucket acl | 设置存储桶 ACL | 设置指定存储桶的访问权限控制列表 |
GET Bucket acl | 查询存储桶 ACL | 查询指定存储桶的访问权限控制列表 |
GET Service 接口是用来查询请求者名下的所有存储桶列表或特定地域下的存储桶列表(Bucket list)。了解更多请参见 GET Service。
示例一:列出存储桶列表。
cos.getService(function(err, data) {
console.log(err || data);
});
示例二:列出指定地域的存储桶列表。
cos.getService({
Region: 'ap-beijing',
}, 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: 'ap-beijing',
ACL: 'private',
}, 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 请求可以确认该存储桶是否存在,是否有权限访问。有以下几种情况:
检索存储桶信息:
cos.headBucket({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'ap-beijing', /* 必须 */
}, 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.code == 404) {
console.log('存储桶不存在');
} else if (err.code == 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: '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 |
PUT Bucket acl 接口用来设置指定存储桶访问权限控制列表(ACL)。
设置存储桶公有读:
cos.putBucketAcl({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'ap-beijing', /* 必须 */
ACL: 'public-read'
}, function(err, data) {
console.log(err || data);
});
为某个用户赋予存储桶所有权限:
cos.putBucketAcl({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'ap-beijing', /* 必须 */
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: 'ap-beijing', /* 必须 */
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);
});
参数名 | 参数描述 | 类型 | 必填 |
---|---|---|---|
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="[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 | 否 |
GrantWriteAcp | 赋予被授权者写入存储桶的访问控制列表(ACL)和存储桶策略(Policy)的权限。格式: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 | 否 |
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 | 否 |
AccessControlPolicy | 跨域资源共享配置的所有信息列表 | Object | 否 |
- Owner | 存储桶持有者的信息 | Object | 否 |
- - ID | 存储桶持有者的完整 ID,格式为 qcs::cam::uin/[OwnerUin]:uin/[OwnerUin] ,例如 qcs::cam::uin/100000000001:uin/100000000001 ,其中100000000001为 uin |
String | 否 |
- Grants | 被授权者信息与权限信息列表 | ObjectArray | 否 |
- - Permission | 授予的权限信息,可选项 READ、WRITE、READ_ACP、WRITE_ACP、FULL_CONTROL。枚举值详情参见 ACL 概述 文档中存储桶的操作部分 | String | 否 |
- - Grantee | 被授权者的信息 | Object | 否 |
- - - ID | 被授权者的完整 ID,格式为 qcs::cam::uin/[OwnerUin]:uin/[OwnerUin] ,例如 qcs::cam::uin/100000000001:uin/100000000001 ,其中100000000001为 uin |
String | 否 |
- - - DisplayName | 被授权者的名称,一般填写成和 ID 一致的字符串 | String | 否 |
- - - URI | 预设用户组,请参见 ACL 概述 文档中预设用户组部分,例如http://cam.qcloud.com/groups/global/AllUsers 或 http://cam.qcloud.com/groups/global/AuthenticatedUsers |
String | 否 |
function(err, data) { ... }
参数名 | 参数描述 | 类型 |
---|---|---|
err | 请求发生错误时返回的对象,包括网络错误和业务错误,如果请求成功则为空,更多详情请参见 错误码 文档 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
data | 请求成功时返回的对象,如果请求发生错误,则为空 | Object |
- statusCode | 请求返回的 HTTP 状态码,例如200、403、404等 | Number |
- headers | 请求返回的头部信息 | Object |
GET Bucket acl 接口用来查询存储桶的访问控制列表(ACL)。该 API 的请求者需要对存储桶有写入 ACL 权限。
cos.getBucketAcl({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'ap-beijing' /* 必须 */
}, 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": {}
}
参数名 | 参数描述 | 类型 | 必填 |
---|---|---|---|
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 |
- ACL | 定义存储桶的访问控制列表(ACL)属性。枚举值请参见 ACL 概述 文档中存储桶的预设 ACL 部分,例如 private, public-read 等,默认为 private | String |
- GrantRead | 具有读取存储桶权限的被授权者 ID 信息 | String |
- GrantWrite | 具有写入存储桶权限的被授权者 ID 信息 | String |
- GrantReadAcp | 具有读取存储桶的访问控制列表(ACL)和存储桶策略(Policy)权限的被授权者 ID 信息 | String |
- GrantWriteAcp | 具有写入存储桶的访问控制列表(ACL)和存储桶策略(Policy)权限的被授权者 ID 信息 | String |
- GrantFullControl | 具有存储桶所有权限的被授权者 ID 信息 | String |
- Owner | 存储桶持有者的信息 | Object |
- - DisplayName | 存储桶持有者的名称 | String |
- - ID | 存储桶持有者的完整 ID 格式为 qcs::cam::uin/<owneruin>:uin/<subuin> 如果是主账号,<OwnerUin> 和 <SubUin> 是同一个值 |
String |
- Grants | 被授权者信息与权限信息列表 | ObjectArray |
- - Permission | 指明授予被授权者的权限信息,枚举值:READ、WRITE、READ_ACP、WRITE_ACP、FULL_CONTROL | String |
- - Grantee | 被授权者的信息 | Object |
- - - DisplayName | 被授权者的名称 | String |
- - - ID | 被授权者的完整 ID:qcs::cam::uin/<owneruin>:uin/<owneruin> 或 qcs::cam::anyone:anyone (指代所有用户)qcs::cam::uin/<owneruin>:uin/<subuin> |
String |
- - - URI | 预设用户组,请参见 ACL 概述 文档中预设用户组部分,例如http://cam.qcloud.com/groups/global/AllUsers 或 http://cam.qcloud.com/groups/global/AuthenticatedUsers |
String |
本页内容是否解决了您的问题?