PutBucketACL--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

PutBucketACL

最近更新时间：2024.11.14 16:39:31首次发布时间：2023.04.17 15:20:18

功能描述

此接口用于设置桶的访问控制权限。您必须拥有 WRITE_ACP 权限，才可以设置桶的 ACL。

注意事项

一个桶的 ACL 最多支持 100 条 Grant 。该接口为覆盖语义，新设置的 ACL 会覆盖原有桶的 ACL。
您可以使用以下两种方式设置桶的 ACL :

在请求体中设置 ACL
通过头域指定权限

通过头域指定权限

您可以使用以下两种方式指定权限：

通过 x-tos-acl 请求头指定预制的 ACL。预制 ACL 有预定义的授权者和权限。使用该头域，不能在请求中使用其他的头域指定权限。
预制 ACL 如下所示：

预制 ACL	描述
private	私有权限，其他账号没有权限。
public-read	公共读权限，所有用户都有读权限。
public-read-write	公共读写权限，所有用户都有读写权限。
authenticated-read	认证用户读权限，通过鉴权认证的用户有读权限。

使用 x-tos-grant-read、x-tos-grant-read-acp、x-tos-grant-write-acp 和 x-tos-grant-full-control 标头显式指定访问权限。使用这些头域，则不能使用 x-tos-acl 请求头指定预制的 ACL。头域的值为 type=value 的格式， type 有以下两种类型：
- id: 值为账号 ID。
- canned: 值为预定义组。
  预定义组说明如下：
  预定义组
  描述
  AllUsers
  所有用户。
  AuthenticatedUsers
  通过鉴权认证的用户。

预定义组	描述
AllUsers	所有用户。
AuthenticatedUsers	通过鉴权认证的用户。

请求消息样式

PUT /?acl HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: GMT Date
Authorization: authorization string
x-tos-acl: ACL
x-tos-grant-full-control: GrantFullControl
x-tos-grant-read: GrantRead
x-tos-grant-read-acp: GrantReadACP
x-tos-grant-write: GrantWrite
x-tos-grant-write-acp: GranteWriteACP

{   
    "Owner": { "ID": "test-cid" },
    "Grants": [{
        "Grantee": {
          "Type": "CanonicalUser",
          "ID": "test-cid"
        },
        "Permission": "FULL_CONTROL"
      }]
}

请求参数和消息头

该请求使用的公共消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
acl	Query	String	是	-\	代表 PutBucketAcl 请求的特殊标识。
x-tos-acl	Header	String	否	private	桶的访问权限，有效的权限设置包括： `private`：私有的。 `public-read`：公共读。 `public-read-write`：公共读写。 `authenticated-read`：认证用户读。
x-tos-grant-full-control	Header	String	否	id: test-cid	授予指定用户所有权限。
x-tos-grant-read	Header	String	否	id: test-cid	授予指定用户读权限，具体包括获取桶内元数据，获取对象元数据，下载对象，列举桶内对象，列举分片任务的权限。
x-tos-grant-read-non-list	Header	String	否	id: test-cid	取消列举桶内对象和分片任务的权限。 `x-tos-grant-read-non-list` 必须搭配 `x-tos-grant-read-acp` 使用，单独使用，无意义。和 `x-tos-grant-read-acp` 搭配使用时，表示被授权者拥有获取桶元数据，获取对象元数据，下载对象的权限。
x-tos-grant-read-acp	Header	String	否	id: test-cid	授予指定用户查看桶 ACL 的权限。
x-tos-grant-write	Header	String	否	id: test-cid	授予指定用户写权限，具体包括上传对象，覆盖桶内已有对象，删除桶内对象的权限。
x-tos-grant-write-acp	Header	String	否	id: test-cid	授予指定用户修改和删除桶 ACL 的权限。

请求元素

名称	参数类型	是否必选	示例值	说明
Grants	Array	否	-\	对象的访问控制权限根节点。
Grantee	Object	否	-\	被授权用户信息。父节点为 Grants。
Type	String	否	CanonicalUser	用户类型。父节点为 Grantee。
Canned	String	否	AuthenticatedUsers	当 `Type` 为 `Group` 时，使用该字段。取值说明如下： `AllUsers`：所有用户。 `AuthenticatedUsers`：部分通过用户 ID 被授权的用户。父节点为 Grantee。
ID	String	否	20012****	当 `Type` 为 `CanonicalUser` 时，使用该字段，代表被授权的用户 ID。父节点为 Grantee。
Permission	String	否	FULL_CONTROL	授权类型，取值说明如下： `READ`：允许被授权者获取桶元数据，获取对象元数据，下载对象，列举桶内对象和分片任务。 `READ_NON_LIST`：允许被授权者获取桶元数据，获取对象元数据，下载对象。 `WRITE`：允许被授权者创建、覆盖和删除桶中的任意对象，初始化分片任务，上传分片，合并分片，取消分片任务。 `READ_ACP`：允许被授权者读取存储桶的 ACL。 `WRITE_ACP`：允许被授权者修改或删除存储桶的 ACL。 `FULL_CONTROL`：允许被授权者在存储桶上的 READ、WRITE、READ_ACP 和 WRITE_ACP 权限。父节点为 Grants。
Owner	Object	否	不涉及	对象所有者。
ID	String	否	20012****	账号 ID。父节点为 Owner。
BucketAclDelivered	Bool	否	False	是否开启对象默认继承桶 ACL 功能，取值说明如下： `true`：开启对象默认继承桶 ACL 功能。 `false`：关闭对象默认继承桶 ACL 功能。默认为 `false`。说明 `Owner` 和 `BucketAclDelivered` 参数必须一起设置，否则无法开启对象默认继承桶 ACL 功能。

响应消息头

该请求返回公共响应消息头。

响应元素

该请求响应中无消息元素。

请求示例 1

使用请求体设置桶 ACL

PUT /?acl HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 13:59:18 GMT
Authorization: authorization string

{
    "Owner": {
        "ID": "AccountID"
    },
    "Grants": [
        {
            "Grantee": {
                "ID": "test-cid",
                "Type": "CanonicalUser"
            },
            "Permission": "FULL_CONTROL"
        }
    ]
}

请求示例 2

使用 x-tos-acl 头域指定桶 ACL 。

PUT /?acl HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 13:59:18 GMT
Authorization: authorization string
x-tos-acl: public-read

请求示例 3

使用 x-tos-grant-read、x-tos-grant-write 头域指定桶 ACL。

PUT /?acl HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 13:59:18 GMT
Authorization: authorization string
x-tos-grant-read: canned=everyone
x-tos-grant-write: canned=AuthenticatedUsers,id=test-cid

请求示例 4

使用 BucketAclDelivered 开启对象默认继承桶 ACL 功能。

PUT /?acl HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 13:59:18 GMT
Authorization: authorization string
{
    "Owner": {
        "ID": "214748****"
    },
    "BucketAclDelivered": true
}

响应示例

HTTP/1.1 200 OK
x-tos-id-2: 4fac130beeb50032-a444ed0
x-tos-request-id: 4fac130beeb50032-a444ed0
Date: Fri, 30 Jul 2021 13:59:18 GMT
server: TosServer
Content-Length: 0