PUT Bucket acl

Last updated: 2021-09-10 16:23:17

    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.
    • 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 bucket.
    API Explorer is recommended.
    Debug
    API Explorer makes it easy to make online API calls, verify signatures, generate SDK code, search for APIs, etc. You can also use it to query the content of each request as well as its response.

    Request

    Sample requests

    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:

    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 bucket. For the enumerated values such as private (default) and public-read, please see the Preset ACL section in ACL Overview. Enum No
    x-cos-grant-read Grants a user permission to read the bucket in the format of 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 Grants a user permission to write to the bucket in the format of 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 permission to read the ACL of the bucket in the format of 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 permission to write to the ACL of the bucket in the format of 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 the bucket in the format of 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 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, please see Error Codes.

    Samples

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