tencent cloud

All product documents
Cloud Object Storage
DocumentationCloud Object StorageAPI DocumentationObject APIsAccess Control List (acl)PUT Object acl
PUT Object acl
Download PDF
Last updated: 2024-06-12 15:10:38
PUT Object acl
Last updated: 2024-06-12 15:10:38
Download PDF

Overview

This API is used to write an access control list (ACL) to an object. 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 Object acl is an overwriting operation. The new ACL will overwrite the old one.
You can only grant permissions to Tencent Cloud CAM root accounts or anonymous users. To grant permissions to sub-accounts or user groups, please use the PUT Bucket policy API. For more information about ACL, please see ACL Overview.
To call this API, you need to have permission to write ACL to the object.


Requests

Sample requests

Sample 1
PUT /<ObjectKey>?acl HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Length: 0
Authorization: Auth String
Sample 2
PUT /<ObjectKey>?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 more information).

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 ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default
Note: If you do not need access control for the object, set this header to default or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.
Enum
No
x-cos-grant-read
Grants a user read permission for an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-read-acp
Grants a user read permission for the ACL of an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-write-acp
Grants a user write permission for the ACL of an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No
x-cos-grant-full-control
Grants a user full permission to operate on an object in the format: id="[OwnerUin]" (e.g., id="100000000001"). You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002".
string
No

Request body

The request body contains the application/xml request data, including information about the object 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 Object acl operation
Container
Yes
Content of AccessControlPolicy:
Node Name (Keyword)
Parent Node
Description
Type
Required
Owner
AccessControlPolicy
Information about the object owner
Container
Yes
AccessControlList
AccessControlPolicy
Information about the grantee and permissions
Container
Yes
Content of AccessControlPolicy.Owner:
Node Name (Keyword)
Parent Node
Description
Type
Required
ID
AccessControlPolicy.Owner
Complete ID of the object owner in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
Example: qcs::cam::uin/100000000001:uin/100000000001
string
Yes
Content of AccessControlPolicy.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 AccessControlPolicy.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 set to Group, the child node can only include URI. If set to CanonicalUser, the child node can only include ID.
Container
Yes
Permission
AccessControlPolicy.
AccessControlList.Grant
Permission granted. For the enumerated values, such as READ and FULL_CONTROL, please see Actions on objects in ACL Overview.
Enum
Yes
Content of AccessControlPolicy.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, please see Error Codes.

Samples

Sample 1: configuring ACL through request headers

Request

PUT /exampleobject?acl HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Mon, 09 Sep 2019 13:11:09 GMT
x-cos-acl: public-read
x-cos-grant-read-acp: id="100000000002"
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1568034669;1568041869&q-key-time=1568034669;1568041869&q-header-list=content-length;date;host;x-cos-acl;x-cos-grant-read-acp&q-url-param-list=acl&q-signature=43faf0a3231435a922e16526709c281a537d****
Connection: close

Response

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Mon, 09 Sep 2019 13:11:10 GMT
Server: tencent-cos
x-cos-request-id: NWQ3NjRmNmRfZjZjMjBiMDlfMmE5MWJfMTI3OWZh****

Sample 2: configuring ACL through the request body

Request

PUT /exampleobject?acl HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Tue, 10 Sep 2019 06:32:02 GMT
Content-Type: application/xml
Content-Length: 594
Content-MD5: zUPEBc1TeGrqTqEfPV7rxg==
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO****&q-sign-time=1568097122;1568104322&q-key-time=1568097122;1568104322&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=acl&q-signature=edab1b68ce0f747604906354afbe5702b24c****
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>READ_ACP</Permission>
                </Grant>
            </AccessControlList>
</AccessControlPolicy>

Response

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Tue, 10 Sep 2019 06:32:02 GMT
Server: tencent-cos
x-cos-request-id: NWQ3NzQzNjJfZmVhODBiMDlfMjc5MGVfMTM4OTky****

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

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

Contact Us
Technical Support

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

Submit a Ticket
7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon