You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

管理桶 ACL（Java SDK）

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

首次发布时间：2023.01.19 14:37:15

我的收藏

桶（Bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象（Object）数据。TOS针对桶（Bucket）资源的权限控制包括桶授权策略（Bucket Policy）和桶读写权限控制（Bucket ACL）。本文介绍如何通过 TOS Java SDK 管理桶的读写权限（ACL）。有关桶的授权策略管理请参考授权策略配置。

设置桶的访问权限

您可以通过 TOS Java SDK 的 putBucketACL 接口设置指定桶的读写权限。

注意

设置桶的读写权限，您的账号必须具备 tos:PutBucketACL 权限，或具备 WRITE_ACP 桶 ACL 权限。具体操作，请参见权限配置概述。

桶 ACL 说明

桶 ACL 权限包含以下五类。

访问权限

描述

访问权限值

READ

允许被授权者列出存储桶中的对象

PermissionType.PERMISSION_READ

WRITE

允许被授权者创建、覆盖和删除存储桶中的任意对象

PermissionType.PERMISSION_WRITE

READ_ACP

允许被授权者读取存储桶 ACL

PermissionType.PERMISSION_READ_ACP

WRITE_ACP

允许被授权者写入存储桶 ACL

PermissionType.PERMISSION_WRITE_ACP

FULL_CONTROL

允许被授权者在存储桶上的 READ、WRITE、READ_ACP 和 WRITE_ACP 权限

PermissionType.PERMISSION_FULL_CONTROL

桶的访问权限可通过在请求 Body 中填写详细的 ACL 权限信息，或在请求的 Header 中进行设置。

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

以下代码展示如何在请求的 Body 中设置桶的权限信息。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.comm.common.CannedType;
import com.volcengine.tos.comm.common.GranteeType;
import com.volcengine.tos.comm.common.PermissionType;
import com.volcengine.tos.model.acl.GrantV2;
import com.volcengine.tos.model.acl.GranteeV2;
import com.volcengine.tos.model.acl.Owner;
import com.volcengine.tos.model.bucket.PutBucketACLInput;
import com.volcengine.tos.model.bucket.PutBucketACLOutput;

import java.util.ArrayList;
import java.util.List;

public class PutBucketACLWithGrantsExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            // 待授权的用户账号id，如果 GranteeType 为 GRANTEE_USER，此项必选
            String accountId = "the granted account id";
            // 待授权的用户账号名，非必选参数
            String accountDisplayName = "the granted account display name";
            GranteeV2 grantee1 = new GranteeV2().setType(GranteeType.GRANTEE_USER)
                    .setId(accountId).setDisplayName(accountDisplayName);
            // 对特定账号为 accountId 的用户授予 PERMISSION_FULL_CONTROL 的权限
            GrantV2 grant1 = new GrantV2().setGrantee(grantee1).setPermission(PermissionType.PERMISSION_FULL_CONTROL);

            GranteeV2 grantee2 = new GranteeV2().setType(GranteeType.GRANTEE_GROUP)
                    .setCanned(CannedType.CANNED_ALL_USERS);
            // 对所有用户授予读权限
            GrantV2 grant2 = new GrantV2().setGrantee(grantee2).setPermission(PermissionType.PERMISSION_READ);

            // 授权列表
            List<GrantV2> grantList = new ArrayList<>();
            grantList.add(grant1);
            grantList.add(grant2);

            // Owner 信息，ownerId 必选，ownerDisplayName 可选
            String ownerId = "your owner id";
            String ownerDisplayName = "your owner display name";
            PutBucketACLInput input = new PutBucketACLInput().setBucket(bucketName).setGrants(grantList)
                    .setOwner(new Owner().setId(ownerId).setDisplayName(ownerDisplayName));
            PutBucketACLOutput output = tos.putBucketACL(input);
            System.out.println("putBucketACL succeed");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putBucketACL failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putBucketACL failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("putBucketACL failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

请求头中设置访问权限

通过 x-tos-acl 请求 Header 设置桶的读写权限有以下四类。

访问权限

描述

访问权限值

私有

私有。桶所有者拥有 FULL_CONTROL 权限，其他用户没有权限操作该对象。

ACLType.ACL_PRIVATE

公共读

公共读。桶的所有者拥有 FULL_CONTROL 权限，其他用户只有该桶的 READ 权限。

ACLType.ACL_PUBLIC_READ

公共读写

公共读写。所有用户都有 FULL_CONTROL 权限。

ACLType.ACL_PUBLIC_READ_WRITE

认证用户读

桶所有者拥有 FULL_CONTROL 权限，认证用户拥有桶的 READ 权限。

ACLType.ACL_AUTHENTICATED_READ

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

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.comm.common.ACLType;
import com.volcengine.tos.model.bucket.PutBucketACLInput;
import com.volcengine.tos.model.bucket.PutBucketACLOutput;

public class PutBucketACLWithAclHeaderExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            // 设置桶为私有
            ACLType aclType = ACLType.ACL_PRIVATE;
            PutBucketACLInput input = new PutBucketACLInput().setBucket(bucketName).setAcl(aclType);
            PutBucketACLOutput output = tos.putBucketACL(input);
            System.out.println("putBucketACL succeed");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putBucketACL failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putBucketACL failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("putBucketACL failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

以下代码展示如何通过 x-tos-grant-* 请求 Header 设置桶的读写权限。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.bucket.PutBucketACLInput;
import com.volcengine.tos.model.bucket.PutBucketACLOutput;

public class PutBucketACLWithGrantHeaderExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            // 以下仅为示例，请根据实际业务需要进行填写。
            // 设置授予 full control 权限的账号ID
            String grantFullControlRule = "id=\"1000000001\"";
            // 设置授予读权限的一组用户
            String grantReadRule = "canned=\"AllUsers\"";
            PutBucketACLInput input = new PutBucketACLInput().setBucket(bucketName)
                    .setGrantFullControl(grantFullControlRule).setGrantRead(grantReadRule);
            PutBucketACLOutput output = tos.putBucketACL(input);
            System.out.println("putBucketACL succeed");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putBucketACL failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putBucketACL failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("putBucketACL failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

获取桶的访问权限

您可以通过 TOS Java SDK 的 getBucketACL 接口获取指定桶当前配置的读写权限。

注意

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

以下代码展示如何获取桶的访问权限。

import com.volcengine.tos.TOSV2;
import com.volcengine.tos.TOSV2ClientBuilder;
import com.volcengine.tos.TosClientException;
import com.volcengine.tos.TosServerException;
import com.volcengine.tos.model.acl.GrantV2;
import com.volcengine.tos.model.bucket.GetBucketACLInput;
import com.volcengine.tos.model.bucket.GetBucketACLOutput;

public class GetBucketACLExample {
    public static void main(String[] args) {
        String endpoint = "your endpoint";
        String region = "your region";
        String accessKey = System.getenv("TOS_ACCESS_KEY");
        String secretKey = System.getenv("TOS_SECRET_KEY");

        String bucketName = "your bucket name";

        TOSV2 tos = new TOSV2ClientBuilder().build(region, endpoint, accessKey, secretKey);

        try{
            GetBucketACLInput input = new GetBucketACLInput().setBucket(bucketName);
            GetBucketACLOutput output = tos.getBucketACL(input);
            System.out.println("getBucketACL succeed");
            if (output.getOwner() != null) {
                System.out.println("owner id is " + output.getOwner().getId());
                System.out.println("owner display name is " + output.getOwner().getDisplayName());
            }
            if (output.getGrants() != null) {
                System.out.println("this bucket has " + output.getGrants().size() + " grants");
                for (int i = 0; i < output.getGrants().size(); i++){
                    GrantV2 grant = output.getGrants().get(i);
                    if (grant.getGrantee() != null) {
                        System.out.printf("bucket acl grantee, id is %s, displayName is %s, type is %s, uri is %s.\n",
                                grant.getGrantee().getId(), grant.getGrantee().getDisplayName(),
                                grant.getGrantee().getType(), grant.getGrantee().getCanned());
                    }
                    System.out.println("bucket acl grant permission is " + grant.getPermission() + ".");
                }
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("getBucketACL failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("getBucketACL failed");
            System.out.println("StatusCode: " + e.getStatusCode());
            System.out.println("Code: " + e.getCode());
            System.out.println("Message: " + e.getMessage());
            System.out.println("RequestID: " + e.getRequestID());
        } catch (Throwable t) {
            // 作为兜底捕获其他异常，一般不会执行到这里
            System.out.println("getBucketACL failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

相关文档

管理桶的权限，请参见桶 ACLs。