租户端 存储 对象存储（COS） COS API参考 设置对象ACL

设置对象ACL

最近更新时间: 2025-02-18 16:02:00

功能描述

PUT Object acl 接口用来对某个 Bucket 中的某个的 Object 进行 ACL 表的配置，您可以通过 Header："x-cos-acl"，"x-cos-grant-read"，"x-cos-grant-full-control" 传入 ACL 信息，或者通过 Body 以 XML 格式传入 ACL 信息。

请求

请求示例

  • 复制
    复制成功
PUT /<ObjectKey>?acl HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String

说明：

Authorization: Auth String（详情请参阅请求签名文档）。

请求头

公共头部

该请求操作的实现使用公共请求头，了解公共请求头详情请参阅 公共请求头部 文档。

非公共头部

名称描述类型必选
x-cos-acl定义 Object 的 ACL 属性，有效值：private，public-read，default；默认值：default（继承 Bucket 权限）。
注：当前访问策略条目限制为1000条，如果您不需要进行 Object ACL 控制，请填 default 或者此项不进行设置，默认继承 Bucket 权限		String否
x-cos-grant-read赋予被授权者读的权限。格式：x-cos-grant-read: id="[OwnerUin]"String否
x-cos-grant-full-control赋予被授权者所有的权限。格式：x-cos-grant-full-control: id="[OwnerUin]"String否

请求体

该响应体返回为 application/xml 数据，包含完整节点数据的内容展示如下：

  • 复制
    复制成功
<AccessControlPolicy>
  <Owner>
    <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
    <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
           <URI>http://cam.qcloud.com/groups/global/AllUsers</URI>
      </Grantee>
      <Permission>READ</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
     </Grant>
  </AccessControlList>
</AccessControlPolicy>

具体的数据内容如下：

节点名称（关键字）父节点描述类型必选
AccessControlPolicy无保存 GET Object acl 结果的容器Container是

Container 节点 AccessControlPolicy 的内容：

节点名称（关键字）父节点描述类型必选
OwnerAccessControlPolicyObject 持有者信息Container是
AccessControlListAccessControlPolicy被授权者信息与权限信息Container是

Container 节点 Owner 的内容：

节点名称（关键字）父节点描述类型必选
IDAccessControlPolicy.OwnerObject 持有者 ID，
格式为：qcs::cam::uin/:uin/如果是主帐号， 和 是同一个值		String是
DisplayNameAccessControlPolicy.OwnerObject 持有者的名称String是

Container 节点 AccessControlList 的内容：

节点名称（关键字）父节点描述类型必选
GrantAccessControlPolicy.AccessControlList单个 Object 的授权信息。一个 AccessControlList 可以拥有100条 GrantContainer是

Container 节点 Grant 的内容：

节点名称（关键字）父节点描述类型必选
GranteeAccessControlPolicy.AccessControlList.Grant说明被授权者的信息。type 类型可以为 RootAccount，Subaccount；当 type 类型为 RootAccount 时，ID 中指定的是主帐号;当 type 类型为 Subaccount 时，ID 中指定的是子帐号Container是
PermissionAccessControlPolicy.AccessControlList.Grant指明授予被授权者的权限信息，枚举值：READ，FULL_CONTROLString是

Container 节点 Grantee 的内容：

节点名称（关键字）父节点描述类型必选
URIAccessControlPolicy.AccessControlList.Grant.Grantee指定所有用户String是
IDAccessControlPolicy.AccessControlList.Grant.Grantee用户的 ID，格式为：qcs::cam::uin/:uin/ 如果是主帐号， 和 是同一个值String是
DisplayNameAccessControlPolicy.AccessControlList.Grant.Grantee用户的名称String是

响应

响应头

公共响应头

该响应使用公共响应头，了解公共响应头详情请参阅 公共响应头部 文档。

特有响应头

该请求操作无特殊的响应头部信息。

响应体

该请求响应体为空。

错误码

该响应可能会出现如下错误码信息，常见的错误信息请参阅 错误码 文档。

错误码描述状态码
SignatureDoesNotMatch提供的签名不符合规则，返回该错误码403 Forbidden
NoSuchBucket如果试图添加的规则所在的 Bucket 不存在，返回该错误码404 Not Found
MalformedXMLXML 格式不合法，请跟 Restful API 文档仔细比对400 Bad Request
InvalidRequest请求不合法，如果错误描述中显示"header acl and body acl conflict"，那么表示不能头部和 body 都有 acl 参数400 Bad Request

实际案例

请求

  • 复制
    复制成功
PUT /exampleobject?acl HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Fri, 25 Feb 2017 04:10:22 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484724784;32557620784&q-key-time=1484724784;32557620784&q-header-list=host&q-url-param-list=acl&q-signature=785d9075b8154119e6a075713c1b9e56ff0bddfc
Content-Length: 229
Content-Type: application/x-www-form-urlencoded

<AccessControlPolicy>
  <Owner>
    <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
    <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
           <URI>http://cam.qcloud.com/groups/global/AllUsers</URI>
      </Grantee>
      <Permission>READ</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
     </Grant>
  </AccessControlList>
</AccessControlPolicy>

响应

  • 复制
    复制成功
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 25 Feb 2017 04:10:22 GMT\
Server: tencent-cos
x-cos-request-id: NTg3ZjFjMmJfOWIxZjRlXzZmNDhfMjIw