文档中心

管理对象读写权限（Java SDK）

最近更新时间：2024.02.04 18:30:54

首次发布时间：2021.11.27 17:58:44

本文介绍如何获取和设置对象的访问权限。对象的访问权限优先级高于桶的访问权限，如果对象未设置访问权限，则遵循桶的访问权限。

设置对象的读写权限

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

注意

设置对象的读写权限，您的账号必须具备 tos:PutObjectAcl 权限。具体操作，请参见权限配置指南。

对象 ACL 说明

对象 ACL 权限包含以下类型。

访问权限	描述	访问权限值
READ	允许被授权者读取对象数据及其元数据	PermissionType.PERMISSION_READ
READ_ACP	允许被授权者读取对象 ACL	PermissionType.PERMISSION_READ_ACP
WRITE_ACP	允许被授权者写入对象 ACL	PermissionType.PERMISSION_WRITE_ACP
FULL_CONTROL	允许被授权者在对象上的 READ、READ_ACP 和 WRITE_ACP 权限	PermissionType.PERMISSION_FULL_CONTROL

您可参考以下代码，通过在请求体中填写详细的 ACL 权限信息，或请求头中设置 ACL 权限信息。

请求体中填写详细 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.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.object.ObjectAclRulesV2;
import com.volcengine.tos.model.object.PutObjectACLInput;
import com.volcengine.tos.model.object.PutObjectACLOutput;

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

public class PutObjectAclWithGrantsExample {
    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 = "bucket-example";
        String objectKey = "example_dir/example_object.txt";

        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";
            Owner owner = new Owner().setId(ownerId).setDisplayName(ownerDisplayName);
            PutObjectACLInput input = new PutObjectACLInput().setBucket(bucketName).setKey(objectKey)
                    .setObjectAclRules(new ObjectAclRulesV2().setGrants(grantList).setOwner(owner));
            PutObjectACLOutput output = tos.putObjectAcl(input);
            System.out.println("putObjectAcl succeed.");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putObjectAcl failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putObjectAcl 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("putObjectAcl failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

请求头中设置访问权限

通过 x-tos-acl header 设置对象的读写权限有以下六类。

访问权限	描述	访问权限值
私有	私有。对象的所有者拥有所有权限，其他用户没有权限操作该对象。	ACLType.ACL_PRIVATE
公共读	公共读。对象的所有者拥有所有权限，其他用户只有该对象的读权限。	ACLType.ACL_PUBLIC_READ
公共读写	公共读写。所有用户都有该对象的读写权限。	ACLType.ACL_PUBLIC_READ_WRITE
认证用户读	对象的所有者拥有所有权限，认证用户拥有该对象的读权限。	ACLType.ACL_AUTHENTICATED_READ
桶所有者读	对象的所有者拥有所有权限，桶所有者拥有此对象的读权限。	ACLType.ACL_BUCKET_OWNER_READ
桶所有者具备所有权限	桶所有者和对象所有者都拥有对象的所有操作权限。	ACLType.ACL_BUCKET_OWNER_FULL_CONTROL

以下代码展示如何通过 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.object.PutObjectACLInput;
import com.volcengine.tos.model.object.PutObjectACLOutput;

public class PutObjectAclWithAclHeaderExample {
    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 = "bucket-example";
        String objectKey = "example_dir/example_object.txt";

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

        try{
            // 授予 objectKey 对象公共读权限
            PutObjectACLInput input = new PutObjectACLInput().setAcl(ACLType.ACL_PUBLIC_READ)
                    .setBucket(bucketName).setKey(objectKey);
            PutObjectACLOutput output = tos.putObjectAcl(input);
            System.out.println("putObjectAcl succeed.");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putObjectAcl failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putObjectAcl 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("putObjectAcl 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.object.PutObjectACLInput;
import com.volcengine.tos.model.object.PutObjectACLOutput;

public class PutObjectAclWithGrantHeaderExample {
    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 = "bucket-example";
        String objectKey = "example_dir/example_object.txt";

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

        try{
            // 以下仅为示例，请根据实际业务需要进行填写。
            // 设置授予 full control 权限的账号ID
            String grantFullControlRule = "id=\"1000000001\"";
            // 设置授予读权限的一组用户
            String grantReadRule = "canned=\"AllUsers\"";
            PutObjectACLInput input = new PutObjectACLInput().setBucket(bucketName).setKey(objectKey)
                    .setGrantFullControl(grantFullControlRule).setGrantRead(grantReadRule);
            PutObjectACLOutput output = tos.putObjectAcl(input);
            System.out.println("putObjectAcl succeed.");
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("putObjectAcl failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("putObjectAcl 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("putObjectAcl failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

获取对象的访问权限

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

注意

获取对象的访问权限，您的账号必须具备 tos:GetObjectACL 权限。具体操作，请参见权限配置指南。

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

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.object.GetObjectACLV2Input;
import com.volcengine.tos.model.object.GetObjectACLV2Output;

public class GetObjectAclExample {
    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 = "bucket-example";
        String objectKey = "example_dir/example_object.txt";

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

        try{
            GetObjectACLV2Input input = new GetObjectACLV2Input().setBucket(bucketName).setKey(objectKey);
            GetObjectACLV2Output output = tos.getObjectAcl(input);
            System.out.println("getObjectAcl succeed.");
            System.out.println("object owner is " + output.getOwner());
            if (output.getGrants() != null && output.getGrants().size() > 0) {
                for (GrantV2 grant : output.getGrants()) {
                    System.out.println("object grant is " + grant);
                }
            }
        } catch (TosClientException e) {
            // 操作失败，捕获客户端异常，一般情况是请求参数错误，此时请求并未发送
            System.out.println("getObjectAcl failed");
            System.out.println("Message: " + e.getMessage());
            if (e.getCause() != null) {
                e.getCause().printStackTrace();
            }
        } catch (TosServerException e) {
            // 操作失败，捕获服务端异常，可以获取到从服务端返回的详细错误信息
            System.out.println("getObjectAcl 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("getObjectAcl failed");
            System.out.println("unexpected exception, message: " + t.getMessage());
        }
    }
}

对象存储