Tencent Cloud

Recent Pages

PUT Bucket acl

Last updated: 2024-03-28 18:08:32

Overview
This API is used to write an access control list (ACL) for a bucket. You can set the ACL information through the x-cos-acl and x-cos-grant-* 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.
PUT Bucket acl is an overwriting operation. The new ACL will overwrite the old one.
With this API, you can grant permissions to Tencent Cloud CAM root accounts, anonymous users, and sub-users. To grant permissions to user groups, see Associating/Unassociating Policy with/from User Group. For more information about ACL, see ACL Overview.
To call this API, you need to have permission to write ACL to the bucket.
﻿
Request
Sample request
Sample 1
PUT /?acl HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Length: 0
Authorization: Auth String
Sample 2
PUT /?acl HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: application/xml
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String
﻿
[Request Body]
Note: 
In Host: <BucketName-APPID>.cos.<Region>.myqcloud.com,  <BucketName-APPID> is the bucket name followed by the APPID, such as examplebucket-1250000000 (see Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Conventions), and <Region> is a COS region (see Regions and Access Endpoints).
Authorization: Auth String (See Request Signature for details.)
Request parameters
This API has no request parameter.
Request headers
In addition to common request headers, this API also supports the following request headers. For more information about common request headers, please see Common Request Headers.
Header
Description
Type
Required
x-cos-acl
Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private (default) and public-read, see the Preset ACL section in ACL Overview.
Enum
No
x-cos-grant-read
Grants a user read access to a bucket in the format of id="[OwnerUin]" for root accounts such as id="100000000001" or id="[OwnerUin/GrantsUin]" for sub-accounts such as id="100000000001/100000000011". You can separate multiple users by comma, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-write
Grants a user write access to a bucket in the format of id="[OwnerUin]" for root accounts such as id="100000000001" or id="[OwnerUin/GrantsUin]" for sub-accounts such as id="100000000001/100000000011". You can separate multiple users by comma, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-read-acp
Grants a user read access to a bucket ACL in the format of id="[OwnerUin]" for root accounts such as id="100000000001" or id="[OwnerUin/GrantsUin]" for sub-accounts such as id="100000000001/100000000011". You can separate multiple users by comma, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-write-acp
Grants a user write access to a bucket ACL in the format of id="[OwnerUin]" for root accounts such as id="100000000001" or id="[OwnerUin/GrantsUin]" for sub-accounts such as id="100000000001/100000000011". You can separate multiple users by comma, such as id="100000000001",id="100000000002".
string
No
x-cos-grant-full-control
Grants a user full access to a bucket in the format of id="[OwnerUin]" for root accounts such as id="100000000001" or id="[OwnerUin/GrantsUin]" for sub-accounts such as id="100000000001/100000000011". You can separate multiple users by comma, such as id="100000000001",id="100000000002".
string
No
Request body
The request body contains the application/xml data that includes information about the bucket owner and authorization.
<AccessControlPolicy>
    <Owner>
        <ID>string</ID>
    </Owner>
    <AccessControlList>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Group">
                <URI>string</URI>
            </Grantee>
            <Permission>Enum</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>string</ID>
            </Grantee>
            <Permission>Enum</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Type
Required
AccessControlPolicy
None
All request information about the PUT Bucket acl operation
Container
Yes
Content of AccessControlPolicy:
Node Name (Keyword)
Parent Node
Description
Type
Required
Owner
AccessControlPolicy
Information about the bucket 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
Complete ID of the bucket owner in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
 Example: qcs::cam::uin/100000000001:uin/100000000001
string
Yes
Content of AccessControlList:
Node Name (Keyword)
Parent Node
Description
Type
Required
Grant
AccessControlPolicy.AccessControlList
A single permission. Each AccessControlList supports up to 100 Grant nodes.
Container
Yes
Content of AccessControlList.Grant:
Node Name (Keyword)
Parent Node
Description
Type
Required
Grantee
AccessControlPolicy.AccessControlList.Grant
Grantee information. xsi:type can be set to Group or CanonicalUser. If it’s set to Group, the child node can only include URI. If it’s set to CanonicalUser, the child node can only include ID.
Container
Yes
Permission
AccessControlPolicy.AccessControlList.Grant
Permission granted. For the enumerated values such as WRITE and FULL_CONTROL, please see  Actions on buckets in ACL Overview﻿
Enum
Yes
Content of AccessControlList.Grant.Grantee:
Node Name (Keyword)
Parent Node
Description
Type
Required
URI
AccessControlPolicy.AccessControlList.Grant.Grantee
Preset user group. For more information, please see Preset user group in ACL Overview.
Example: http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers
string
Required if xsi:type of the Grantee is set to Group
ID
AccessControlPolicy.AccessControlList.Grant.Grantee
Compete ID of the grantee in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
Example: qcs::cam::uin/100000000001:uin/100000000001
string
Required if xsi:type of the grantee is set to CanonicalUser
Response
Response headers
This API only returns Common Response Headers.
Response body
The response body of this API is empty.
Error codes
This API returns common error responses and error codes. For more information, see Error Codes.
Examples
Sample 1: configuring ACL through request headers
Request
PUT /?acl HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Mon, 17 Jun 2019 08:30:12 GMT
x-cos-acl: public-read
x-cos-grant-write: id="100000000002"
x-cos-grant-read-acp: id="100000000002"
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1560760212;1560767412&q-key-time=1560760212;1560767412&q-header-list=content-length;date;host;x-cos-acl;x-cos-grant-read-acp;x-cos-grant-write&q-url-param-list=acl&q-signature=5b10c6ea4e6c9630c085e1f85476c76d8c4e****
Connection: close
Response
HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Mon, 17 Jun 2019 08:30:13 GMT
Server: tencent-cos
x-cos-request-id: NWQwNzRmOTRfODhjMjJhMDlfMWRlYl81Mzc0****
Sample 2: configuring ACL through the request body
Request
PUT /?acl HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Mon, 17 Jun 2019 08:30:13 GMT
Content-Type: application/xml
Content-Length: 812
Content-MD5: 1qS+8SqnivarcO6Z11R0nw==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1560760213;1560767413&q-key-time=1560760213;1560767413&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=acl&q-signature=70f96b91823f3715905df125d96fe447554e****
Connection: close
﻿
<AccessControlPolicy>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
    </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/100000000002:uin/100000000002</ID>
            </Grantee>
            <Permission>WRITE</Permission>
        </Grant>
        <Grant>
            <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
                <ID>qcs::cam::uin/100000000002:uin/100000000002</ID>
            </Grantee>
            <Permission>READ_ACP</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>
Response
HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Mon, 17 Jun 2019 08:30:13 GMT
Server: tencent-cos
x-cos-request-id: NWQwNzRmOTVfMzBjMDJhMDlfOTM3MF8yNzdj****
﻿

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support

tencent cloud

Recent Pages

PUT Bucket acl

Overview

Request

Sample request

Request parameters

Request headers

Request body

Response

Response headers

Response body

Error codes

Examples

Sample 1: configuring ACL through request headers

Request

Response

Sample 2: configuring ACL through the request body

Request

Response

Was this page helpful?

Was this page helpful?

Header	Description	Type	Required
x-cos-acl	Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as `private` (default) and `public-read`, see the Preset ACL section in ACL Overview.	Enum	No
x-cos-grant-read	Grants a user read access to a bucket in the format of `id="[OwnerUin]"` for root accounts such as `id="100000000001"` or `id="[OwnerUin/GrantsUin]"` for sub-accounts such as `id="100000000001/100000000011"`. You can separate multiple users by comma, such as `id="100000000001",id="100000000002"`.	string	No
x-cos-grant-write	Grants a user write access to a bucket in the format of `id="[OwnerUin]"` for root accounts such as `id="100000000001"` or `id="[OwnerUin/GrantsUin]"` for sub-accounts such as `id="100000000001/100000000011"`. You can separate multiple users by comma, such as `id="100000000001",id="100000000002"`.	string	No
x-cos-grant-read-acp	Grants a user read access to a bucket ACL in the format of `id="[OwnerUin]"` for root accounts such as `id="100000000001"` or `id="[OwnerUin/GrantsUin]"` for sub-accounts such as `id="100000000001/100000000011"`. You can separate multiple users by comma, such as `id="100000000001",id="100000000002"`.	string	No
x-cos-grant-write-acp	Grants a user write access to a bucket ACL in the format of `id="[OwnerUin]"` for root accounts such as `id="100000000001"` or `id="[OwnerUin/GrantsUin]"` for sub-accounts such as `id="100000000001/100000000011"`. You can separate multiple users by comma, such as `id="100000000001",id="100000000002"`.	string	No
x-cos-grant-full-control	Grants a user full access to a bucket in the format of `id="[OwnerUin]"` for root accounts such as `id="100000000001"` or `id="[OwnerUin/GrantsUin]"` for sub-accounts such as `id="100000000001/100000000011"`. You can separate multiple users by comma, such as `id="100000000001",id="100000000002"`.	string	No

Node Name (Keyword)	Parent Node	Description	Type	Required
AccessControlPolicy	None	All request information about the `PUT Bucket acl` operation	Container	Yes

tencent cloud

Sign Up

Log in

Recent Pages

PUT Bucket acl

Overview

Request

Sample request

Request parameters

Request headers

Request body

Response

Response headers

Response body

Error codes

Examples

Sample 1: configuring ACL through request headers

Request

Response

Sample 2: configuring ACL through the request body

Request

Response

Was this page helpful?

Was this page helpful?