Help & Documentation>Cloud Object Storage>SDK Documentation>Python SDK>Bucket Operations

Bucket Operations

Last updated: 2023-09-13 11:01:47

On this page:

Feature Overview

This document provides an overview of APIs and SDK code samples for basic bucket operations.
Note
We recommend you use a temporary key as instructed in Generating and Using Temporary Keys to call the SDK for security purposes. When you apply for a temporary key, follow the Notes on Principle of Least Privilege to avoid leaking resources besides your buckets and objects.
If you must use a permanent key, we recommend you follow the Notes on Principle of Least Privilege to limit the scope of permission on the permanent key.
API
Operation
Description
Querying a bucket list
Queries the list of all buckets under a specified account
Creating Bucket
Creates a bucket under a specified account
Checking a bucket and its permission
Checks whether a bucket exists and you have permission to access it
Deleting a bucket
Deletes an empty bucket under a specified account

Querying a bucket list

Note

This API (GET Service) is used to query the list of all buckets in an account.

Method prototype

list_buckets()

Sample Request

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# Under normal circumstances, use the INFO log level. If you need to locate an issue, change it to DEBUG. The SDK will then print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket
                           For a list of all regions supported by COS, please visit https://cloud.tencent.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, see https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This 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.list_buckets(
)

Response description

Query a bucket list in Dict format.
            {
    'Buckets': {
        'Bucket': [
            {
                'Name': 'string',
                'Location': 'string',
                'CreationDate': 'string'
    },
        ],
    },
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
}
}
Parameter name
ParameterDescription
Local Disk Types
Buckets
A buckets list
Dict
Bucket
A buckets list
List
Name
Bucket Name
String
Location
Name of bucket region
String
CreationDate
Time of Bucket creation
String
Owner
Bucket owner information
Dict
DisplayName
Bucket owner name
String
ID
Bucket owner ID
String

Creating Bucket

Note

This API (PUT Bucket) is used to create a bucket under a specified account.

Method prototype

create_bucket(Bucket, BucketAZConfig=None, **kwargs)

Sample Request

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# Under normal circumstances, use the INFO log level. If you need to locate an issue, change it to DEBUG. The SDK will then print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket
                           For a list of all regions supported by COS, please visit https://cloud.tencent.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, see https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)

# Bucket names do not support uppercase letters. The COS backend will automatically convert any uppercase letters entered by the user to lowercase for bucket creation.
response = client.create_bucket(
    Bucket='examplebucket-1250000000'
)

Sample request with all parameters

response = client.create_bucket(
    Bucket='examplebucket-1250000000',
    BucketAZConfig='string',
    ACL='private'|'public-read'|'public-read-write',
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string'    
)

Description

Parameter name
ParameterDescription
Local Disk Types
Required
Bucket
The name of a bucket to create, must be in the format: BucketName-APPID
The bucket name does not support uppercase letters, and the COS backend will automatically convert uppercase letters passed in to lowercase when creating the bucket.
String
Required
BucketAZConfig
AZ configuration of the bucket. To create an MAZ bucket, specify 'MAZ'.
String
Not required
ACL
Sets the bucket ACL, such as 'private', 'public-read', 'public-read-write'
String
Not required
GrantFullControl
Grants a specified account full Read/Write permission for a bucket in the format of id="OwnerUin"
String
Not required
GrantRead
Grants a specified account Read permission for a bucket in the format of id="OwnerUin"
String
Not required
GrantWrite
Grants a specified account Write permission for a bucket in the format of id="OwnerUin"
String
Not required

Response description

This API returns None.

Checking a bucket and its permission

Note

This API is used to verify whether a bucket exists and you have permission to access it.

Method prototype

head_bucket(Bucket)

Sample Request

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# Under normal circumstances, use the INFO log level. If you need to locate an issue, change it to DEBUG. The SDK will then print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket
                           For a list of all regions supported by COS, please visit https://cloud.tencent.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, see https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This 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.head_bucket(
    Bucket='examplebucket-1250000000'
)

Description

Parameter name
ParameterDescription
Local Disk Types
Required
Bucket
The name of a bucket to query. Format: BucketName-APPID
String
Required

Response description

This API returns None.

Deleting a bucket

Note

This API (DELETE Bucket) is used to delete an empty bucket under a specified account.

Method prototype

delete_bucket(Bucket)

Sample Request

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# Under normal circumstances, use the INFO log level. If you need to locate an issue, change it to DEBUG. The SDK will then print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket
                           For a list of all regions supported by COS, please visit https://cloud.tencent.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, see https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This 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.delete_bucket(
    Bucket='examplebucket-1250000000'
)

Description

Parameter name
ParameterDescription
Local Disk Types
Required
Bucket
The name of a bucket to delete, must be in the format: BucketName-APPID
String
Required

Response description

This API returns None.

Checking Whether Buckets Exist

Note

Checking Whether Buckets Exist

Method prototype

bucket_exists(Bucket)

Sample Request

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# Under normal circumstances, use the INFO log level. If you need to locate an issue, change it to DEBUG. The SDK will then print communication information with the server.
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. Set user attributes, including secret_id, secret_key, region, etc. Appid has been removed from CosConfig, please include Appid in the Bucket parameter. Bucket is composed of BucketName-Appid.
secret_id = os.environ['COS_SECRET_ID']     # User <1>SecretId</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
secret_key = os.environ['COS_SECRET_KEY']   # User <1>SecretKey</1>. We recommend that you use a sub-account key and follow the principle of least privilege to reduce risks. For more information on how to obtain a sub-account key, visit https://cloud.tencent.com/document/product/598/37140.
region = 'ap-beijing'      # Replace it with the actual region, which can be viewed in the console at https://console.cloud.tencent.com/cos5/bucket
                           For a list of all regions supported by COS, please visit https://cloud.tencent.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, see https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # Specify whether to use HTTP or HTTPS protocol to access COS. This 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.bucket_exists(
    Bucket='examplebucket-1250000000'
)
print(response)

Description

Parameter name
ParameterDescription
Local Disk Types
Required
Bucket
Bucket name in the format of BucketName-APPID
String
Required

Response description

True indicates that the bucket exists. False indicates that the bucket does not exist.
中国站 - English