文档中心

管理桶 ACL（C++ SDK）

最近更新时间：2024.02.04 18:31:04

首次发布时间：2023.01.29 15:35:46

桶（Bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象（Object）数据。本文介绍如何设置和获取桶的读写权限（ACL）。

设置桶的访问权限

注意

设置桶的读写权限，您必须具备 tos:PutBucketACL 权限，或具备 WRITE_ACP 桶 ACL 权限，具体操作，请参见权限配置指南。
配置桶 ACL 的账号必须是该桶的创建者，或拥有该桶 ACL 的写权限。
仅支持对主账号 ID 配置 ACL，不支持子账号。

桶 ACL 说明

访问权限	描述	对应枚举值
READ	允许被授权者列出存储桶中的对象	PermissionType::Read
WRITE	允许被授权者创建、覆盖和删除存储桶中的任意对象	PermissionType::Write
READ_ACP	允许被授权者读取存储桶 ACL	PermissionType::ReadAcp
WRITE_ACP	允许被授权者写入存储桶 ACL	PermissionType::WriteAcp
FULL_CONTROL	允许被授权者在存储桶上的 READ、WRITE、READ_ACP 和 WRITE_ACP 权限	PermissionType::FullControl

请求头中设置访问权限

您可以通过 x-tos-acl 头域，选择预定义的权限。通过 x-tos-acl 请求头设置桶的读写权限如下。

访问权限	描述	对应枚举值
private	私有。桶的所有者拥有完全控制权限，其他人没有权限。默认策略即为 private。	ACLType::Private
public-read	公共读。任何人拥有桶的 READ 权限。	ACLType::PublicRead
public-read-write	公共读写。任何人拥有桶的 READ 和 WRITE 权限。	ACLType::PublicReadWrite
authenticated-read	任何已认证用户拥有桶的 READ 权限。	ACLType::AuthenticatedRead

以下代码展示如何通过 x-tos-acl 设置桶的读写权限。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    // 填写 Bucket 名称，例如 examplebucket
    std::string bucketName = "examplebucket";
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey);
    
    // 设置桶的访问权限为公共读，默认为私有。
    PutBucketAclInput input(bucketName);
    input.setAcl(ACLType::PublicRead);
    auto output = client.putBucketAcl(input);
    if (!output.isSuccess()) {
        // 异常处理
        std::cout << "SetBucketACL failed." << output.error().String() << std::endl;
        // 释放网络等资源
        CloseClient();
        return -1;
    }
    std::cout << "SetBucketACL success." << std::endl;

    // 释放网络等资源
    CloseClient();
    return 0;
}

以下代码通过 x-tos-grant-* 请求头设置桶 examplebucket 的读写权限。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    // 填写 Bucket 名称，例如 examplebucket
    std::string bucketName = "examplebucket";

    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey);
    
    // 设置桶的访问权限为公共读，默认为私有。
    PutBucketAclInput input(bucketName);
    // 设置用户ID为1000000001具备FULL_CONTROL控制权, 所有用户具备桶的READ权限
    input.setGrantFullControl("id=\"1000000001\"");
    input.setGrantRead("canned=\"AllUsers\"");
    auto output = client.putBucketAcl(input);
    if (!output.isSuccess()) {
        // 异常处理
        std::cout << "SetBucketACL failed." << output.error().String() << std::endl;
        // 释放网络等资源
        CloseClient();
        return -1;
    }
    std::cout << "SetBucketACL success." << std::endl;

    // 释放网络等资源
    CloseClient();
    return 0;
}

请求体中填写详细 ACL 权限信息

以下代码用于请求体中设置桶 examplebucket 的权限信息。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    // 填写 Bucket 名称，例如 examplebucket
    std::string bucketName = "examplebucket";
    
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey);
    
    // 请求体中设置桶 examplebucket 的权限信息。
    PutBucketAclInput input(bucketName);
    Owner owner;
    owner.setId("test-cid");
    GranteeV2 granteev2;
    granteev2.setType(GranteeType::Group);
    granteev2.setCanned(CannedType::AllUsers);
    GrantV2 grantv2;
    grantv2.setGrantee(granteev2);
    grantv2.setPermission(PermissionType::WriteAcp);
    input.setOwner(owner);
    input.setGrants({grantv2});
    auto output = client.putBucketAcl(input);
    if (!output.isSuccess()) {
        // 异常处理
        std::cout << "SetBucketACL failed." << output.error().String() << std::endl;
        // 释放网络等资源
        CloseClient();
        return -1;
    }
    std::cout << "SetBucketACL success." << std::endl;

    // 释放网络等资源
    CloseClient();
    return 0;
}

获取桶的访问权限

注意

获取桶的访问权限，您必须具备 tos:GetBucketACL 权限，或具备 READ_ACP 的桶 ACL 权限，具体操作，请参见权限配置指南。

#include "TosClientV2.h"
using namespace VolcengineTos;

int main(void){
    // 初始化 TOS 账号信息
    // Your Region 填写 Bucket 所在 Region
    std::string region = "Your Region";
    std::string accessKey = std::getenv("TOS_ACCESS_KEY");
    std::string secretKey = std::getenv("TOS_SECRET_KEY");
    // 填写 Bucket 名称，例如 examplebucket
    std::string bucketName = "examplebucket";
    
    PermissionType permission_;
    // 初始化网络等资源
    InitializeClient();
    // 创建交互的 client
    TosClientV2 client(region, accessKey, secretKey);
    
    // 获取桶读写权限配置
    GetBucketAclInput input(bucketName);
    auto output = client.getBucketAcl(input);
    if (!output.isSuccess()) {
        // 异常处理
        std::cout << "GetBucketACL failed." << output.error().String() << std::endl;
        // 释放网络等资源
        CloseClient();
        return -1;
    }

    // 打印：
    // 授予者所拥有的 Bucket 权限，
    // 当 Type 为 CanonicalUser 时，表示权限授予者的 ID，
    // 权限被授予者的名称，
    // 权限授予者的类型，
    // 被授权的用户组。
    std::cout << "GetBucketACL success." << std::endl;
    auto grant = output.result().getGrant();
    for(auto& g : grant){
        std::cout << " the premission is:" << g.getStringFormatPermission()
                  << " the grantee id is:" <<  g.getGrantee().getId()
                  << " the display name is:" <<  g.getGrantee().getDisplayName()
                  << " the grantee is:" <<  g.getGrantee().getStringFormatType()
                  << " the canned is:" <<  g.getGrantee().getStringFormatCanned() << std::endl;
    }
    // 释放网络等资源
    CloseClient();
    return 0;
}

对象存储