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

简介

本文档提供关于存储桶、对象的访问控制列表(ACL)的相关 API 概览以及 SDK 示例代码。
存储桶 ACL
API
操作名
操作描述
设置存储桶 ACL
设置指定存储桶的访问权限控制列表(ACL)
查询存储桶 ACL
查询指定存储桶的访问权限控制列表(ACL)
对象 ACL
API
操作名
操作描述
设置对象 ACL
设置存储桶中某个对象的访问控制列表
查询对象 ACL
查询对象的访问控制列表

存储桶 ACL

设置存储桶 ACL

功能说明

设置指定存储桶的访问权限控制列表(PUT Bucket acl)。该操作是覆盖操作,会覆盖已有的权限设置。ACL 包括预定义权限策略(CannedAccessControlList)或者自定义的权限控制(AccessControlList)。两类权限当同时设置时将忽略预定义策略,以自定义策略为主。

方法原型

CosResult PutBucketACL(const PutBucketACLReq& request, PutBucketACLResp* response);

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

// PutBucketACLReq 的构造函数需要传入 bucket_name
qcloud_cos::PutBucketACLReq req(bucket_name);
qcloud_cos::PutBucketACLResp resp;

// 设置 ACL 配置(可以通过 Body、Header 两种方式,但只能二选一,否则会有冲突)
// 1.通过 header 设置 ACL
req.SetXCosAcl("public-read-write");

// 2.通过 body 设置 ACL
qcloud_cos::Owner owner = {"qcs::cam::uin/00000000001:uin/00000000001", "qcs::cam::uin/00000000001:uin/00000000001" };
qcloud_cos::Grant grant;
req.SetOwner(owner);
grant.m_grantee.m_type = "Group";
grant.m_grantee.m_uri = "http://cam.qcloud.com/groups/global/AllUsers";
grant.m_perm = "READ";
req.AddAccessControlList(grant);

qcloud_cos::PutBucketACLResp resp;
qcloud_cos::CosResult result = cos.PutBucketACL(req, &resp);

if (result.IsSucc()) {
// 请求成功
} else {
// 请求失败,调用 CosResult 的成员函数输出错误信息,例如 requestID 等
}

参数说明

参数
参数描述
类型
是否必填
req
PutBucketACL 操作的请求
PutBucketACLReq
resp
PutBucketACL 操作的响应
PutBucketACLResp
PutBucketACLReq 提供以下成员函数:
// 定义 Bucket 的 ACL 属性,有效值:private,public-read-write,public-read
// 默认值:private
void SetXCosAcl(const std::string& str);

// 赋予被授权者读的权限.格式:x-cos-grant-read: id=" ",id=" ".
// 当需要给子账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
// 当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantRead(const std::string& str);

// 赋予被授权者写的权限,格式:x-cos-grant-write: id=" ",id=" "./
// 当需要给子账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// 当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantWrite(const std::string& str);

// 赋予被授权者读写权限.格式:x-cos-grant-full-control: id=" ",id=" ".
// 当需要给子账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// 当需要给主账号授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXCosGrantFullControl(const std::string& str);

// Bucket 持有者 ID
void SetOwner(const Owner& owner);

// 设置被授权者信息与权限信息
void SetAccessControlList(const std::vector<Grant>& grants);

// 添加单个 Bucket 的授权信息
void AddAccessControlList(const Grant& grant);

注意
SetXCosAcl、SetXCosGrantRead、SetXCosGrantWrite、SetXCosGrantFullControl 这类接口与 SetAccessControlList、AddAccessControlList 不可同时使用。因为前者实际是通过设置 HTTP Header 实现,而后者是在 Body 中添加了 XML 格式的内容,二者只能二选一。 SDK 内部优先使用第一类。
该请求涉及到的类定义如下:
struct Owner {
// 存储桶持有者信息
std::string m_id; // owner 的完整 ID,格式为:qcs::cam::uin/<OwnerUin>:uin/<SubUin>
std::string m_display_name; // owner 的描述
};

struct Grantee {
// type 类型可以为 RootAccount, SubAccount
// 当 type 类型为 RootAccount 时,可以在 id 中 uin 填写账号 ID,也可以用 anyone(指代所有类型用户)代替 uin/<OwnerUin> 和 uin/<SubUin>
// 当 type 类型为 RootAccount 时,uin 代表主账号,Subaccount 代表子账号
std::string m_type;
std::string m_id; // qcs::cam::uin/<OwnerUin>:uin/<SubUin>
std::string m_display_name; // 非必选
std::string m_uri;
};

struct Grant {
Grantee m_grantee; // 被授权者资源信息
std::string m_perm; // 指明授予被授权者的权限信息,可选值"READ""WRITE""FULL_CONTROL"
};


查询存储桶 ACL

功能说明

查询指定存储桶的访问权限控制列表。

方法原型

CosResult GetBucketACL(const GetBucketACLReq& req, GetBucketACLResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";

qcloud_cos::GetBucketACLReq req(bucket_name);
qcloud_cos::GetBucketACLResp resp;
qcloud_cos::CosResult result = cos.GetBucketACL(req, &resp);

if (result.IsSucc()) {
// 请求成功,调用 resp 的成员函数获取返回内容
} else {
// 请求失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
}


参数说明

参数
参数描述
类型
是否必填
req
GetBucketACL 操作的请求
GetBucketACLReq
resp
GetBucketACL 操作的响应
GetBucketACLResp
GetBucketACLResp 提供以下成员函数:
std::string GetOwnerID();
std::string GetOwnerDisplayName();
std::vector<Grant> GetAccessControlList();

对象 ACL

设置对象 ACL

功能说明

设置存储桶中某个对象的访问控制列表。
注意
当前访问策略条目限制为1000条,如果您不需要进行对象 ACL 控制,请不要设置,默认继承 Bucket 权限。
ACL 包括预定义权限策略(CannedAccessControlList)或者自定义的权限控制(AccessControlList)。两类权限当同时设置时将忽略预定义策略,以自定义策略为主。

方法原型

CosResult PutObjectACL(const PutObjectACLReq& req, PutObjectACLResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "test";

// 1 设置 ACL 配置(通过 Body, 设置 ACL 可以通过 Body、Header 两种方式,但只能二选一,否则会有冲突)
{
qcloud_cos::PutObjectACLReq req(bucket_name, object_name);
qcloud_cos::Owner owner = {"qcs::cam::uin/xxxxx:uin/xxx", "qcs::cam::uin/xxxxxx:uin/xxxxx" };
qcloud_cos::Grant grant;
req.SetOwner(owner);
grant.m_grantee.m_type = "Group";
grant.m_grantee.m_uri = "http://cam.qcloud.com/groups/global/AllUsers";
grant.m_perm = "READ";
req.AddAccessControlList(grant);

qcloud_cos::PutObjectACLResp resp;
qcloud_cos::CosResult result = cos.PutObjectACL(req, &resp);
if (result.IsSucc()) {
// 请求成功
} else {
// 请求失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
}
}

// 2 设置 ACL 配置(通过 Header, 设置 ACL 可以通过 Body、Header 两种方式,但只能二选一,否则会有冲突)
{
qcloud_cos::PutObjectACLReq req(bucket_name, object_name);
req.SetXCosAcl("public-read-write");

qcloud_cos::PutObjectACLResp resp;
qcloud_cos::CosResult result = cos.PutObjectACL(req, &resp);
if (result.IsSucc()) {
// 请求成功
} else {
// 请求失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
}
}

参数说明

参数
参数描述
类型
是否必填
req
PutObjectACL 操作的请求
PuttObjectACLReq
resp
PutObjectACL 操作的响应
PutObjectACLResp
PutObjectACLReq 包含以下成员函数:
// 定义 Object 的 ACL 属性,有效值:private,public-read
// 默认值:private
void SetXCosAcl(const std::string& str);

// 赋予被授权者读的权限。格式:id="[OwnerUin]"
void SetXCosGrantRead(const std::string& str);

// 赋予被授权者所有的权限。格式:id="[OwnerUin]"
void SetXCosGrantFullControl(const std::string& str);

// Object 持有者 ID
void SetOwner(const Owner& owner);

// 设置被授权者信息与权限信息
void SetAccessControlList(const std::vector<Grant>& grants);

// 添加单个 Object 的授权信息
void AddAccessControlList(const Grant& grant);

注意
SetXCosAcl/SetXCosGrantRead/SetXCosGrantWrite/SetXCosGrantFullControl 这类接口与 SetAccessControlList/AddAccessControlList 不可同时使用。因为前者实际是通过设置 HTTP Header 实现,而后者是在Body 中添加了 XML 格式的内容,二者只能二选一。SDK 内部优先使用第一类。
ACLRule 定义如下:
struct Grantee {
// type 类型可以为 RootAccount, SubAccount
// 当 type 类型为 RootAccount 时,可以在 id 中 uin 填写账号 ID,也可以用 anyone(指代所有类型用户)代替 uin/<OwnerUin> 和 uin/<SubUin>
// 当 type 类型为 RootAccount 时,uin 代表主账号账号,Subaccount 代表子账号账号
std::string m_type;
std::string m_id; // qcs::cam::uin/<OwnerUin>:uin/<SubUin>
std::string m_display_name; // 非必选
std::string m_uri;
};

struct Grant {
Grantee m_grantee; // 被授权者资源信息
std::string m_perm; // 指明授予被授权者的权限信息,可选值"READ""WRITE""FULL_CONTROL"
};


查询对象 ACL

功能说明

查询对象的访问控制列表。

方法原型

CosResult GetObjectACL(const GetObjectACLReq& req, GetObjectACLResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);

std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "exampleobject";

// GetObjectACLReq 的构造函数需要传入 Object_name
qcloud_cos::GetObjectACLReq req(bucket_name, object_name);
qcloud_cos::GetObjectACLResp resp;
qcloud_cos::CosResult result = cos.GetObjectACL(req, &resp);

if (result.IsSucc()) {
// 请求成功,调用 resp 的成员函数获取返回内容
} else {
// 请求失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
}

参数说明

参数
参数描述
类型
是否必填
req
GetObjectACL 操作的请求
GetObjectACLReq
resp
GetObjectACL 操作的响应
GetObjectACLResp
GetObjectACLResp 包含以下成员函数:
std::string GetOwnerID();
std::string GetOwnerDisplayName();
std::vector<Grant> GetAccessControlList();