Help & Documentation>Cloud Object Storage>API Documentation>Bucket APIs>Access Control List (acl)>GET Bucket acl

GET Bucket acl

Last updated: 2023-09-19 18:50:34

On this page:

Feature Overview

This API is used to query the access control list (ACL) of a bucket. To call this API, you need to have permission to read the ACL of the bucket.


Requests

Sample Request

GET /?acl HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Note
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, where <BucketName-APPID> is the bucket name with the APPID suffix, such as examplebucket-1250000000. You can refer to the Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Convention documentation. <Region> represents the available regions for COS, which can be found in the Regions and Access Domain Names documentation.
Authorization: Auth String (For more information, see Request Signature.)

Request Parameters

This API has no request parameter.

Request Header

This API only uses Common Request Headers.

Request Body

The request body of this request is empty.

Response

Response Header

This API only returns Common Response Headers.

Response Body

A successful query returns the application/xml data that includes information about the bucket owner and authorization.
<AccessControlPolicy>
    <Owner>
        <ID>string</ID>
        <DisplayName>string</DisplayName>
    </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>
                <DisplayName>string</DisplayName>
            </Grantee>
            <Permission>Enum</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>
The nodes are described as follows:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
AccessControlPolicy
-
Storing all information from the GET Bucket ACL result
Container
Content of AccessControlPolicy:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Owner
AccessControlPolicy
Bucket owner information
Container
AccessControlList
AccessControlPolicy
Information about the grantee and permissions
Container
Content of Owner:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
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
DisplayName
AccessControlPolicy.Owner
Bucket owner name
string
Content of AccessControlList:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Grant
AccessControlPolicy.AccessControlList
A single permission
Container
Content of AccessControlList.Grant:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
Grantee
AccessControlPolicy.AccessControlList.Grant
Grantee information, with xsi:type as Group or CanonicalUser. When set to Group, the child node includes only URI. When set to CanonicalUser, the child node includes only ID and DisplayName.
Container
Permission
AccessControlPolicy.AccessControlList.Grant
Granted permission information, please refer to the bucket operation section in the ACL Overview document for enumeration values, such as WRITE, FULL_CONTROL, etc.
Enum
Content of AccessControlList.Grant.Grantee:
Node Name (Keyword)
Parent Node
Description
Local Disk Types
URI
AccessControlPolicy.AccessControlList.Grant.Grantee
Preset user groups, please refer to the preset user groups section in the ACL Overview document, such as http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers.
string
ID
AccessControlPolicy.AccessControlList.Grant.Grantee
Grantee's complete ID, formatted as qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], such as qcs::cam::uin/100000000001:uin/100000000001.
string
DisplayName
AccessControlPolicy.AccessControlList.Grant.Grantee
Name of the grantee
string

Error Codes

This API returns common error responses and error codes. For more information, see Error Codes.

Examples

Requests

GET /?acl HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Mon, 17 Jun 2019 08:37:35 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1560760655;1560767855&q-key-time=1560760655;1560767855&q-header-list=date;host&q-url-param-list=acl&q-signature=24b9d377eac860917a33c8c298042ce5b1a5**
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1035
Connection: close
Date: Mon, 17 Jun 2019 08:37:36 GMT
Server: tencent-cos
x-cos-request-id: NWQwNzUxNTBfMzdiMDJhMDlfOWM0Nl85NDFk****

<AccessControlPolicy>
    <Owner>
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
    </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>
                <DisplayName>qcs::cam::uin/100000000002:uin/100000000002</DisplayName>
            </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>
                <DisplayName>qcs::cam::uin/100000000002:uin/100000000002</DisplayName>
            </Grantee>
            <Permission>READ_ACP</Permission>
        </Grant>
    </AccessControlList>
</AccessControlPolicy>

中国站 - English