文档中心

管理桶 ACL（Python SDK）

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

首次发布时间：2023.01.19 17:25:20

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

设置桶的访问权限

注意

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

桶 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 权限信息或请求头中设置。

请求体中填写详细 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))

对象存储