Description
PUT Bucket acl API is used to write an access control list (ACL) for a bucket. You can set the ACL information through "x-cos-acl", "x-cos-grant-read", and "x-cos-grant-full-control" request headers or the request body in XML format.
Note:
- You can set the ACL information either through request headers or through the request body, otherwise the response returned will conflict.
- PUT Bucket acl is an overwriting operation. The new ACL will overwrite the old one.
- Only the Bucket creator has the permission to perform this operation.
Notes
- You can set the header or the XML body. We recommend you to use only one of them.
- You can set a folder of private bucket to be public, and then all files in the folder will be public. If you set a folder to be private, the public attributes set in the folder will not take effect.
Request
Request Example
PUT /?acl HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String
Note:
Authorization: Auth String (See Request Signature for details.)
Request Header
Common headers:
This request is implemented by using common request headers. For details on common request headers, see the Common Request Headers section.
Non-common headers:
This request is implemented by using the x-cos-acl header in PUT requests to set the bucket access permissions. Currently, bucket access permissions are divided into three types: public-read-write, public-read, and private. If the permissions are not set, private is configured by default. The read, write, or read-write permissions can also be granted individually to users. Details are as follows:
| Name | Description | Type | Required |
|---|---|---|---|
| x-cos-acl | Defines the ACL attribute of a bucket. Valid values: private, public-read-write, and public-read; default value: private | String | No |
| x-cos-grant-read | Grants read access to the grantee. Format: x-cos-grant-read: id="[OwnerUin]" | String | No |
| x-cos-grant-write | Grants write permission to the grantee. Format: x-cos-grant-write: id="[OwnerUin]" | String | No |
| x-cos-grant-full-control | Grants full permission to the grantee. Format: x-cos-grant-full-control: id="[OwnerUin]" | String | No |
Request Body
This request can also be implemented by including specific request parameters in the request body to set the bucket access permissions. You have to choose between including parameters in the request body and including ACL subresources in the request header.
Below is an example with all nodes:
<AccessControlPolicy>
<Owner>
<ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
</Owner>
<AccessControlList>
<Grant>
<Grantee>
<ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee>
<ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
</Grantee>
<Permission>READ</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>
The data are as follows:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| AccessControlPolicy | No | Container for storing the result of the GET Object ACL | Container | Yes |
Content of AccessControlPolicy:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| Owner | AccessControlPolicy | Information of the object owner | Container | Yes |
| AccessControlList | AccessControlPolicy | Information about the grantee and permissions | Container | Yes |
Content of Owner:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| ID | AccessControlPolicy.Owner | ID of the Bucket Owner, formatted as qcs::cam::uin/ :uin/. This is the owner account, so and have the same value. |
String | Yes |
Content of AccessControlList:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| Grant | AccessControlPolicy.AccessControlList | Permission information for a single bucket. An AccessControlList can have 100 grants. | Container | Yes |
Contents of Grant:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| Grantee | AccessControlPolicy.AccessControlList.Grant | Grantee information. Type is RootAccount. | Container | Yes |
| Permission | AccessControlPolicy.AccessControlList.Grant | Specifies the permissions granted to the grantee, with enum values: READ, FULL_CONTROL. | String | Yes |
Contents of Grantee:
| Node Name (Keyword) | Parent Node | Description | Type | Required |
|---|---|---|---|---|
| ID | AccessControlPolicy.AccessControlList.Grant.Grantee | ID of the User, Format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>. The ID should be that of the root account. Therefore, and have the same value. You can also use anyone (representing all types of users) to replace uin/ and uin/. |
String | Yes |
Response
Response Headers
Common Response Headers
This response uses common response headers. For details, see Common Response Headers.
Special Response Headers
There are no special response headers for this response operation.
Response Body
The response body is empty.
Error Analysis
The following describes some special but common errors that may occur with this request:
| Error Code | Description | HTTP Status Code |
|---|---|---|
| InvalidDigest | 400 Bad Request | Content-MD5 provided by the user is inconsistent with Content-MD5 in the body calculated by COS. |
| MalformedXML | 400 Bad Request | The XML syntax of the request body is incorrect. Please compare it carefully with the restful API document. |
| InvalidArgument | 400 Bad Request | Parameter error, see the error message for details. |
Practical Case
Request
PUT /?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>
</Owner>
<AccessControlList>
<Grant>
<Grantee>
<ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
</Grantee>
<Permission>FULL_CONTROL</Permission>
</Grant>
<Grant>
<Grantee>
<ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
</Grantee>
<Permission>READ</Permission>
</Grant>
</AccessControlList>
</AccessControlPolicy>
Response
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 25 Feb 2017 04:10:22 GMT
x-cos-request-id: NTg3ZjFjMmJfOWIxZjRlXzZmNDhfMjIw