PUT Object ACL

描述

此PUT操作使用 acl 的子集为已存在于 bucket 中的 object 设置访问控制权限(ACL)。

使用此接口，必须是bucket的所有者或具有ks3:PutObjectAcl权限。

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

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

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

接口细节分析

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

请求

语法

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

PUT /{ObjectKey}?acl HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

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

注意：

• endpoint与Region对应关系
• SignatureValue签名算法

请求参数

该接口不使用请求参数。

请求头部

该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。
用户可以通过以下的header为Object设置预设的ACL

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

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

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

以上header的值为以一个逗号","分割的授权列表。每个授权信息的格式为type=value，当前type支持被授权者的用户id：

• 例如，要给id为1234578和3344211的两个用户授予READ权限:
  x-kss-grant-read:id=“1234578”,id=“3344211”

请求内容

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

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

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

响应

响应头部

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

响应内容

该接口不返回相应内容。

特殊错误

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

示例

请求示例

PUT /my-image.jpg ?acl HTTP/1.1
Host: ks3-example.ks3-cn-beijing.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>73410125</ID>
        <DisplayName>73410125</DisplayName>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>73404060</ID>
                <DisplayName>73404060</DisplayName>
            </Grantee>
            <Permission>FULL_CONTROL</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>73406240</ID>
                <DisplayName>73406240</DisplayName>
            </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
Connection: keep-alive
Server: KS3