PUT Bucket acl

Last updated: 2020-06-23 17:47:37

    Description

    This API is used to write an access control list (ACL) to a bucket. You can pass in the ACL information through the request headers x-cos-acl and x-cos-grant-* or through the request body in XML format.

    • 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 passed in will overwrite the old one.
    • To make this request, you need to have the 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]

    Authorization: Auth String (see Request Signature for details).

    Request Parameters

    This API does not use any request parameter.

    Request Headers

    In addition to common request headers, this API also supports the following request headers. For more information on common request headers, see Common Request Headers.

    Name Description Type Required
    x-cos-acl Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private and public-read, see the “Preset ACL for buckets” section in ACL Overview. Default value: private Enum No
    x-cos-grant-read Allows grantee to read the bucket; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-write Allows grantee to write to the bucket; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-read-acp Allows grantee to read the ACL of the bucket; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-write-acp Allows grantee to write to the ACL of the bucket; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-full-control Grants a user full permission to perform operations on the bucket; format: id="[OwnerUin]", such as id="100000000001". You can use comma (,) to separate multiple users, such as id="100000000001",id="100000000002" string No

    Request Body

    This request body submits the application/xml request data which include the bucket owner information and full authorization information.

    <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 in details below:

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

    Content of the Container node AccessControlPolicy:

    Node Name (Keyword) Parent Node Description Type Required
    Owner AccessControlPolicy Bucket owner information Container Yes
    AccessControlList AccessControlPolicy Information on the grantee and permissions Container Yes

    Content of the Container node 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], such as qcs::cam::uin/100000000001:uin/100000000001 string Yes

    Content of the Container node AccessControlList:

    Node Name (Keyword) Parent Node Description Type Required
    Grant AccessControlPolicy.AccessControlList A single permission entry. One AccessControlList can have up to 100 Grant entries Container Yes

    Content of the Container node AccessControlList.Grant:

    Node Name (Keyword) Parent Node Description Type Required
    Grantee AccessControlPolicy.AccessControlList.Grant Grantee information. xsi:type can be specified as Group or CanonicalUser. If it is specified as Group, the child node includes and can only include URI. If it is specified as CanonicalUser, the child node includes and can only include ID Container Yes
    Permission AccessControlPolicy.AccessControlList.Grant Permissions. For the enumerated values such as WRITE and FULL_CONTROL, see the “Actions on buckets” section in ACL Overview Enum Yes

    Content of the Container node AccessControlList.Grant.Grantee:

    Node Name (Keyword) Parent Node Description Type Required
    URI AccessControlPolicy.AccessControlList.Grant.Grantee Preset user group such as http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers. For more information, see the “Preset user group” section in ACL Overview string Yes if xsi:type of Grantee is specified as Group
    ID AccessControlPolicy.AccessControlList.Grant.Grantee Complete ID of the grantee in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], such as qcs::cam::uin/100000000001:uin/100000000001 string Yes if xsi:type of Grantee is specified as CanonicalUser

    Response

    Response Headers

    This API only returns common response headers. For more information, see Common Response Headers.

    Response Body

    The response body of this API is empty.

    Error Codes

    This API uses standardized error responses and error codes. For more information, see Error Codes .

    Examples

    Example 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****

    Example 2. Configuring ACL through 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****

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help