tencent cloud

Feedback

Access Control

Last updated: 2022-05-11 12:10:09

    Overview

    This document provides an overview of APIs and SDK code samples for for the ACL of buckets and objects.

    Bucket ACL

    API Operation Description
    PUT Bucket acl Setting bucket ACL Sets the ACL for the specified bucket
    GET Bucket acl Querying bucket ACL Queries the ACL of a specified bucket

    Object ACL

    API Operation Description
    PUT Object acl Setting an object ACL Sets an ACL for an object in a bucket
    GET Object acl Querying an object ACL Queries the ACL of an object

    Bucket ACL

    Setting a bucket ACL

    Description

    The API (PUT Bucket acl) is used to set the ACL for a specified bucket. The AccessControlPolicy parameter and other permission parameters are mutually exclusive and cannot be specified at the same time.

    Method prototype

    put_bucket_acl(Bucket, AccessControlPolicy={}, **kwargs)
    

    Sample request

    # -*- coding=utf-8
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    import logging
    # In most cases, set the log level to INFO. If you need to debug, you can set it to DEBUG and the SDK will print the communication information of the client.
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    # 1. Set user attributes such as secret_id, secret_key, and region. Appid has been removed from CosConfig and thus needs to be specified in Bucket, which is formatted as BucketName-Appid.
    secret_id = 'SecretId'     # Replace it with the actual SecretId, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    secret_key = 'SecretKey'     # Replace it with the actual SecretKey, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.tencentcloud.com/cos5/bucket
                             # For the list of regions supported by COS, see https://www.tencentcloud.com/document/product/436/6224
    token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, visit https://www.tencentcloud.com/document/product/436/14048
    scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This field is optional and is `https` by default
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
    client = CosS3Client(config)
    response = client.put_bucket_acl(
      Bucket='examplebucket-1250000000',
      ACL='public-read'
    )
    

    Sample request with all parameters

    response = client.put_bucket_acl(
      Bucket='examplebucket-1250000000',
      ACL='private'|'public-read'|'public-read-write',
      GrantFullControl='id="100000000002"',
      GrantRead='id="100000000003",id="100000000004"',
      GrantWrite='id="100000000005"',
      AccessControlPolicy={
          'AccessControlList': {
              'Grant': [
                  {
                      'Grantee': {
                          'DisplayName': 'qcs::cam::uin/100000000002:uin/100000000002',
                          'Type': 'CanonicalUser'|'Group',
                          'ID': 'qcs::cam::uin/100000000002:uin/100000000002', # The ID is required when `Type` is `CanonicalUser`
                          'URI': 'http://cam.qcloud.com/groups/global/AllUsers' # The URI is required when `Type` is `Group`
                      },
                      'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
                  },
              ]
          },
          'Owner': {
              'DisplayName': 'qcs::cam::uin/100000000001:uin/100000000001', 
              'ID': 'qcs::cam::uin/100000000001:uin/100000000001' # It must be the ID of the bucket owner
          }
      }
    )
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    ACL ACL of the bucket, such as private, public-read, and public-read-write. For more information, see ACL. String No
    GrantFullControl Grants a specified account read/write permission for a bucket in the format of id="OwnerUin". You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". string No
    GrantRead Grants a specified account read permission for a bucket in the format of id="OwnerUin". You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". string No
    GrantWrite Grants a specified account write permission for a bucket in the format of id="OwnerUin". You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". string No
    AccessControlPolicy Grants a specified account access permission for a bucket. This parameter and other permission parameters are mutually exclusive and cannot be specified at the same time. Dict No

    AccessControlPolicy parameter description:

    Parameter Description Type Required
    Owner Information on the bucket owner, including DisplayName and ID Dict Yes
    AccessControlList Information on the user to whom a bucket permission is granted, including Grant list Dict Yes

    Owner parameter description:

    Parameter Description Type Required
    ID ID of the grantee when Type is CanonicalUser, in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], for example, qcs::cam::uin/100000000001:uin/100000000001. string Yes
    DisplayName Name of the grantee. This parameter can be left empty or be consistent with the value of ID String No

    AccessControlList parameter description:

    Parameter Description Type Required
    Grant Information on the user to whom a bucket permission is granted, including Grantee and Permission List Yes
    Grantee Information on the grantee, including DisplayName, Type, ID, and URI Dict Yes
    Type Type of the grantee: CanonicalUser or Group String Yes
    ID ID of the grantee when Type is CanonicalUser, in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], for example, qcs::cam::uin/100000000001:uin/100000000001. String Yes when Type is CanonicalUser
    URI URI of the preset user group when Type is Group, for example, http://cam.qcloud.com/groups/global/AllUsers. For more information, see ACL. String Yes when Type is Group
    Permission Bucket permissions granted to the grantee. Valid values: FULL_CONTROL (read/write permission), WRITE (write permission), and READ (read permission) String Yes

    Response description

    This API returns None.

    Querying a bucket ACL

    Description

    This API is used to query the ACL of a specified bucket.

    Method prototype

    get_bucket_acl(Bucket, **kwargs)
    

    Sample request

    # -*- coding=utf-8
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    import logging
    # In most cases, set the log level to INFO. If you need to debug, you can set it to DEBUG and the SDK will print the communication information of the client.
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    # 1. Set user attributes such as secret_id, secret_key, and region. Appid has been removed from CosConfig and thus needs to be specified in Bucket, which is formatted as BucketName-Appid.
    secret_id = 'SecretId'     # Replace it with the actual SecretId, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    secret_key = 'SecretKey'     # Replace it with the actual SecretKey, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.tencentcloud.com/cos5/bucket
                             # For the list of regions supported by COS, see https://www.tencentcloud.com/document/product/436/6224
    token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, visit https://www.tencentcloud.com/document/product/436/14048
    scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This field is optional and is `https` by default
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
    client = CosS3Client(config)
    response = client.get_bucket_acl(
      Bucket='examplebucket-1250000000'
    )
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes

    Response description

    This response returns bucket ACL information in Dict format.

    {
       'Owner': {
           'DisplayName': 'qcs::cam::uin/100000000001:uin/100000000001',
           'ID': 'qcs::cam::uin/100000000001:uin/100000000001'
       },
       'AccessControlList': {
           'Grant': [
               {
                   'Grantee': {
                       'DisplayName': 'qcs::cam::uin/100000000002:uin/100000000002',
                       'Type': 'CanonicalUser'|'Group',
                       'ID': 'qcs::cam::uin/100000000002:uin/100000000002',
                       'URI': 'http://cam.qcloud.com/groups/global/AllUsers'
                   },
                   'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
               },
           ]
       }
    }
    
    Parameter Description Type
    Owner Information on the bucket owner, including DisplayName and ID. For more information, see PUT Bucket acl. Dict
    AccessControlList Information on the user to whom a bucket permission is granted, including Grant list. For more information, see PUT Bucket acl. Dict

    Object ACL

    Setting an object ACL

    Description

    The API is used to set the ACL for an object in a bucket. The AccessControlPolicy parameter and other permission parameters cannot be specified at the same time.

    Method prototype

    put_object_acl(Bucket, Key, AccessControlPolicy={}, **kwargs)
    

    Sample request

    # -*- coding=utf-8
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    import logging
    # In most cases, set the log level to INFO. If you need to debug, you can set it to DEBUG and the SDK will print the communication information of the client.
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    # 1. Set user attributes such as secret_id, secret_key, and region. Appid has been removed from CosConfig and thus needs to be specified in Bucket, which is formatted as BucketName-Appid.
    secret_id = 'SecretId'     # Replace it with the actual SecretId, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    secret_key = 'SecretKey'     # Replace it with the actual SecretKey, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.tencentcloud.com/cos5/bucket
                             # For the list of regions supported by COS, see https://www.tencentcloud.com/document/product/436/6224
    token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, visit https://www.tencentcloud.com/document/product/436/14048
    scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This field is optional and is `https` by default
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
    client = CosS3Client(config)
    response = client.put_object_acl(
      Bucket='examplebucket-1250000000',
      Key='exampleobject',
      ACL='public-read'
    )
    

    Sample request with all parameters

    response = client.put_object_acl(
      Bucket='examplebucket-1250000000',
      Key='exampleobject',
      ACL='default'|'private'|'public-read',
      GrantFullControl='id="100000000003"',
      GrantRead='id="100000000003",id="100000000004"',
      AccessControlPolicy={
          'AccessControlList': {
              'Grant': [
                  {
                      'Grantee': {
                          'DisplayName': 'qcs::cam::uin/100000000002:uin/100000000002',
                          'Type': 'CanonicalUser'|'Group',
                          'ID': 'qcs::cam::uin/100000000002:uin/100000000002', # The ID is required when `Type` is `CanonicalUser`
                          'URI': 'http://cam.qcloud.com/groups/global/AllUsers' # The URI is required when `Type` is `Group`
                      },
                      'Permission': 'FULL_CONTROL'|'READ'
                  },
              ]
          },
          'Owner': {
              'DisplayName': 'qcs::cam::uin/100000000001:uin/100000000001',
              'ID': 'qcs::cam::uin/100000000001:uin/100000000001'
          }
      }
    )
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Key Object key, which uniquely identifies an object in a bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, its key is doc/pic.jpg. String Yes
    ACL ACL of the object, such as default, private, and public-read. For more information, see ACL. String No
    GrantFullControl Grants a specified account full permission for an object in the format of id="OwnerUin". You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". string No
    GrantRead Grants a specified account read permission for an object in the format of id="OwnerUin". You can use commas (,) to separate multiple users, for example, id="100000000001",id="100000000002". string No
    AccessControlPolicy Grants a specified account access permission for an object. This parameter and other permission parameters are mutually exclusive and cannot be specified at the same time. Dict No

    AccessControlPolicy parameter description:

    Parameter Description Type Required
    Owner Information on the bucket owner, including DisplayName and ID Dict Yes
    AccessControlList Information on the user to whom a bucket permission is granted, including Grant list Dict Yes

    Owner parameter description:

    Parameter Description Type Required
    ID ID of the grantee when Type is CanonicalUser, in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], for example, qcs::cam::uin/100000000001:uin/100000000001. string Yes
    DisplayName Name of the grantee. This parameter can be left empty or be consistent with the value of ID String No

    AccessControlList parameter description:

    Parameter Description Type Required
    Grant Information on the user to whom a bucket permission is granted, including Grantee and Permission List Yes
    Grantee Information on the grantee, including DisplayName, Type, ID, and URI Dict Yes
    Type Type of the grantee: CanonicalUser or Group String Yes
    ID ID of the grantee when Type is CanonicalUser, in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin], for example, qcs::cam::uin/100000000001:uin/100000000001. String Yes when Type is CanonicalUser
    URI URI of the preset user group when Type is Group, for example, http://cam.qcloud.com/groups/global/AllUsers. For more information, see ACL. String Yes when Type is Group
    Permission Permissions granted to the grantee. Valid values: FULL_CONTROL (full access) and READ (read permission) String Yes

    Response description

    This API returns None.

    Querying an object ACL

    Description

    The API is used to query the ACL of an object.

    Method prototype

    get_object_acl(Bucket, Key, **kwargs)
    

    Sample request

    # -*- coding=utf-8
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    import logging
    # In most cases, set the log level to INFO. If you need to debug, you can set it to DEBUG and the SDK will print the communication information of the client.
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    # 1. Set user attributes such as secret_id, secret_key, and region. Appid has been removed from CosConfig and thus needs to be specified in Bucket, which is formatted as BucketName-Appid.
    secret_id = 'SecretId'     # Replace it with the actual SecretId, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    secret_key = 'SecretKey'     # Replace it with the actual SecretKey, which can be viewed and managed at https://console.tencentcloud.com/cam/capi
    region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.tencentcloud.com/cos5/bucket
                             # For the list of regions supported by COS, see https://www.tencentcloud.com/document/product/436/6224
    token = None               # Token is required for temporary keys but not permanent keys. For more information about how to generate and use a temporary key, visit https://www.tencentcloud.com/document/product/436/14048
    scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This field is optional and is `https` by default
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
    client = CosS3Client(config)
    response = client.get_object_acl(
      Bucket='examplebucket-1250000000',
      Key='exampleobject'
    )
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Key Object key, which uniquely identifies an object in a bucket. For example, if an object's access endpoint is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, its key is doc/pic.jpg. String Yes

    Response description

    Object ACL information in dict type:

    {
       'Owner': {
           'DisplayName': 'qcs::cam::uin/100000000001:uin/100000000001',
           'ID': 'qcs::cam::uin/100000000001:uin/100000000001'
       },
       'AccessControlList': {
           'Grant': [
               {
                   'Grantee': {
                       'DisplayName': 'qcs::cam::uin/100000000002:uin/100000000002',
                       'Type': 'CanonicalUser'|'Group',
                       'ID': 'qcs::cam::uin/100000000002:uin/100000000002',
                       'URI': 'http://cam.qcloud.com/groups/global/AllUsers'
                   },
                   'Permission': 'FULL_CONTROL'|'READ'
               },
           ]
       }
    }
    
    Parameter Description Type
    Owner Information on the object owner, including DisplayName and ID. For more information, see PUT Object acl. Dict
    AccessControlList Information on the user to whom an object permission is granted, including Grant list. For more information, see PUT Object acl. Dict
    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