桶（Bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象（Object）数据。本文介绍如何设置和获取桶的读写权限（ACL）。
注意
设置桶的读写权限，您必须具备 tos:PutBucketACL` 权限，或具备 WRITE_ACP 桶 ACL权限，具体操作，请参见权限配置指南。
桶 ACL 权限包含以下五类。
访问权限 | 描述 | 访问权限值 |
|---|---|---|
READ | 允许被授权者列出存储桶中的对象 | tos.PermissionType.Permission_Read |
WRITE | 允许被授权者创建、覆盖和删除存储桶中的任意对象 | tos.PermissionType.Permission_Write |
READ_ACP | 允许被授权者读取存储桶 ACL | tos.PermissionType.Permission_Read_Acp |
WRITE_ACP | 允许被授权者写入存储桶 ACL | tos.PermissionType.Permission_Write_Acp |
FULL_CONTROL | 允许被授权者在存储桶上的 READ、WRITE、READ_ACP 和 WRITE_ACP 权限 | tos.PermissionType.Permission_Full_Control |
可通过请求体中填写详细的 ACL 权限信息或请求头中设置。
以下代码用于请求体中设置桶 bucket-test 的权限信息。
import os import tos from tos import GranteeType, CannedType, PermissionType from tos.models2 import Grantee, Grant, Owner # 从环境变量获取 AK 和 SK 信息。 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') endpoint = "your endpoint" region = "your region" bucket_name = "bucket-test" try: client = tos.TosClientV2(ak, sk, endpoint, region) # 被授权者为账户ID grantee1 = Grantee(GranteeType.Grantee_User, id='account id', display_name='account display name') # 被授权者为预定义组中的所有用户 grantee2 = Grantee(GranteeType.Grantee_Group, canned=CannedType.Canned_All_Users) # 向指定账户ID授予Permission_Full_Control权限 grant_1 = Grant(grantee1, PermissionType.Permission_Full_Control) # 向所有用户授予Permission_Read权限 grant_2 = Grant(grantee2, PermissionType.Permission_Read) client.put_bucket_acl(bucket_name, grants=[grant_1, grant_2], owner=Owner("object owner id", 'object owner name')) except tos.exceptions.TosClientError as e: # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常 print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause)) except tos.exceptions.TosServerError as e: # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息 print('fail with server error, code: {}'.format(e.code)) # request id 可定位具体问题，强烈建议日志中保存 print('error with request id: {}'.format(e.request_id)) print('error with message: {}'.format(e.message)) print('error with http code: {}'.format(e.status_code)) print('error with ec: {}'.format(e.ec)) print('error with request url: {}'.format(e.request_url)) except Exception as e: print('fail with unknown error: {}'.format(e))
通过 x-tos-acl 请求头设置桶的读写权限有以下四类。
访问权限 | 描述 | 访问权限值 |
|---|---|---|
私有 | 私有。桶所有者拥有 FULL_CONTROL 权限，其他用户没有权限操作该对象。 | tos.ACLType.ACL_Private |
公共读 | 公共读。桶的所有者拥有 FULL_CONTROL 权限，其他用户只有该桶的 READ 权限。 | tos.ACLType.ACL_Public_Read |
公共读写 | 公共读写。所有用户都有 FULL_CONTROL 权限。 | tos.ACLType.ACL_Public_Read_Write |
认证用户读 | 桶所有者拥有 FULL_CONTROL 权限，认证用户拥有桶的 READ 权限。 | tos.ACLType.ACL_Authenticated_Read |
以下代码通过 x-tos-acl 设置桶 bucket-test 的读写权限。
import os import tos # 从环境变量获取 AK 和 SK 信息。 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" bucket_name = "bucket-test" try: # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) # 设置桶权限为私有 client.put_bucket_acl(bucket_name, acl=tos.ACLType.ACL_Private) except tos.exceptions.TosClientError as e: # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常 print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause)) except tos.exceptions.TosServerError as e: # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息 print('fail with server error, code: {}'.format(e.code)) # request id 可定位具体问题，强烈建议日志中保存 print('error with request id: {}'.format(e.request_id)) print('error with message: {}'.format(e.message)) print('error with http code: {}'.format(e.status_code)) print('error with ec: {}'.format(e.ec)) print('error with request url: {}'.format(e.request_url)) except Exception as e: print('fail with unknown error: {}'.format(e))
以下代码通过 x-tos-grant-* 请求设头置桶 bucket-test 的读写权限。
import os import tos # 从环境变量获取 AK 和 SK 信息。 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" bucket_name = "bucket-test" try: # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) # 设置用户ID为1000000001具备FULL_CONTROL控制权, 所有用户具备桶的READ权限 client.put_bucket_acl(bucket_name, grant_full_control='id="1000000001"', grant_read='canned="AllUsers"') except tos.exceptions.TosClientError as e: # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常 print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause)) except tos.exceptions.TosServerError as e: # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息 print('fail with server error, code: {}'.format(e.code)) # request id 可定位具体问题，强烈建议日志中保存 print('error with request id: {}'.format(e.request_id)) print('error with message: {}'.format(e.message)) print('error with http code: {}'.format(e.status_code)) print('error with ec: {}'.format(e.ec)) print('error with request url: {}'.format(e.request_url)) except Exception as e: print('fail with unknown error: {}'.format(e))
注意
获取桶的访问权限，您必须具备 tos:GetBucketACL 权限，或具备 READ_ACP 的桶 ACL 权限，具体操作，请参见权限配置指南。
以下代码用于获取桶 bucket-test 的访问权限。
import os import tos # 从环境变量获取 AK 和 SK 信息。 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例，your endpoint 填写 tos-cn-beijing.volces.com，your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" bucket_name = "bucket-test" try: # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现 client = tos.TosClientV2(ak, sk, endpoint, region) # 获取桶的权限 out = client.get_bucket_acl(bucket_name) print('owner_id={}'.format(out.owner.id)) for grant in out.grants: print('permission={}'.format(grant.permission.value)) print('id={}'.format(grant.grantee.id)) print('type={}'.format(grant.grantee.type)) print('canned={}'.format(grant.grantee.canned)) except tos.exceptions.TosClientError as e: # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常 print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause)) except tos.exceptions.TosServerError as e: # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息 print('fail with server error, code: {}'.format(e.code)) # request id 可定位具体问题，强烈建议日志中保存 print('error with request id: {}'.format(e.request_id)) print('error with message: {}'.format(e.message)) print('error with http code: {}'.format(e.status_code)) print('error with ec: {}'.format(e.ec)) print('error with request url: {}'.format(e.request_url)) except Exception as e: print('fail with unknown error: {}'.format(e))
管理桶的权限，请参见桶 ACLs。