存储桶操作

简介

本文档提供关于存储桶的基本操作和访问控制列表（ACL）的相关 API 概览以及 SDK 示例代码。

基本操作

访问控制列表

基本操作

创建存储桶

功能说明

在指定账号下创建一个存储桶（PUT Bucket）。

方法原型

create_bucket(Bucket, **kwargs)

请求示例

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

参数说明

返回结果说明

该方法返回值为 None。

检索存储桶及其权限

功能说明

检索存储桶是否存在且是否有权限访问（HEAD Bucket）。

方法原型

head_bucket(Bucket)

请求示例

response = client.head_bucket(
    Bucket='examplebucket-1250000000'
)

参数说明

返回结果说明

该方法返回值为 None。

删除存储桶

功能说明

删除指定账号下的空存储桶（DELETE Bucket）。

方法原型

delete_bucket(Bucket)

请求示例

response = client.delete_bucket(
    Bucket='examplebucket-1250000000'
)

参数说明

返回结果说明

该方法返回值为 None。

访问控制列表

设置存储桶 ACL

功能说明

设置指定存储桶的访问权限控制列表（PUT Bucket acl）。AccessControlPolicy 参数与其它权限参数是互斥的，无法同时指定。

方法原型

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

请求示例

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

参数说明

返回结果说明

该方法返回值为 None。

查询存储桶 ACL

功能说明

查询指定存储桶的访问权限控制列表（GET Bucket acl）。

方法原型

get_bucket_acl(Bucket, **kwargs)

请求示例

response = client.get_bucket_acl(
    Bucket='examplebucket-1250000000',
)

参数说明

返回结果说明

Bucket ACL 信息，类型为 dict。

{
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'Grant': [
        {
            'Grantee': {
                'DisplayName': 'string',
                'Type': 'CanonicalUser'|'Group',
                'ID': 'string',
                'URI': 'string'
            },
            'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
        },
    ]
}

对象操作

简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。

简单操作

分块操作

其他操作

简单操作

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。

方法原型

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

请求示例

response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='string'
)

全部参数请求示例

response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='string',
    Delimiter='/',
    Marker='string',
    MaxKeys=100,
    EncodingType='url'
)

参数说明

返回结果说明

获取对象的元信息，类型为 dict：

{
    'MaxKeys': '1000', 
    'Prefix': 'string',
    'Delimiter': 'string',
    'Marker': 'string',
    'NextMarker': 'string',
    'Name': 'examplebucket-1250000000',  
    'IsTruncated': 'false'|'true',
    'EncodingType': 'url',
    'Contents':[
        {
            'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
            'StorageClass': 'STANDARD', 
            'Key': 'exampleobject',
            'Owner': {
                'DisplayName': '1250000000',
                'ID': '1250000000'
            }, 
            'LastModified': '2017-08-08T09:43:35.000Z', 
            'Size': '23'
        },
    ],
    'CommonPrefixes':[
        {
            'Prefix': 'string'
        },
    ],
}

查询对象及其历史版本列表

功能说明

查询存储桶下的部分或者全部对象及其历史版本信息。

方法原型

list_objects_versions(Bucket, Prefix="", Delimiter="", KeyMarker="", VersionIdMarker="", MaxKeys=1000, EncodingType="", **kwargs)

请求示例

response = client.list_objects_versions(
    Bucket='examplebucket-1250000000',
    Prefix='string'
)

全部参数请求示例

response = client.list_objects_versions(
    Bucket='examplebucket-1250000000',
    Prefix='string',
    Delimiter='/',
    KeyMarker='string',
    VersionIdMarker='string',
    MaxKeys=100,
    EncodingType='url'
)

参数说明

返回结果说明

获取对象的元信息，类型为 dict：

{
    'MaxKeys': '1000', 
    'Prefix': 'string',
    'Delimiter': 'string',
    'KeyMarker': 'string',
    'VersionIdMarker': 'string',
    'NextMarker': 'string',
    'NextVersionIdMarker': 'string',
    'Name': 'examplebucket-1250000000',  
    'IsTruncated': 'false'|'true',
    'EncodingType': 'url',
    'Version':[
        {
            'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
            'StorageClass': 'STANDARD', 
            'Key': 'exampleobject',
            'VersionId': 'string',
            'IsLatest': 'true'|'false',
            'Owner': {
                'DisplayName': '1250000000',
                'ID': '1250000000'
            }, 
            'LastModified': '2017-08-08T09:43:35.000Z', 
            'Size': '23'
        },
    ],
    'DeleteMarker': [
        {
            'Key': 'exampleobject',
            'VersionId': 'string',
            'IsLatest': 'true'|'false',
            'Owner': {
                'DisplayName': '1250000000',
                'ID': '1250000000'
            },
            'LastModified': '2017-08-08T09:43:35.000Z'
        },
    ],
    'CommonPrefixes':[
        {
            'Prefix': 'string'
        },
    ],
}

简单上传对象

功能说明

上传一个对象至存储桶（PUT Object）。

方法原型

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

请求示例

response = client.put_object(
    Bucket='examplebucket-1250000000',
    Body=b'bytes'|file,
    Key='exampleobject',
    EnableMD5=False
)

全部参数请求示例

response = client.put_object(
    Bucket='examplebucket-1250000000',
    Body=b'bytes'|file,
    Key='exampleobject',
    EnableMD5=False|True,
    ACL='private'|'public-read',  # 请慎用此参数,否则会达到1000条 ACL 上限
    GrantFullControl='string',
    GrantRead='string',
    StorageClass='STANDARD',
    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'
    }
)

参数说明

返回结果说明

上传对象的属性，类型为 dict：

{
    'ETag': 'string',
    'x-cos-version-id': 'string'
}

查询对象元数据

功能说明

查询对象的元数据信息（HEAD Object）。

方法原型

head_object(Bucket, Key, **kwargs)

请求示例

response = client.head_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    VersionId='string',
    IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
)

参数说明

返回结果说明

获取对象的元信息，类型为 dict：

{
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'Cache-Control': 'max-age=1000000',
    'Content-Type': 'application/octet-stream',
    'Content-Disposition': 'attachment; filename="filename.jpg"',
    'Content-Encoding': 'gzip',
    'Content-Language': 'zh-cn',
    'Content-Length': '16807',
    'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
    'x-cos-meta-test': 'test',
    'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
    'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}

下载对象

功能说明

下载一个对象到本地（GET Object）。

方法原型

 get_object(Bucket, Key, **kwargs)

请求示例

response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    Range='string',
    IfMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
    IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    IfNoneMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
    IfUnmodifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires='string',
    VersionId='string'
)

参数说明

返回结果说明

下载对象的 Body 和元信息，类型为 dict：

{
    'Body': StreamBody(),
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'Accept-Ranges': 'bytes',
    'Content-Range': 'bytes 0-16086/16087',
    'Cache-Control': 'max-age=1000000',
    'Content-Type': 'application/octet-stream',
    'Content-Disposition': 'attachment; filename="filename.jpg"',
    'Content-Encoding': 'gzip',
    'Content-Language': 'zh-cn',
    'Content-Length': '16807',
    'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
    'x-cos-meta-test': 'test',
    'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
    'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}

设置对象复制

功能说明

复制文件到目标路径（PUT Object - Copy）。

方法原型

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

请求示例

response = client.copy_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    CopySource={
        'Bucket': 'examplebucket-1250000000', 
        'Key': 'exampleobject', 
        'Endpoint': 'example.endpoint',
        'VesionId': 'string'
    },
    CopyStatus='Copy'|'Replaced',
    ACL='private'|'public-read',
    GrantFullControl='string',
    GrantRead='string',
    StorageClass='STANDARD',
    Expires='string',
    CacheControl='string',
    ContentType='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    Metadata={
        'x-cos-meta-key1': 'value1',
        'x-cos-meta-key2': 'value2'
    }
)

参数说明

返回结果说明

上传对象的属性，类型为 dict：

{
    'ETag': 'string',
    'LastModified': 'string',
    'VersionId': 'string',
    'x-cos-copy-source-version-id': 'string'
}

删除单个对象

功能说明

删除指定的对象（DELETE Object）。

方法原型

delete_object(Bucket, Key, **kwargs)

请求示例

response = client.delete_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    VersionId='string',
)

参数说明

返回结果说明

删除对象的信息，类型为dict

{
    'x-cos-version-id': 'string',
    'x-cos-delete-marker': 'true'|'false',
}

删除多个对象

功能说明

删除多个指定的对象（DELETE Multiple Objects）。

方法原型

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

请求示例

response = client.delete_objects(
    Bucket='examplebucket-1250000000',
    Delete={
        'Object': [
            {
                'Key': 'exampleobject1',
                'VersionId': 'string'
            },
            {
                'Key': 'exampleobject2',
                'VersionId': 'string'
            },
        ],
        'Quiet': 'true'|'false'
    }
)

参数说明

返回结果说明

批量删除对象的结果，类型为 dict：

{
    'Deleted': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'DeleteMarker': 'true'|'false',
            'DeleteMarkerVersionId': 'string'
        },
        {
            'Key': 'string',
        },
    ],
    'Error': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

分块操作

分块上传对象可包括的操作：

• 分块上传对象：初始化分块上传，上传分块，完成所有分块上传。

• 分块续传：查询已上传的分块，上传分块，完成所有分块上传。

• 删除已上传分块。

查询分块上传

功能说明

查询指定存储桶正在进行中的分块上传信息（List Multipart Uploads）。

方法原型

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

请求示例

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

参数说明

返回结果说明

获取分块上传的信息，类型为 dict：

{
    'Bucket': 'examplebucket-1250000000',
    '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'
        },
    ],
}

初始化分块上传

功能说明

初始化分块上传，获取对应的 uploadId（Initiate Multipart Upload）。

方法原型

create_multipart_upload(Bucket, Key, **kwargs):

请求示例

response = client.create_multipart_upload(
    Bucket='examplebucket-1250000000',
    Key='multipart.txt',
    StorageClass='STANDARD',
    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',
    GrantFullControl='string',
    GrantRead='string'
)
# 获取UploadId供后续接口使用
uploadid = response['UploadId']

参数说明

返回结果说明

获取分块上传的初始化信息，类型为 dict：

{
    'UploadId': '150219101333cecfd6718d0caea1e2738401f93aa531a4be7a2afee0f8828416f3278e5570',
    'Bucket': 'examplebucket-1250000000', 
    'Key': 'exampleobject' 
}

上传分块

分块上传对象（Upload Part）。

方法原型

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

请求示例

# 注意，上传分块的块数最多10000块
response = client.upload_part(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    Body=b'bytes'|file,
    PartNumber=1,
    UploadId='string',
    EnableMD5=False|True,
    ContentLength='123',
    ContentMD5='string'
)

参数说明

返回结果说明

上传分块的属性，类型为 dict：

{
    'ETag': 'string'
}

复制分块

将其他对象复制为一个分块（Upload Part - Copy）。

方法原型

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

请求示例

response = client.upload_part_copy(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    PartNumber=100,
    UploadId='string',
    CopySource={
        'Bucket': 'examplebucket-1250000000', 
        'Key': 'exampleobject', 
        'Endpoint': 'example.endpoint',
        'VersionId': 'string'
    },
    CopySourceRange='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince='string',
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince='string'
)

参数说明

返回结果说明

复制分块的属性，类型为 dict：

{
    'ETag': 'string',
    'LastModified': 'string',
    'x-cos-copy-source-version-id': 'string',
}

查询已上传块

功能说明

查询特定分块上传操作中的已上传的块（List Parts）。

方法原型

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

请求示例

response = client.list_parts(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    UploadId=uploadid,
    MaxParts=1000,
    PartNumberMarker=100,
    EncodingType='url'
)

参数说明

返回结果说明

所有上传分块的信息，类型为 dict：

{
    'Bucket': 'examplebucket-1250000000', 
    'Key': 'exampleobject', 
    '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'
    }
}

完成分块上传

功能说明

完成整个对象的分块上传（Complete Multipart Upload）。

方法原型

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

请求示例

response = client.complete_multipart_upload(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    UploadId=uploadid,
    MultipartUpload={
        'Part': [
            {
                'ETag': 'string',
                'PartNumber': 1
            },
            {
                'ETag': 'string',
                'PartNumber': 2
            },
        ]
    },
)

参数说明

返回结果说明

组装后的对象的相关信息，类型为 dict：

{
    'ETag': '"3f866d0050f044750423e0a4104fa8cf-2"', 
    'Bucket': 'examplebucket-1250000000', 
    'Location': 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject', 
    'Key': 'exampleobject'
}

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块（Abort Multipart Upload）。

方法原型

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

请求示例

response = client.abort_multipart_upload(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    UploadId=uploadid
)

参数说明

返回结果说明

该方法返回值为 None。

其他操作

设置对象 ACL

功能说明

设置存储桶中某个对象的访问控制列表（PUT Object acl）。AccessControlPolicy 参数与其它权限参数是互斥的，无法同时指定。

方法原型

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

请求示例

response = client.put_object_acl(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    ACL='private'|'public-read',
    GrantFullControl='string',
    GrantRead='string',
    AccessControlPolicy={
        'AccessControlList': {
            'Grant': [
                {
                    'Grantee': {
                        'DisplayName': 'string',
                        'Type': 'CanonicalUser'|'Group',
                        'ID': 'string',
                        'URI': 'string'
                    },
                    'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
                },
            ]
        },
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    }
)

参数说明

返回结果说明

该方法返回值为 None。

查询对象 ACL

功能说明

查询对象的访问控制列表（GET Object acl）。

方法原型

get_object_acl(Bucket, Key, **kwargs)

请求示例

response = client.get_object_acl(
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

参数说明

返回结果说明

Bucket ACL 信息，类型为 Dict：

{
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'Grant': [
        {
            'Grantee': {
                'DisplayName': 'string',
                'Type': 'CanonicalUser'|'Group',
                'ID': 'string',
                'URI': 'string'
            },
            'Permission': 'FULL_CONTROL'|'WRITE'|'READ'
        },
    ]
}

高级接口（推荐）

上传对象（断点续传）

功能说明

该高级接口根据用户文件的长度自动选择简单上传以及分块上传，对于小于等于20M的文件调用简单上传，对于大于20MB的文件调用分块上传，对于分块上传未完成的文件会自动进行断点续传。

方法原型

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

请求示例

response = client.upload_file(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    LocalFilePath='local.txt',
    EnableMD5=False
)

全部参数请求示例

response = client.upload_file(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    LocalFilePath='local.txt',
    PartSize=1,
    MAXThread=5,
    EnableMD5=False|True,
    ACL='private'|'public-read', # 请慎用此参数,否则会达到1000条ACL上限
    GrantFullControl='string',
    GrantRead='string',
    StorageClass='STANDARD',
    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'
    }
)

参数说明

返回结果说明

上传对象的属性，类型为 dict：

{
    'ETag': 'string'
}

存储桶管理

简介

本文档提供关于跨域访问、生命周期、版本控制和跨地域复制相关的 API 概览以及 SDK 示例代码。

跨域访问

版本控制

跨地域复制

跨域访问

设置跨域配置

功能说明

设置指定存储桶的跨域访问配置信息（PUT Bucket cors）。

方法原型

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

请求示例

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

参数说明

返回结果说明

该方法返回值为 None。

查询跨域配置

功能说明

查询指定存储桶的跨域访问配置信息（GET Bucket cors）。

方法原型

get_bucket_cors(Bucket, **kwargs)

请求示例

response = client.get_bucket_cors(
    Bucket='examplebucket-1250000000',
)

参数说明

返回结果说明

存储桶跨域配置，类型为 dict。

{
    'CORSRule': [
        {
            'ID': 'string',
            'MaxAgeSeconds': 100,
            'AllowedOrigin': [
                'string',
            ],
            'AllowedMethod': [
                'string',
            ],
            'AllowedHeader': [
                'string',
            ],
            'ExposeHeader': [
                'string',
            ],
        }
    ]
}

删除跨域配置

功能说明

删除指定存储桶的跨域访问配置（DELETE Bucket cors）。

方法原型

delete_bucket_cors(Bucket, **kwargs)

请求示例

response = client.delete_bucket_cors(
    Bucket='examplebucket-1250000000',
)

参数说明

返回结果说明

该方法返回值为 None。

版本控制

设置版本控制

功能说明

设置指定存储桶的版本控制功能（PUT Bucket versioning）。

方法原型

put_bucket_versioning(Bucket, Status, **kwargs)

请求示例

开启版本控制

response = client.put_bucket_versioning(
    Bucket='examplebucket-1250000000',
    Status='Enabled'
)

暂停版本控制

response = client.put_bucket_versioning(
    Bucket='examplebucket-1250000000',
    Status='Suspended'
)

参数说明

返回结果说明

该方法返回值为 None。

查询版本控制

功能说明

查询指定存储桶的版本控制信息（GET Bucket versioning）。

方法原型

get_bucket_versioning(Bucket, **kwargs)

请求示例

response = client.get_bucket_versioning(
    Bucket='examplebucket-1250000000',
)

参数说明

返回结果说明

Bucket 版本控制配置，类型为 dict。

{
    'Status': 'Enabled'|'Suspended'
}

跨地域复制

设置跨地域复制

功能说明

设置指定存储桶的跨地域复制规则（PUT Bucket replication）。

方法原型

put_bucket_replication(Bucket, ReplicationConfiguration={}, **kwargs)

请求示例

response = client.put_bucket_replication(
    Bucket='examplebucket-1250000000',
    ReplicationConfiguration={
        'Role': 'qcs::cam::uin/100000000001:uin/100000000001',
        'Rule': [
            {
                'ID': 'string',
                'Status': 'Enabled'|'Disabled',
                'Prefix': 'string',
                'Destination': {
                    'Bucket': 'qcs::cos:ap-shanghai::examplebucket1-1250000000',
                    'StorageClass': 'STANDARD'
                }
            },
            {
                'ID': 'string',
                'Status': 'Enabled'|'Disabled',
                'Prefix': 'string',
                'Destination': {
                    'Bucket': 'qcs::cos:ap-guangzhou::examplebucket2-1250000000',
                    'StorageClass': 'STANDARD'
                }
            },
        ]   
    }
)

参数说明

返回结果说明

该方法返回值为 None。

查询跨地域复制

功能说明

查询指定存储桶的跨地域复制规则（GET Bucket replication）。

方法原型

get_bucket_replication(Bucket, **kwargs)

请求示例

response = client.get_bucket_replication(
    Bucket='examplebucket-1250000000'
)

参数说明

返回结果说明

Bucket 跨地域复制配置，类型为 dict。

{
    'Role': 'qcs::cam::uin/100000000001:uin/100000000001',
    'Rule': [
        {
            'ID': 'string',
            'Status': 'Enabled'|'Disabled',
            'Prefix': 'string',
            'Destination': {
                'Bucket': 'qcs::cos:ap-shanghai::examplebucket1-1250000000',
                'StorageClass': 'STANDARD'
            }
        },
        {
            'ID': 'string',
            'Status': 'Enabled'|'Disabled',
            'Prefix': 'string',
            'Destination': {
                'Bucket': 'qcs::cos:ap-guangzhou::examplebucket2-1250000000',
                'StorageClass': 'STANDARD'
            }
        },
    ]  
}

删除跨地域复制

功能说明

删除指定存储桶的跨地域复制规则（DELETE Bucket replication）。

方法原型

delete_bucket_replication(Bucket, **kwargs)

请求示例

response = client.delete_bucket_replication(
    Bucket='examplebucket-1250000000',
)

参数说明

返回结果说明

该方法返回值为 None。

预签名 URL

简介

Python SDK 提供获取签名，获取请求预签名 URL 接口以及获取对象下载预签名 URL 接口。使用永久密钥或临时密钥获取预签名 URL 的调用方法相同，使用临时密钥时需要在 header 或 query_string 中加上 x-cos-security-token。

获取签名

功能说明

获取指定操作的签名，常用于移动端的签名分发。

方法原型

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

上传请求示例

response = client.get_auth(
    Method='PUT',
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

下载请求示例

response = client.get_auth(
    Method='GET',
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

全部参数请求示例

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

参数说明

返回结果说明

该方法返回值为对应操作的签名值。

获取预签名 URL

功能说明

获取预签名链接用于分发。

上传请求示例

response = client.get_presigned_url(
    Method='PUT',
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

下载请求示例

response = client.get_presigned_url(
    Method='GET',
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

方法原型

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

请求示例

response = client.get_presigned_url(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    Method='PUT'|'POST'|'GET'|'DELETE'|'HEAD',
    Expired=300,
    Headers={
        'Content-Length': 'string',
        'Content-MD5': 'string'
    },
    Params={
        'param1': 'string',
        'param2': 'string'
    }
)

参数说明

返回结果说明

该方法返回值为预签名的 URL。

获取预签名下载 URL

功能说明

获取预签名下载链接用于直接下载。

方法原型

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

请求示例

response = client.get_presigned_download_url(
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

参数说明

返回结果说明

该方法返回值为预签名的下载 URL。

异常处理

简介

COS XML Python SDK 操作成功会返回一个 dict 或者 None。若调用 SDK 接口请求 COS 服务失败，系统将抛出 CosClientError（客户端异常）或者 CosServiceError （服务端异常）。

• CosClientError 是由于客户端无法和 COS 服务端正常进行交互所引起。如客户端无法连接到服务端，无法解析服务端返回的数据，读取本地文件发生 IO 异常等。

• CosServiceError 是客户端和 COS 服务端交互正常，但操作 COS 资源失败。如客户端访问一个不存在的存储桶，删除一个不存在的对象，没有权限进行某个操作等。

客户端异常

CosClientError 一般指如 timeout 引起的客户端错误，用户捕获后可以选择重试或其它操作。

服务端异常

CosServiceError 提供服务端返回的具体信息，包含了服务端返回的状态码、requestid 和出错明细等。捕获异常后，建议对整个异常进行打印，异常包含了必须的排查因素。以下是异常成员变量的描述以及异常捕获示例。

异常捕获示例

from qcloud_cos import CosServiceError

except CosServiceError as e:
    e.get_origin_msg()  # 获取原始错误信息，格式为XML
    e.get_digest_msg()  # 获取处理过的错误信息，格式为dict
    e.get_status_code() # 获取 http 错误码（如4XX，5XX)
    e.get_error_code()  # 获取 COS 定义的错误码
    e.get_error_msg()   # 获取 COS 错误码的具体描述
    e.get_trace_id()    # 获取请求的 trace_id
    e.get_request_id()  # 获取请求的 request_id
    e.get_resource_location() # 获取 URL 地址