Help & DocumentationCloud Object Storage

API Documentation

Last updated: 2019-09-23 12:07:56

The documentation is not available now.

For a successful operation of COS XML API Python SDK, dict or None is returned. For a failed operation, an exception (CosClientError and CosServiceError) is thrown. An error message is provided for the corresponding exception type. For more information, please see Exception Types at the end of this document.

For more information on the definitions of SecretId, SecretKey, Bucket and other terms and how to obtain them, please see COS Glossary.

Bucket APIs

Create Bucket

Feature description

This API is used to create a Bucket under the specified account. An error is returned if a bucket exists.

Method prototype

create_bucket(Bucket, **kwargs)

Request example

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

Parameters

Parameter Name Description Type Required
Bucket The name of the bucket to be created, in the format of bucketname-appid String Yes
ACL Sets the bucket ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write buckets in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read buckets in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write buckets in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No

Returned result

The returned value for this method is None.

Delete Bucket

Feature description

This API is used to delete an existing Bucket under the specified account. The Bucket must be empty before it can be deleted.

Method prototype

delete_bucket(Bucket)

Request example

response = client.delete_bucket(
    Bucket='test01-123456789'
)

Parameters

Parameter Name Description Type Required
Bucket Name of the Bucket to be deleted, in the format of bucketname-appid String Yes

Returned result

The returned value for this method is None.

Check whether a Bucket exists

Feature description

This API is used to check whether a bucket exists or whether you have the access to it.

Method prototype

head_bucket(Bucket)

Request example

response = client.head_bucket(
    Bucket='test01-123456789'
)

Parameters

Parameter Name Description Type Required
Bucket The name of the Bucket to be queried, in the format of bucketname-appid String Yes

Returned result

The returned value for this method is None.

Obtain the Bucket's region information

Feature description

This API is used to query the information on the region in which a bucket resides.

Method prototype

get_bucket_location(Bucket)

Request example

response = client.get_bucket_location(
    Bucket='test01-123456789'
)

Parameters

Parameter Name Description Type Required
Bucket The name of the Bucket to be queried, in the format of bucketname-appid String Yes

Returned result

The Bucket's region information. Type is dict.

{
    'LocationConstraint': 'ap-beijing-1'|'ap-beijing'|'ap-shanghai'|'ap-guangzhou'|'ap-chengdu'|'ap-chongqing'|'ap-singapore'|'ap-hongkong'|'na-toronto'|'eu-frankfurt'|'ap-mumbai'|'ap-seoul'|'na-siliconvalley'|'na-ashburn'
}
Parameter Name Description Type
LocationConstraint The information on the region in which the Bucket resides String

List all files under the Bucket

Feature description

This API is used to get all Objects under the specified Bucket.

Method prototype

list_objects(Bucket, Delimiter="", Marker="", MaxKeys=1000, Prefix="", EncodingType="", **kwargs)

Request example

response = client.list_objects(
    Bucket='test01-123456789',
    Delimiter='string',
    Marker='string',
    MaxKeys=100,
    Prefix='string',
    EncodingType='url'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Delimiter Sets a delimiter, for example, as "/" to simulate a folder. It is left empty by default. String No
Marker Marks the starting point of the list of returned objects. Entries are listed using UTF-8 binary order by default. String No
MaxKeys The maximum number of returned objects. Default is 1,000. Int No
Prefix Filters the keys of objects by matching the objects prefixed with this parameter. It is left empty by default. String No
EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url String No

Returned result

The meta information of objects. Type is dict:

{
    'MaxKeys': '1000', 
    'Prefix': 'string',
    'Delimiter': 'string',
    'Marker': 'string',
    'NextMarker': 'string',
    'Name': 'test04-1252448703',  
    'IsTruncated': 'false'|'true',
    'EncodingType': 'url',
    'Contents':[
        {
            'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
            'StorageClass': 'STANDARD', 
            'Key': 'zh.cn.txt'
            'Owner': {
                'DisplayName': '1252448703',
                'ID': '1252448703'
            }, 
            'LastModified': '2017-08-08T09:43:35.000Z', 
            'Size': '23'
        },
    ],
    'CommonPrefixes':[
        {
            'Prefix': 'string'
        },
    ],
}
Parameter Name Description Type
MaxKeys The maximum number of returned objects. Default is 1,000. String
Prefix Filters the keys of objects by matching the objects prefixed with this parameter. It is left empty by default. String
Delimiter Sets a delimiter, for example, as "/" to simulate a folder. It is left empty by default. String
Marker Marks the starting point of the list of returned objects. Entries are listed using UTF-8 binary order by default. String
NextMarker Marks the starting point of the next list of returned if IsTruncated is true. String
Name Bucket name, in the format of bucketname-appid String
IsTruncated Indicates whether the returned objects are truncated String
EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url String
Contents The list containing the meta information of all objects, including 'ETag', 'StorageClass', 'Key', 'Owner', 'LastModified', 'Size', etc. List
CommonPrefixes All keys starting with Prefix and ending with Delimiter are grouped into the same type List

List all multipart uploads under the Bucket

Feature description

This API is used to get all multipart uploads in progress under the specified Bucket.

Method prototype

list_multipart_uploads(Bucket, Prefix="", Delimiter="", KeyMarker="", UploadIdMarker="", MaxUploads=1000, EncodingType="", **kwargs)

Request example

response = client.list_multipart_uploads(
    Bucket='test01-123456789',
    Prefix='string',
    Delimiter='string',
    KeyMarker='string',
    UploadIdMarker='string'
    MaxUploads=100,
    EncodingType='url'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Prefix Filters the keys of multipart uploads by matching the multipart uploads prefixed with this parameter. It is left empty by default. String No
Delimiter Sets a delimiter. It is left empty by default. String No
KeyMarker Marks the starting point of a multipart upload task. It is used with UploadIdMarker. String No
UploadIdMarker Marks the starting point of a multipart upload task. It is used with KeyMarker. If KeyMarker is not specified, UploadIdMarker will be ignored. String No
MaxUploads The maximum number of returned multipart uploads. Default is 1,000. Int No
EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url String No

Returned result

The information of a multipart upload task. Type is dict:

{
    'Bucket': 'test04-1252448703',
    'Prefix': 'string',
    'Delimiter': 'string',
    'KeyMarker': 'string',
    'UploadIdMarker': 'string',
    'NextKeyMarker': 'string',
    'NextUploadIdMarker': 'string',
    'MaxUploads': '1000',
    'IsTruncated': 'true'|'false',,
    'EncodingType': 'url',
    'Upload':[
        {
            'UploadId': 'string',
            'Key': 'string',
            'Initiated': 'string',
            'StorageClass': 'STANDARD',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            },
            'Initiator': {
                'ID': 'string',
                'DisplayName': 'string'
            }
        },
    ],
    'CommonPrefixes':[
        {
            'Prefix': 'string'
        },
    ],
}
Parameter Name Description Type
Bucket Bucket name, in the format of bucketname-appid String
Prefix Filters the keys of multipart uploads by matching the multipart uploads prefixed with this parameter. It is left empty by default. String
Delimiter Sets a delimiter. It is left empty by default. String
KeyMarker Marks the starting point of a multipart upload task. It is used with UploadIdMarker. String
UploadIdMarker Marks the starting point of uploadid for a multipart upload task. It is used with KeyMarker. If KeyMarker is not specified, UploadIdMarker will be ignored. String
NextKeyMarker Marks the starting point of the next list of keys of multipart uploads String
NextUploadIdMarker Marks the starting point of the next list of uploadid of multipart uploads String
MaxUploads The maximum number of returned multipart uploads. Default is 1,000. Int
IsTruncated Indicates whether the returned multipart uploads are truncated String
EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url String
Upload The list containing information of all multipart uploads, including 'UploadId', 'StorageClass', 'Key', 'Owner', 'Initiator', 'Initiated', etc. List
CommonPrefixes All keys starting with Prefix and ending with Delimiter are grouped into the same type List

Set Bucket ACL information

Feature description

This API is used to set the Bucket ACL information by passing header through ACL, GrantFullControl, GrantRead, GrantWrite or by passing body through AccessControlPolicy. You can only use one of these two methods, otherwise a conflict is returned.

Method prototype

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

Request example

response = client.put_bucket_acl(
    Bucket='test01-123456789',
    ACL='private'|'public-read'|'public-read-write',
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string',
    AccessControlPolicy={
        'Grant': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'Type': 'CanonicalUser'|'Group',
                    'ID': 'string',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
            },
        ],
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
ACL Sets the bucket ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write buckets in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read buckets in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write buckets in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
AccessControlPolicy Grants the specified account the access to buckets. For more information on the format, please see the response for "get bucket acl". Dict No

Returned result

The returned value for this method is None.

Get Bucket ACL information

Feature description

This API is used to set the ACL information of the specified Bucket.

Method prototype

get_bucket_acl(Bucket, **kwargs)

Request example

response = client.get_bucket_acl(
    Bucket='test01-123456789',
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes

Returned result

Bucket ACL information. Type is dict.

{
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'Grant': [
        {
            'Grantee': {
                'DisplayName': 'string',
                'Type': 'CanonicalUser'|'Group',
                'ID': 'string',
                'URI': 'string'
            },
            'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
        },
    ]
}
Parameter Name Description Type
Owner Information of the Bucket owner, including DisplayName and ID Dict
Grant Information of a user granted the Bucket permissions, including Grantee and Permission List
Grantee Information of grantee, including DisplayName, Type, ID and URI Dict
DisplayName Name of grantee String
Type Type of grantee: CanonicalUser and Group String
ID ID of grantee when Type is CanonicalUser String
URI URI of grantee when Type is Group String
Permission Bucket permissions of grantee. Available values: FULL_CONTROL (read and write permissions), WRITE (write permission), and READ (read permission) String

Set Bucket cross-origin configuration

Feature description

This API is used to set the cross-origin resource configuration for the specified Bucket.

Method prototype

put_bucket_cors(Bucket, CORSConfiguration={}, **kwargs)

Request example

response = client.put_bucket_cors(
    Bucket='test01-123456789',
    CORSConfiguration={
        'CORSRule': [
            {
                'ID': 'string',
                'MaxAgeSeconds': 100,
                'AllowedOrigin': [
                    'string',
                ],
                'AllowedMethod': [
                    'string',
                ],
                'AllowedHeader': [
                    'string',
                ],
                'ExposeHeader': [
                    'string',
                ]
            }
        ]
    },
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
CORSRule Sets the appropriate cross-origin rules, including ID, MaxAgeSeconds, AllowedOrigin, AllowedMethod, AllowedHeader, and ExposeHeader List Yes
ID Sets rule ID String No
MaxAgeSeconds Sets the validity period of the results obtained by OPTIONS Int No
AllowedOrigin Sets allowed access sources, e.g. "http://cloud.tencent.com". The wildcard "*" is supported. Dict Yes
AllowedMethod Sets allowed methods, including GET, PUT, HEAD, POST, and DELETE Dict Yes
AllowedHeader Sets the custom HTTP request headers that are allowed to be used by requests. The wildcard "*" is supported. Dict No
ExposeHeader Sets the custom header information that can be received by the browser from the server end. Dict No

Returned result

The returned value for this method is None.

Get Bucket cross-origin configuration

Feature description

This API is used to get the cross-origin configuration of the specified Bucket.

Method prototype

get_bucket_cors(Bucket, **kwargs)

Request example

response = client.get_bucket_cors(
    Bucket='test01-123456789',
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes

Returned result

Bucket cross-origin configuration. Type is dict.

{
    'CORSRule': [
        {
            'ID': 'string',
            'MaxAgeSeconds': 100,
            'AllowedOrigin': [
                'string',
            ],
            'AllowedMethod': [
                'string',
            ],
            'AllowedHeader': [
                'string',
            ],
            'ExposeHeader': [
                'string',
            ],
        }
    ]
}
Parameter Name Description Type
CORSRule Cross-origin rules, including ID, MaxAgeSeconds, AllowedOrigin, AllowedMethod, AllowedHeader, and ExposeHeader List
ID Rule ID String
MaxAgeSeconds The validity period of the results obtained by OPTIONS request String
AllowedOrigin Allowed access sources, e.g. "http://cloud.tencent.com". The wildcard "*" is supported. Dict
AllowedMethod Allowed methods, including GET, PUT, HEAD, POST, and DELETE Dict
AllowedHeader The custom HTTP request headers that are allowed to be used by requests. The wildcard "*" is supported. Dict
ExposeHeader Sets the custom header information that can be received by the browser from the server end. Dict

Delete Bucket cross-origin configuration

Feature description

This API is used to delete the cross-origin configuration of the specified Bucket.

Method prototype

delete_bucket_cors(Bucket, **kwargs)

Request example

response = client.delete_bucket_cors(
    Bucket='test01-123456789',
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes

Returned result

The returned value for this method is None.

Set Bucket lifecycle configuration

Feature description

This API is used to set the lifecycle configuration of the specified Bucket.

Method prototype

put_bucket_lifecycle(Bucket, LifecycleConfiguration={}, **kwargs)

Request example

from qcloud_cos import get_date
response = client.put_bucket_lifecycle(
    Bucket='test01-123456789',
    LifecycleConfiguration={
        'Rule': [
            {
                'ID': 'string',
                'Filter': {
                    'Prefix': 'string',
                    'Tag': [
                        {
                            'Key': 'string',
                            'Value': 'string'
                        }
                    ]
                },
                'Status': 'Enabled'|'Disabled',
                'Expiration': {
                    'Days': 100,
                    'Date': get_date(2018, 4, 20)
                },
                'Transition': [
                    {
                        'Days': 100,
                        'Date': get_date(2018, 4, 20),
                        'StorageClass': 'Standard_IA'|'Archive'
                    },
                ],
                'NoncurrentVersionExpiration': {
                    'NoncurrentDays': 100
                },
                'NoncurrentVersionTransition': [
                    {
                        'NoncurrentDays': 100,
                        'StorageClass': 'Standard_IA'
                    },
                ],
                'AbortIncompleteMultipartUpload': {
                    'DaysAfterInitiation': 100
                }
            }
        ]   
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Rule Sets the appropriate rules, including ID, Filter, Status, Expiration, Transition, NoncurrentVersionExpiration, NoncurrentVersionTransition, and AbortIncompleteMultipartUpload List Yes
ID Sets rule ID String No
Filter Describes a collection of Objects that are subject to the rules. To set rules for all objects in the bucket, leave Prefix empty. Dict Yes
Status Sets whether Rule is enabled. Available values: Enabled or Disabled Dict Yes
Expiration Sets the expiration rule for Object. You can specify the number of days (Days) or the specified date (Date). The format of Date must be GMT ISO 8601. You can specify the date using get_date method. Dict No
Transition Sets the rule for changing the storage type of Object. You can specify the number of days (Days) or the specified date (Date). The format of Date must be GMT ISO 8601. You can specify the date using get_date method. Available values for StorageClass: Standard_IA and Archive. Multiple rules can be set at a time. List No
NoncurrentVersionExpiration Sets the expiration rule for noncurrent Object versions. You can specify the number of days (NoncurrentDays). Dict No
NoncurrentVersionTransition Sets the rule for changing the storage type of noncurrent Object versions. You can specify the number of days (NoncurrentDays). Available value for StorageClass: Standard_IA. Multiple rules can be set at a time. List No
AbortIncompleteMultipartUpload Indicates the number of days within which the multipart upload must be completed after the upload starts. Dict No

Returned result

The returned value for this method is None.

Get Bucket lifecycle configuration

Feature description

This API is used to get the lifecycle configuration of the specified Bucket.

Method prototype

get_bucket_lifecycle(Bucket, **kwargs)

Request example

response = client.get_bucket_lifecycle(
    Bucket='test01-123456789',
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes

Returned result

Bucket lifecycle configuration. Type is dict.

{
    'Rule': [
        {
            'ID': 'string',
            'Filter': {
                'Prefix': 'string',
                'Tag': [
                        {
                            'Key': 'string',
                            'Value': 'string'
                        }
                ]
            },
            'Status': 'string',
            'Expiration': {
                'Days': 100,
                'Date': 'string'
            },
            'Transition': [
                {
                    'Days': 100,
                    'Date': 'string',
                    'StorageClass': 'STANDARD_IA'|'Archive'
                },
            ],
            'NoncurrentVersionExpiration': {
                'NoncurrentDays': 100
            },
            'NoncurrentVersionTransition': [
                {
                    'NoncurrentDays': 100,
                    'StorageClass': 'STANDARD_IA'
                },
            ],
            'AbortIncompleteMultipartUpload': {
                'DaysAfterInitiation': 100
            }
        }
    ]   
}
Parameter Name Description Type
Rule Rules, including ID, Filter, Status, Expiration, Transition, NoncurrentVersionExpiration, NoncurrentVersionTransition, and AbortIncompleteMultipartUpload List
ID Rule ID String
Filter Describes a collection of Objects that are subject to the rules. Dict
Status Indicates whether the rule is enabled. Available values: Enabled and Disabled Dict
Expiration Expiration rule for Object. You can specify the number of days (Days) or the specified date (Date). Dict
Transition Rule for changing the storage type of Object. You can specify the number of days (Days) or the specified date (Date). Available values for StorageClass: Standard_IA and Archive. List
NoncurrentVersionExpiration Expiration rule for noncurrent Object versions. You can specify the number of days (NoncurrentDays). Dict
NoncurrentVersionTransition Rule for changing the storage type of noncurrent Object versions. You can specify the number of days (NoncurrentDays). Available value for StorageClass: Standard_IA. List
AbortIncompleteMultipartUpload Number of days within which the multipart upload must be completed after the upload starts. Dict

Delete Bucket lifecycle configuration

Feature description

This API is used to delete the lifecycle configuration of the specified Bucket.

Method prototype

delete_bucket_lifecycle(Bucket, **kwargs)

Request example

response = client.delete_bucket_lifecycle(
    Bucket='test01-123456789',
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes

Returned result

The returned value for this method is None.

Object APIs

Simple Upload of File

Feature description

This API is used to upload a local file or an input stream to the specified Bucket. It is recommended to upload small files not larger than 20 MB. The file size for a single upload is limited to 5 GB. Use multipart upload to upload larger files.

Method prototype

put_object(Bucket, Body, Key, **kwargs)

Request example

response = client.put_object(
    Bucket='test01-123456789',
    Body=b'abc'|file,
    Key='test.txt',
)

Request example for all parameters

response = client.put_object(
    Bucket='test01-123456789',
    Body=b'abc'|file,
    Key='test.txt',
    ACL='private'|'public-read'|'public-read-write',  # Use this parameter with caution. Otherwise, a limit of 1,000 ACL rules may be reached.
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string',
    StorageClass='STANDARD'|'STANDARD_IA',
    Expires='string',
    CacheControl='string',
    ContentType='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength='123',
    ContentMD5='string',
    Metadata={
        'x-cos-meta-key1': 'value1',
        'x-cos-meta-key2': 'value2'
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Body The content of the uploaded file, which can be a file stream or a byte stream file/bytes Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
ACL Sets file ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
StorageClass Sets file storage type: STANDARD and STANDARD_IA. Default: STANDARD String No
Expires Sets Content-Expires String No
CacheControl Cache policy. Sets Cache-Control String No
ContentType Content type. Sets Content-Type String No
ContentDisposition File name. Sets Content-Disposition String No
ContentEncoding Encoding format. Sets Content-Encoding String No
ContentLanguage Language type. Sets Content-Language String No
ContentLength Sets transmission length String No
ContentMD5 Sets MD5 of the uploaded file for verification String No
Metadata User-defined file meta information. It must start with x-cos-meta. Otherwise, it will be ignored. Dict No

Returned result

Attributes of the uploaded file. Type is dict:

{
    'ETag': 'string',
    'x-cos-expiration': 'string'
}
Parameter Name Description Type
ETag MD5 of the uploaded file String
x-cos-expiration After the lifecycle is set, the file expiration rule is returned String

Download files

Feature description

This API is used to download the files of the specified Bucket locally.

Method prototype

 get_object(Bucket, Key, **kwargs)

Request example

response = client.get_object(
    Bucket='test01-123456789',
    Key='test.txt',
    Range='string',
    IfMatch='string',
    IfModifiedSince='string',
    IfNoneMatch='string',
    IfUnmodifiedSince='string',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires='string',
    VersionId='string'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
Range Sets the range of the downloaded file, in the format of bytes=first-last. String No
IfMatch The file is returned if ETag is identical to the specified value String No
IfModifiedSince The file is returned after it has been modified since the specified time String No
IfNoneMatch The file is returned if ETag is different from the specified value String No
IfUnmodifiedSince The file is returned if it has been modified at or before the specified time String No
ResponseCacheControl Sets response header Cache-Control String No
ResponseContentDisposition Sets Content-Disposition in the response header String No
ResponseContentEncoding Sets Content-Encoding in the response header String No
ResponseContentLanguage Sets Content-Language in the response header String No
ResponseContentType Sets Content-Type in the response header String No
ResponseExpires Sets Content-Expires in the response header String No
VersionId Specifies the version of the downloaded file String No

Returned result

Body and meta information of the download file. Type is dict:

{
    'Body': StreamBody(),
    'Accept-Ranges': 'bytes',
    'Content-Type': 'application/octet-stream',
    'Content-Length': '16807',
    'Content-Disposition': 'attachment; filename="filename.jpg"',
    'Content-Range': 'bytes 0-16086/16087',
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
Parameter Name Description Type
Body The content of the downloaded file. You can get a file stream by means of get_raw_stream, and download the file content to the specified local file using get_stream_to_file. StreamBody
File meta information Meta information of the downloaded file, including Etag and x-cos-request-id. The meta information of the configured file is also returned. String

Get pre-signed download URL

Feature description

This API is used to get a pre-signed download URL to directly download a file.

Method prototype

get_presigned_download_url(Bucket, Key, Expired=300)

Request example

response = client.get_presigned_download_url(
    Bucket='test01-123456789',
    Key='test.txt'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
Expired Signature expiration time (in seconds) Int No

Returned result

The returned value for this method is pre-signed URL.

Delete a file

Feature description

This API is used to delete a file in the specified Bucket.

Method prototype

delete_object(Bucket, Key, **kwargs)

Request example

response = client.delete_object(
    Bucket='test01-123456789',
    Key='test.txt'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes

Returned result

The returned value for this method is None.

Batch deletion of files

Feature description

This API is used to delete the files in the specified Bucket in batches.

Method prototype

delete_objects(Bucket, Delete={}, **kwargs)

Request example

response = client.delete_objects(
    Bucket='test01-123456789',
    Delete={
        'Object': [
            {
                'Key': 'string',
            },
        ],
        'Quiet': 'true'|'false'
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Delete Indicates the method by which the result is returned for the deletion and the target Object Dict Yes
Object Provides the information of each target Object to be deleted List Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String No
Quiet Indicates the method by which the result is returned for the deletion. Available values: 'true' and 'false'. Default is 'false'. If it is set to 'true', only error message for failed deletion is returned. If it is set to 'false', messages indicating successful and failed deletion are returned. String No

Returned result

Result of batch deletion of files. Type is dict:

{
    'Deleted': [
        {
            'Key': 'string',
        },
    ],
    'Error': [
        {
            'Key': 'string',
            'Code': 'string',
            'Message': 'string'
        },
    ]
}
Parameter Name Description Type
Deleted The information of the Object that has been deleted List
Key The path of the Object that has been deleted String
Error The information of the Object that failed to be deleted List
Key The path of the Object that failed to be deleted String
Code The error code for the Object that failed to be deleted String
Message The error message for the Object that failed to be deleted String

Obtain file attributes

Feature description

This API is used to obtain the meta information of the specified file.

Method prototype

head_object(Bucket, Key, **kwargs)

Request example

response = client.head_object(
    Bucket='test01-123456789',
    Key='test.txt',
    IfModifiedSince='string'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
IfModifiedSince The file is returned after it has been modified since the specified time String No

Returned result

The meta information of the file obtained. Type is dict:

{
    'Content-Type': 'application/octet-stream',
    'Content-Length': '16807',
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
Parameter Name Description Type
File meta information Meta information of the file obtained, including ETag and x-cos-request-id. The meta information of the configured file is also included. String

Create multipart upload

Feature description

This API is used to create a new multipart upload task. UploadId is returned.

Method prototype

create_multipart_upload(Bucket, Key, **kwargs):

Request example

response = client.create_multipart_upload(
    Bucket='test01-123456789',
    Key='multipart.txt',
    StorageClass='STANDARD'|'STANDARD_IA',
    Expires='string'
    CacheControl='string',
    ContentType='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    Metadata={
        'x-cos-meta-key1': 'value1',
        'x-cos-meta-key2': 'value2'
    },
    ACL='private'|'public-read'|'public-read-write',
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string'
)
# Obtain UploadId for use by subsequent APIs
uploadid = response['UploadId']

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
StorageClass Sets file storage type: STANDARD and STANDARD_IA. Default: STANDARD String No
Expires Sets Content-Expires String No
CacheControl Cache policy. Sets Cache-Control String No
ContentType Content type. Sets Content-Type String No
ContentDisposition File name. Sets Content-Disposition String No
ContentEncoding Encoding format. Sets Content-Encoding String No
ContentLanguage Language type. Sets Content-Language String No
Metadata User-defined file meta information Dict No
ACL Sets file ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No

Returned result

The initialization information of the multipart upload task obtained. Type is dict:

{
    'UploadId': '150219101333cecfd6718d0caea1e2738401f93aa531a4be7a2afee0f8828416f3278e5570',
    'Bucket': 'test01-123456789', 
    'Key': 'multipartfile.txt' 
}
Parameter Name Description Type
UploadId Indicates the ID of multipart upload String
Bucket Bucket name, in the format of bucket-appid String
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String

Abort multipart upload

Feature description

This API is used to abort a multipart upload task, and all uploaded parts are deleted.

Method prototype

abort_multipart_upload(Bucket, Key, UploadId, **kwargs)

Request example

response = client.abort_multipart_upload(
    Bucket='test01-123456789',
    Key='multipart.txt',
    UploadId=uploadid
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
UploadId Indicates the ID of multipart upload String Yes

Returned result

The returned value for this method is None.

Upload a part

Feature description

This API is used to upload a part to the specified UploadId. The size of a part is limited to 5 GB.

Method prototype

upload_part(Bucket, Key, Body, PartNumber, UploadId, **kwargs)

Request example

# Note: The maximum number of parts to be uploaded is 10,000.
response = client.upload_part(
    Bucket='test01-123456789',
    Key='multipart.txt',
    Body=b'abc'|file,
    PartNumber=1,
    UploadId='string',
    ContentLength=123,
    ContentMD5='string'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
Body The content of the uploaded part, which can be a local file stream or an input stream file/bytes Yes
PartNumber Indicates the number of the uploaded part Int Yes
UploadId Indicates the ID of multipart upload String Yes
ContentLength Sets transmission length Int No
ContentMD5 Sets MD5 of the uploaded file for verification String No

Returned result

Attributes of the uploaded part. Type is dict:

{
    'ETag': 'string'
}
Parameter Name Description Type
ETag MD5 of the uploaded part. String

List uploaded parts

Feature description

This API is used to list the information of the uploaded parts in the specified UploadId.

Method prototype

list_parts(Bucket, Key, UploadId, MaxParts=1000, PartNumberMarker=0, EncodingType='', **kwargs)

Request example

response = client.list_parts(
    Bucket='test01-123456789',
    Key='multipart.txt',
    UploadId=uploadid,
    MaxParts=1000,
    PartNumberMarker=100,
    EncodingType='url'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
UploadId Indicates the ID of multipart upload String Yes
MaxParts The maximum number of returned parts. Default is 1,000. Int No
PartNumberMarker Indicates that the parts are listed from the one following PartNumberMarker. Default is 0, which means the parts are listed from the first one. Int No
EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url String No

Returned result

Information of all uploaded parts. Type is dict:

{
    'Bucket': 'test01-123456789', 
    'Key': 'multipartfile.txt', 
    'UploadId': '1502192444bdb382add546a35b2eeab81e06ed84086ca0bb75ea45ca7fa073fa9cf74ec4f2', 
    'EncodingType': None, 
    'MaxParts': '1000',
    'IsTruncated': 'true',
    'PartNumberMarker': '0', 
    'NextPartNumberMarker': '1000', 
    'StorageClass': 'Standard',
    'Part': [
        {
            'LastModified': '2017-08-08T11:40:48.000Z',
            'PartNumber': '1',
            'ETag': '"8b8378787c0925f42ccb829f6cc2fb97"',
            'Size': '10485760'
        },
    ], 
    'Initiator': {
        'DisplayName': '3333333333', 
        'ID': 'qcs::cam::uin/3333333333:uin/3333333333'
    }, 
    'Owner': {
        'DisplayName': '124564654654',
        'ID': '124564654654'
    }
}
Parameter Name Description Type
Bucket Bucket name, in the format of bucketname-appid String
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String
UploadId Indicates the ID of multipart upload String
EncodingType Indicates the encoding method of the returned value. The value is not encoded by default. Available value: url String
MaxParts The maximum number of returned parts. Default is 1,000. String
IsTruncated Indicates whether the returned parts are truncated String
PartNumberMarker Indicates that the parts are listed from the one following PartNumberMarker. Default is 0, which means the parts are listed from the first one. String
NextPartNumberMarker Marks the starting point of the next list of parts String
StorageClass File storage type: STANDARD and STANDARD_IA. Default: STANDARD String
Part Information of the uploaded part, including ETag, PartNumber, Size, and LastModified String
Initiator Creator of the multipart upload, including DisplayName and ID Dict
Owner Information of the file owner, including DisplayName and ID Dict

Complete multipart upload

Feature description

This API is used to construct all parts in the specified UploadId into a complete file. The size of the resulting file must be larger than 1 MB, otherwise an error is returned.

Method prototype

complete_multipart_upload(Bucket, Key, UploadId, MultipartUpload={}, **kwargs)

Request example

response = client.complete_multipart_upload(
    Bucket='test01-123456789',
    Key='multipart.txt',
    UploadId=uploadid,
    MultipartUpload={
        'Part': [
            {
                'ETag': 'string',
                'PartNumber': 1
            },
            {
                'ETag': 'string',
                'PartNumber': 2
            },
        ]
    },
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
UploadId Indicates the ID of multipart upload String Yes
MultipartUpload ETag and PartNumber information for all parts. Dict Yes

Returned result

Information about the constructed file. Type is dict:

{
    'ETag': '"3f866d0050f044750423e0a4104fa8cf-2"', 
    'Bucket': 'test01-123456789', 
    'Location': 'test01-123456789.cn-north.myqcloud.com/multipartfile.txt', 
    'Key': 'multipartfile.txt'
}
Parameter Name Description Type
ETag The unique tag of the resulting object. It is not the MD5 check value for the object content, but is only used to check the uniqueness of the object. To verify the file content, you can check the ETag of each part during the process of upload. String
Bucket Bucket name, in the format of bucketname-appid String
Location URL String
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String

Set Object ACL information

Feature description

This API is used to set the file ACL information by passing header through ACL, GrantFullControl, GrantRead, and GrantWrite or by passing body through AccessControlPolicy. You can only choose one method, otherwise a conflict error is returned.

Method prototype

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

Request example

response = client.put_object_acl(
    Bucket='test01-123456789',
    Key='test.txt',
    ACL='private'|'public-read'|'public-read-write',
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string',
    AccessControlPolicy={
        'Grant': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'Type': 'CanonicalUser'|'Group',
                    'ID': 'string',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
            },
        ],
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
ACL Sets file ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
AccessControlPolicy Grants the specified account the access to files. For more information on the format, please see the response for "get object acl". Dict No

Returned result

The returned value for this method is None.

Get Object ACL information

Feature description

This API is used to get the ACL information of the specified file.

Method prototype

get_object_acl(Bucket, Key, **kwargs)

Request example

response = client.get_object_acl(
    Bucket='test01-123456789',
    Key='test.txt'
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes

Returned result

Bucket ACL information. Type is Dict.

{
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'Grant': [
        {
            'Grantee': {
                'DisplayName': 'string',
                'Type': 'CanonicalUser'|'Group',
                'ID': 'string',
                'URI': 'string'
            },
            'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
        },
    ]
}
Parameter Name Description Type
Owner Information of the file owner, including DisplayName and ID Dict
Grant Information of a user granted the file permissions, including Grantee and Permission List
Grantee Information of grantee, including DisplayName, Type, ID and URI Dict
DisplayName Name of grantee String
Type Type of grantee: CanonicalUser and Group String
ID ID of grantee when Type is CanonicalUser String
URI URI of grantee when Type is Group String
Permission File permissions of grantee. Available values: FULL_CONTROL (read and write permissions), WRITE (write permission), and READ (read permission) String

Copy a file

Feature description

This API is used to copy a file from the source path to the destination path, during which the file meta attributes and ACL can be modified. To copy an object, if it is larger than 5 GB and the source and destination objects are in different regions, you must use the API create_multipart_upload() to create a multipart upload, then use upload_part_copy() to copy parts, and use complete_multipart_upload() to complete the multipart upload. If the object to be copied is smaller than or equal to 5 GB, or the source and destination objects are in the same region, you can just call copy_object().

Method prototype

copy_object(Bucket, Key, CopySource, CopyStatus='Copy', **kwargs)

Request example

response = client.copy_object(
    Bucket='test01-123456789',
    Key='test.txt',
    CopySource={
        'Appid': '1252408340',
        'Bucket': 'test02', 
        'Key': 'test.txt', 
        'Region': 'ap-guangzhou'
    },
    CopyStatus='Copy'|'Replaced',
    ACL='private'|'public-read'|'public-read-write',
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string',
    StorageClass='STANDARD'|'STANDARD_IA',
    Expires='string'
    CacheControl='string',
    ContentType='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    Metadata={
        'x-cos-meta-key1': 'value1',
        'x-cos-meta-key2': 'value2'
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
CopySource Indicates the path of the copied source file, including Appid, Bucket, Key, and Region Dict Yes
CopyStatus Available values: 'Copy' and 'Replaced'. When it is set to 'Copy', ignore the configured user metadata information and copy the file directly. When it is set to 'Replaced', modify the metadata according to the configured meta information. If the destination path is identical to the source path, it must be set to 'Replaced'. String Yes
ACL Sets file ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write files in the format of id=" ",id=" ". <eci> For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
StorageClass Sets file storage type: STANDARD and STANDARD_IA. Default: STANDARD String No
Expires Sets Content-Expires String No
CacheControl Cache policy. Sets Cache-Control String No
ContentType Content type. Sets Content-Type String No
ContentDisposition File name. Sets Content-Disposition String No
ContentEncoding Encoding format. Sets Content-Encoding String No
ContentLanguage Language type. Sets Content-Language String No
Metadata User-defined file meta information Dict No
#### Returned result

Attributes of the uploaded file. Type is dict:

{
    'ETag': 'string',
    'LastModified': 'string',
}
Parameter Name Description Type
ETag MD5 of the copied file String
LastModified The time when the copied file was last modified String

Copy parts

Feature description

This API is used to copy the parts of a file from source path to the destination path.

Method prototype

upload_part_copy(Bucket, Key, PartNumber, UploadId, CopySource, CopySourceRange='', **kwargs)

Request example

response = client.upload_part_copy(
    Bucket='test01-123456789',
    Key='test.txt',
    PartNumber=100,
    UploadId='string',
    CopySource={
        'Appid': '1252408340',
        'Bucket': 'test02', 
        'Key': 'test.txt', 
        'Region': 'ap-guangzhou'
    },
    CopySourceRange='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince='string',
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince='string'

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
PartNumber Indicates the number of the uploaded part Int Yes
UploadId Indicates the ID of multipart upload String Yes
CopySource Indicates the path of the copied source file, including Appid, Bucket, Key, and Region Dict Yes
CopySourceRange Indicates the range of the copied file, in the format of bytes=first-last. If it is not specified, the entire source file is copied by default. String No
CopySourceIfMatch The file is copied when the ETag of the source file is identical to the specified value String No
CopySourceIfModifiedSince The source file is copied after it has been modified since the specified time String No
CopySourceIfNoneMatch The file is copied when the ETag of the source file is different from the specified value String No
CopySourceIfUnmodifiedSince The source file is copied after it is not modified since the specified time String No

Returned result

Attributes of the copied part. Type is dict:

{
    'ETag': 'string',
    'LastModified': 'string',
}
Parameter Name Description Type
ETag MD5 of the copied part String
LastModified The time when the copied part was last modified String

Restore an archive file

Feature description

This API is used to restore an object that has been archived as "archive" via COS.

Method prototype

restore_object(Bucket, Key, RestoreRequest={}, **kwargs)

Request example

response = client.restore_object(
    Bucket='test01-123456789',
    Key='test.txt',
    RestoreRequest={
        'Days': 100,
        'CASJobParameters': {
            'Tier': 'Expedited'|'Standard'|'Bulk'
        }

    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
RestoreRequest Describes the rule for restoring temporary files Dict Yes
Days Describes the validity period of a temporary file Int Yes
CASJobParameters Describes the configuration information of restore type Dict No
Tier Describes the mode of restoring temporary files. Available values: 'Expedited' (fast), 'Standard' (moderate), and 'Bulk' (slow). String No

Returned result

The returned value for this method is None.

High-level API

Upload files (resuming upload from breakpoint)

Feature description

This API for file upload selects easy upload or multipart upload according to the file length. Easy upload is used for files smaller than or equal to 20 MB. Multipart upload is used for files larger than 20 MB. If the upload of a part is not completed, you can resume the upload from the breakpoint.

Method prototype

upload_file(Bucket, Key, LocalFilePath, PartSize=1, MAXThread=5, **kwargs)

Request example

response = client.upload_file(
    Bucket='test01-123456789',
    Key='test.txt',
    LocalFilePath='local.txt'
)

Request example for all parameters

response = client.upload_file(
    Bucket='test01-123456789',
    Key='test.txt',
    LocalFilePath='local.txt',
    PartSize=1,
    MAXThread=5,
    ACL='private'|'public-read'|'public-read-write', # Please use this parameter with caution. Otherwise, a limit of 1,000 ACL rules may be reached.
    GrantFullControl='string',
    GrantRead='string',
    GrantWrite='string',
    StorageClass='STANDARD'|'STANDARD_IA',
    Expires='string',
    CacheControl='string',
    ContentType='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength='123',
    ContentMD5='string',
    Metadata={
        'x-cos-meta-key1': 'value1',
        'x-cos-meta-key2': 'value2'
    }
)

Parameters

Parameter Name Description Type Required
Bucket Bucket name, in the format of bucketname-appid String Yes
Key Object key is the unique identifier of the object in the bucket. For example, in the object's access domain name bucket1-1250000000.cos.ap-guangzhou.myqcloud.com/doc1/pic1.jpg, the object key is doc1/pic1.jpg. String Yes
LocalFilePath Name of the path to the local file String Yes
PartSize Part size in multipart upload. Default is 1 MB. Int No
MAXThread The maximum number of parts to be uploaded at a time. Default is 5. Parts are uploaded through threads Int No
ACL Sets file ACL, such as 'private', 'public-read', and 'public-read-write' String No
GrantFullControl Grants the specified account the permission to read and write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantRead Grants the specified account the permission to read files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
GrantWrite Grants the specified account the permission to write files in the format of id=" ",id=" ". For authorization to a sub-account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{SubUin}". For authorization to a root account, the format is id="qcs::cam::uin/{OwnerUin}:uin/{OwnerUin}". For example, 'id="qcs::cam::uin/123:uin/456",id="qcs::cam::uin/123:uin/123"' String No
StorageClass Sets file storage type: STANDARD and STANDARD_IA. Default: STANDARD String No
Expires Sets Content-Expires String No
CacheControl Cache policy. Sets Cache-Control String No
ContentType Content type. Sets Content-Type String No
ContentDisposition File name. Sets Content-Disposition String No
ContentEncoding Encoding format. Sets Content-Encoding String No
ContentLanguage Language type. Sets Content-Language String No
ContentLength Sets transmission length String No
ContentMD5 Sets MD5 of the uploaded file for verification String No
Metadata User-defined file meta information Dict No

Returned result

Attributes of the uploaded file. Type is dict:

{
    'ETag': 'string',
    'x-cos-expiration': 'string'
}
Parameter Name Description Type
ETag MD5 of the uploaded file String
x-cos-expiration After the lifecycle is set, the file expiration rule is returned String

API for Obtaining Signature

Obtain a signature

Feature description

This API is used to obtain the signature of the specified operation, which is commonly used for signature distribution.

Method prototype

get_auth(Method, Bucket, Key, Expired=300, Headers={}, Params={})

Request example

response = client.get_auth(
    Method='PUT'|'POST'|'GET'|'DELETE'|'HEAD',
    Bucket='test01-123456789',
    Key='test.txt',
    Expired=300,
    Headers={
        'Content-Length': 'string',
        'Content-MD5': 'string'
    },
    Params={
        'param1': 'string',
        'param2': 'string'
    }
)

Parameters

Parameter Name Description Type Required
Method Indicates the method of the operation. Available values: 'PUT', 'POST', 'GET', 'DELETE', and 'HEAD'. String Yes
Bucket Bucket name, in the format of bucketname-appid String Yes
Key For bucket operations, enter a root path "/". For object operations, enter a file path. String Yes
Expired Signature expiration time (in seconds) Int No
Headers Indicates the request header required in the signature Dict No
Params Indicates the request parameters required in the signature Dict No

Returned result

The returned value for this method is the signature value of the corresponding operation.

Exception Types

Exceptions include CosClientError (SDK client error) and CosServiceError (COS server error).

CosClientError

CosClientError generally refers to a client error caused by the reasons such as timeout. When capturing such an error, you can choose to retry or perform other operations.

CosServiceError

CosServiceError provides the message returned by the server. For more information on error codes, please see COS Error Codes.

#except CosServiceError as e
e.get_origin_msg()  # Get original error message in XML format
e.get_digest_msg()  # Get the processed error message in dict format
e.get_status_code()# Get http error code (e.g. 4XX, 5XX)
e.get_error_code()  # Get COS-defined error code
e.get_error_msg()   # Get a detailed description of the COS error code
e.get_trace_id()   # Get the trace_id of the request
e.get_request_id() # Get the request_id of the request
e.get_resource_location()# Get the URL