PUT Bucket ACL

文档中心 >

下载PDF文档

描述

此 PUT 操作使用 acl 资源通过访问权限列表为已经存在的用户空间设定访问权限。

当前只有Bucket的所有者拥有该权限

你可以使用下面两种方式来设置对象的权限。

在请求体中指定 ACL。
使用请求头部来设置访问权限。

注意 : 不能同时使用以上两种方式。

请求

语法

下面展示的是通过在请求体中指定 ACL 的方式进行设定。

PUT /?acl HTTP/1.1
Host: {BucketName}.kss.ksyun.com
Date: date
Authorization: authorization string

<AccessControlPolicy>
  <Owner>
    <ID>ID</ID>
    <DisplayName>EmailAddress</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>ID</ID>
        <DisplayName>EmailAddress</DisplayName>
      </Grantee>
      <Permission>Permission</Permission>
    </Grant>
    ...
  </AccessControlList>
</AccessControlPolicy>

请求参数

该接口不使用请求参数。

请求头部

该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。

用户可以通过以下的header为Bucket设置预设的ACL

名称	描述	必须
x-kss-acl	用于对象的预定义权限。类型：String 默认值：private 有效值：`private` &##124; `public-read` &##124; `public-read-write` 约束条件：无	否

如果用户期望为Bucket设置详细的ACL，可以通过以下header设置

名称	描述	必须
x-kss-grant-read	为若干用户授予READ权限。类型：String 默认值：无约束条件：无	否
x-kss-grant-write	为若干用户授予WRITE权限。类型：String 默认值：无约束条件：无	否
x-kss-grant-full-control	为若干用户授予FULL_CONTROL权限。类型：String 默认值：无约束条件：无	否

以上header值的值为以一个逗号","分割的授权列表。每个授权信息的格式为type=value,当前type支持以下几种：

id:被授权者的用户id
uri:被授权的用户组，暂时value仅支持http://acs.ksyun.com/groups/global/AllUsers，表示所有用户(包括匿名用户)

例如，要给所有用户授予WRITE权限:

x-kss-grant-write:uri="http://acs.ksyun.com/groups/global/AllUsers"

## 请求内容

如果用户决定使用请求体来指定访问权限列表，需要使用下表元素。

注意 如果你使用请求体设置ACL，你不能再通过请求头部设置ACL

名称	描述
AccessControlList	包含 `Grant`,`Grantee`,`Permission` 的容器类型：Container 父节点：AccessControlPolicy
AccessControlPolicy	包含了每一个 `Grantee` 对于某个对象的 `ACL` 权限设置信息类型：Container 父节点：无
Grant	包含被授权者和其权限信息。类型：String 父节点：AccessControlPolicy.AccessControlList
Grantee	被授权者，参考`授予权限方式` 类型：String 父节点：AccessControlPolicy.AccessControlList.Grant
DisplayName	Bucket拥有者的名称类型：String 父节点：AccessControlPolicy.Owner
ID	Bucket拥有者的用户ID，或者是被授权者的ID 类型：String 父节点：AccessControlPolicy.Owner 或者 AccessControlPolicy.AccessControlList.Grant
Owner	包含bucket拥有者信息（`DisplayName`,`ID`）的容器类型：Container 父节点：AccessControlPolicy
Permission	指明授予被授权者的权限信息（`FULL_CONTROL`,`READ`,`WRITE`）类型：String 父节点：AccessControlPolicy.AccessControlList.Grant

授予权限方式

用户可以通过以下方式来授予某个用户对用户空间的权限。

通过用户ID,即根据用户ID授予特定用户权限

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser"><ID>ID</ID><DisplayName>GranteesEmail</DisplayName>
</Grantee>

通过URI,授予指定的一组用户权限

<Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group"><URI>http://acs.ksyun.com/groups/global/AllUsers</URI></Grantee>

注意：当前仅支持http://acs.ksyun.com/groups/global/AllUsers，表示所有用户，包括匿名用户。

响应

响应头部

该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。

响应内容

该接口不返回相应内容。

特殊错误

该接口不返回任何特殊错误。

示例

请求示例

PUT /?acl HTTP/1.1
Host: {BucketName}.kss.ksyun.com
Content-Length: 1660
Date: Fri, 26 Dec 2014 06:34:32 GMT
Authorization: authorization string

<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>852b113e7a2f25102679df27bb0ae12b3f85be6BucketOwnerCanonicalUserID</ID>
    <DisplayName>OwnerDisplayName</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>BucketOwnerCanonicalUserID</ID>
        <DisplayName>OwnerDisplayName</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
        <URI xmlns="">http://acs.ksyun.com/groups/global/AllUsers</URI>
      </Grantee>
      <Permission xmlns="">READ</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

响应示例

HTTP/1.1 200 OK
Date: Fri, 26 Dec 2014 06:34:32 GMT
x-kss-request-id: dbea4ce4ec23415b9e454ecfa25ec4d9
Content-Length: 0
Server: Tengine

接口细节分析

Bucket的权限含义详见 ACL
当同时在header中和Body中设置了ACL，最后只有header中的会生效。当同时在header中设置了x-kss-acl和x-kss-grant-*时，后者生效。
对于大部分用户，使用x-kss-acl在header中设置预设的ACL就可以满足大部分需求。对于bucket，一般需要设置x-kss-acl为private。