Overview
This document provides an overview of APIs and SDK code samples for for the ACL of buckets and objects.
Bucket ACL
|
| | Sets the ACL for the specified bucket |
| | Queries the ACL of a specified bucket |
Object ACL
|
| | Sets an ACL for an object in a bucket |
| | 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
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = os.environ['COS_SECRET_ID']
secret_key = os.environ['COS_SECRET_KEY']
region = 'ap-beijing'
token = None
scheme = 'https'
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',
'URI': 'http://cam.qcloud.com/groups/global/AllUsers'
},
'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
},
]
},
'Owner': {
'DisplayName': 'qcs::cam::uin/100000000001:uin/100000000001',
'ID': 'qcs::cam::uin/100000000001:uin/100000000001'
}
}
)
Parameter description
|
| Bucket name in the format of BucketName-APPID | | |
| ACL of the bucket, such as private, public-read, and public-read-write. For more information, see ACL. | | |
| 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". | | |
| 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". | | |
| 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". | | |
| 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. | | |
AccessControlPolicy parameter description:
|
| Information on the bucket owner, including DisplayName and ID | | |
| Information on the user to whom a bucket permission is granted, including Grant list | | |
Owner parameter description:
|
| 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. | | |
| Name of the grantee. This parameter can be left empty or be consistent with the value of ID | | |
AccessControlList parameter description:
|
| Information on the user to whom a bucket permission is granted, including Grantee and Permission | | |
| Information on the grantee, including DisplayName, Type, ID, and URI | | |
| Type of the grantee: CanonicalUser or Group | | |
| 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. | | Yes when Type is CanonicalUser |
| URI of the preset user group when Type is Group, for example, http://cam.qcloud.com/groups/global/AllUsers. For more information, see ACL. | | |
| Bucket permissions granted to the grantee. Valid values: FULL_CONTROL (read/write permission), WRITE (write permission), and READ (read permission) | | |
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
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = os.environ['COS_SECRET_ID']
secret_key = os.environ['COS_SECRET_KEY']
region = 'ap-beijing'
token = None
scheme = 'https'
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
|
| Bucket name in the format of BucketName-APPID | | |
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'
},
]
}
}
|
| Information on the bucket owner, including DisplayName and ID. For more information, see PUT Bucket acl. | |
| Information on the user to whom a bucket permission is granted, including Grant list. For more information, see PUT Bucket acl. | |
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
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = os.environ['COS_SECRET_ID']
secret_key = os.environ['COS_SECRET_KEY']
region = 'ap-beijing'
token = None
scheme = 'https'
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',
'URI': 'http://cam.qcloud.com/groups/global/AllUsers'
},
'Permission': 'FULL_CONTROL'|'READ'
},
]
},
'Owner': {
'DisplayName': 'qcs::cam::uin/100000000001:uin/100000000001',
'ID': 'qcs::cam::uin/100000000001:uin/100000000001'
}
}
)
Parameter description
|
| Bucket name in the format of BucketName-APPID | | |
| 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. | | |
| ACL of the object, such as default, private, and public-read. For more information, see ACL. | | |
| 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". | | |
| 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". | | |
| 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. | | |
AccessControlPolicy parameter description:
|
| Information on the bucket owner, including DisplayName and ID | | |
| Information on the user to whom a bucket permission is granted, including Grant list | | |
Owner parameter description:
|
| 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. | | |
| Name of the grantee. This parameter can be left empty or be consistent with the value of ID | | |
AccessControlList parameter description:
|
| Information on the user to whom a bucket permission is granted, including Grantee and Permission | | |
| Information on the grantee, including DisplayName, Type, ID, and URI | | |
| Type of the grantee: CanonicalUser or Group | | |
| 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. | | Yes when Type is CanonicalUser |
| URI of the preset user group when Type is Group, for example, http://cam.qcloud.com/groups/global/AllUsers. For more information, see ACL. | | |
| Permissions granted to the grantee. Valid values: FULL_CONTROL (full access) and READ (read permission) | | |
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
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = os.environ['COS_SECRET_ID']
secret_key = os.environ['COS_SECRET_KEY']
region = 'ap-beijing'
token = None
scheme = 'https'
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
|
| Bucket name in the format of BucketName-APPID | | |
| 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. | | |
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'
},
]
}
}
|
| Information on the object owner, including DisplayName and ID. For more information, see PUT Object acl. | |
| Information on the user to whom an object permission is granted, including Grant list. For more information, see PUT Object acl. | |
