上传对象

最近更新时间:2024-09-11 15:14:41

我的收藏

简介

本文介绍对象存储 COS 通过 Python SDK 实现上传对象功能的示例代码和描述。包括高级接口、简单接口、分块上传三个部分。

注意事项

若您使用简单上传,需要具有目标对象的写权限:在您进行 授权策略 时,action 需要设置为cos:PutObject ,更多授权请参见 支持CAM的业务接口
若您使用高级接口的自动分块上传或使用简单接口实现分块上传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传的权限:在您进行 授权策略 时,action 需要设置为 cos:InitiateMultipartUploadcos:UploadPartcos:CompleteMultipartUpload,更多授权请参见 支持CAM的业务接口
若您使用高级接口的断点续传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传、列举分块上传任务、列举已上传分块的权限:在您进行 授权策略 时,action 需要设置为 cos:InitiateMultipartUploadcos:UploadPartcos:CompleteMultipartUploadcos:ListMultipartUploadscos:ListParts更多授权请参见 支持CAM的业务接口

相关示例

功能名称
描述
示例代码
高级接口
高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持断点续传功能。
简单接口
PUT Object 接口可以上传一个对象至指定存储桶中,不支持自动分块上传和断点续传。最大支持上传不超过5GB的对象,5GB以上对象请使用 分块上传 或 高级接口 上传。
分块操作
分块上传可以实现将整个对象切分为多个分块,然后再将这些分块上传到对象存储(Cloud Object Storage,COS)。

高级接口(推荐)

上传对象(断点续传)

功能说明

该高级接口根据用户文件的长度和设置的分块大小PartSize(单位MB)自动选择简单上传以及分块上传,对于小于等于PartSize的文件调用简单上传,对于大于PartSize的文件调用分块上传,对于分块上传未完成的文件会自动进行断点续传。
对于分块上传的文件,可以通过 progress_callback 回调函数,获取上传进度。

方法原型

upload_file(Bucket, Key, LocalFilePath, PartSize=1, MAXThread=5, EnableMD5=False, progress_callback=None, **kwargs)

使用案例

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos.cos_exception import CosClientError, CosServiceError
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

# 使用高级接口上传一次,不重试,此时没有使用断点续传的功能
response = client.upload_file(
Bucket='examplebucket-1250000000',
Key='exampleobject',
LocalFilePath='local.txt',
EnableMD5=False,
progress_callback=None
)

# 使用高级接口断点续传,失败重试时不会上传已成功的分块(这里重试10次)
for i in range(0, 10):
try:
response = client.upload_file(
Bucket='examplebucket-1250000000',
Key='exampleobject',
LocalFilePath='local.txt')
break
except CosClientError or CosServiceError as e:
print(e)

全部参数请求示例

def upload_percentage(consumed_bytes, total_bytes):
"""进度条回调函数,计算当前上传的百分比

:param consumed_bytes: 已经上传的数据量
:param total_bytes: 总数据量
"""
if total_bytes:
rate = int(100 * (float(consumed_bytes) / float(total_bytes)))
print('\\r{0}% '.format(rate))
sys.stdout.flush()

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

参数说明

参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
LocalFilePath
本地文件的路径名
String
PartSize
分块上传的分块大小,默认为1MB
Int
MAXThread
分块上传的并发数量,默认为5个线程上传分块
Int
progress_callback
上传进度的回调函数,可以通过自定义此函数,来获取上传进度
Func
EnableMD5
是否需要 SDK 计算 Content-MD5,默认关闭,打开后会增加上传耗时
Bool
ACL
设置对象的 ACL,例如 private,public-read
String
GrantFullControl
赋予被授权者所有的权限,格式为 id="OwnerUin",例如 id="100000000001"
String
GrantRead
赋予被授权者读的权限,格式为 id="OwnerUin",例如 id="100000000001"
String
StorageClass
设置对象的存储类型,例如 STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD,更多存储类型,请参见 存储类型概述
String
Expires
设置 Expires
String
CacheControl
缓存策略,设置 Cache-Control
String
ContentType
内容类型,设置 Content-Type
String
ContentDisposition
文件名称,设置 Content-Disposition
String
ContentEncoding
编码格式,设置 Content-Encoding
String
ContentLanguage
语言类型,设置 Content-Language
String
ContentLength
设置传输长度
String
ContentMD5
设置上传对象的 MD5 值用于校验
String
Metadata
用户自定义的对象元数据
Dict
TrafficLimit
单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即800Kb/s - 800Mb/s,高级接口限制的是单线程的速度
String

返回结果说明

除 HTTP 公共响应头外,还包括上传对象的属性,类型为 dict:
{
'ETag': 'string'
'x-cos-hash-crc64ecma': 'string',
'x-cos-request-id': 'string',
'x-cos-storage-class': 'string',
'x-cos-version-id': 'string',
'Location': 'string', # 触发分块上传时返回此字段
'Bucket': 'string', # 触发分块上传时返回此字段
'Key': 'string' # 触发分块上传时返回此字段
}
参数名称
参数描述
类型
ETag
分块上传时,该值不是对象内容的 MD5 校验值,仅能用于检查对象唯一性
String
x-cos-hash-crc64ecma
文件的 CRC64 校验码
String
x-cos-request-id
请求 ID
String
x-cos-storage-class
对象存储类型
String
x-cos-version-id
开启版本控制后,对象的版本号
String
Location
对象的访问 URL (触发分块上传时返回此字段)
String
Bucket
存储桶名 (触发分块上传时返回此字段)
String
Key
对象名 (触发分块上传时返回此字段)
String

批量上传(本地文件夹上传)

功能说明

该示例展示通过组合 SDK 的基本接口,完成批量上传本地文件夹到 COS。

请求示例

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
from qcloud_cos.cos_threadpool import SimpleThreadPool

import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig中 移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048

config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token) # 获取配置对象
client = CosS3Client(config)

uploadDir = '/root/logs'
bucket = 'examplebucket-125000000'
g = os.walk(uploadDir)
# 创建上传的线程池
pool = SimpleThreadPool()
for path, dir_list, file_list in g:
for file_name in file_list:
srcKey = os.path.join(path, file_name)
cosObjectKey = srcKey.strip('/')
# 判断 COS 上文件是否存在
exists = False
try:
response = client.head_object(Bucket=bucket, Key=cosObjectKey)
exists = True
except CosServiceError as e:
if e.get_status_code() == 404:
exists = False
else:
print("Error happened, reupload it.")
if not exists:
print("File %s not exists in cos, upload it", srcKey)
pool.add_task(client.upload_file, bucket, cosObjectKey, srcKey)


pool.wait_completion()
result = pool.get_result()
if not result['success_all']:
print("Not all files upload successed. you should retry")

简单操作:简单上传对象

功能说明

上传一个对象至存储桶(PUT Object)。

方法原型

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

使用案例:简单文件上传

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

# 文件流 简单上传
file_name = 'test.txt'
with open('test.txt', 'rb') as fp:
response = client.put_object(
Bucket='examplebucket-1250000000', # Bucket 由 BucketName-APPID 组成
Body=fp,
Key=file_name,
StorageClass='STANDARD',
ContentType='text/html; charset=utf-8'
)
print(response['ETag'])

# 字节流 简单上传
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=b'abcdefg',
Key=file_name
)
print(response['ETag'])

# 本地路径 简单上传
response = client.put_object_from_local_file(
Bucket='examplebucket-1250000000',
LocalFilePath='local.txt',
Key=file_name
)
print(response['ETag'])

# chunk 简单上传
import requests
stream = requests.get('https://cloud.tencent.com/document/product/436/7778')

# 网络流将以 Transfer-Encoding:chunked 的方式传输到 COS
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=stream,
Key='picture.jpg'
)
print(response['ETag'])

# 设置 HTTP 头部 简单上传
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=b'test',
Key=file_name,
ContentType='text/html; charset=utf-8'
)
print(response['ETag'])

# 设置自定义头部 简单上传
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=b'test',
Key=file_name,
Metadata={
'x-cos-meta-key1': 'value1',
'x-cos-meta-key2': 'value2'
}
)
print(response['ETag'])

# 上传时限速
with open('test.bin', 'rb') as fp:
response = client.put_object(
Bucket='examplebucket-1250000000',
Key='exampleobject',
Body=fp,
TrafficLimit='819200'
)
print(response['ETag'])

使用案例:创建目录

COS 中的目录是'/'结尾的特殊对象名,调用 Put Object 接口即可。
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

# 创建目录
dir_to_create='path/to/create/dir/'
response = client.put_object(
Bucket='examplebucket-1250000000', # Bucket 由 BucketName-APPID 组成
Key=dir_to_create,
Body=b''
)
print(response)

使用案例:上传对象到指定的目录

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

#上传由 '/' 分隔的对象名,自动创建包含文件的文件夹。想要在此文件夹中添加新文件时,只需要在上传文件至 COS 时,将 Key 填写为此目录前缀即可。
dir_name = 'path/to/dir/'
file_name = 'test.txt'
object_key = dir_name + file_name
with open('test.txt', 'rb') as fp:
response = client.put_object(
Bucket='examplebucket-1250000000', # Bucket 由 BucketName-APPID 组成
Body=fp,
Key=object_key,
StorageClass='STANDARD',
ContentType='text/html; charset=utf-8'
)
print(response['ETag'])

全部参数请求示例

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'|'STANDARD_IA'|'ARCHIVE',
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'
},
TrafficLimit='1048576'
)

参数说明

参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Body
上传对象的内容,可以为文件流或字节流
file/bytes
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
EnableMD5
是否需要 SDK 计算 Content-MD5,默认关闭,打开后将增加上传耗时
Bool
ACL
设置对象的 ACL,例如 'private','public-read'
String
GrantFullControl
赋予被授权者所有的权限,格式为 id="OwnerUin",例如 id="100000000001"
String
GrantRead
赋予被授权者读的权限,格式为 id="OwnerUin",例如 id="100000000001"
String
StorageClass
设置对象的存储类型,STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD。更多存储类型,请参见 存储类型概述
String
Expires
设置 Expires
String
CacheControl
缓存策略,设置 Cache-Control
String
ContentType
内容类型,设置 Content-Type
String
ContentDisposition
对象名称,设置 Content-Disposition
String
ContentEncoding
编码格式,设置 Content-Encoding
String
ContentLanguage
语言类型,设置 Content-Language
String
ContentLength
设置传输长度
String
ContentMD5
设置上传对象的 MD5 值用于校验
String
Metadata
用户自定义的对象元数据, 必须以 x-cos-meta 开头,否则会被忽略
Dict
TrafficLimit
单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即800Kb/s - 800Mb/s
String

返回结果说明

除 HTTP 公共响应头外,还包括上传对象的属性,类型为 dict:
{
'ETag': 'string',
'x-cos-hash-crc64ecma': 'string',
'x-cos-request-id': 'string',
'x-cos-storage-class': 'string',
'x-cos-version-id': 'string'
}
参数名称
参数描述
类型
ETag
上传对象的 MD5 值
String
x-cos-hash-crc64ecma
文件的 CRC64 校验码
String
x-cos-request-id
请求 ID
String
x-cos-storage-class
对象存储类型
String
x-cos-version-id
开启版本控制后,对象的版本号
String

分块操作

关于分块上传的更多说明请参见 分块上传。分块上传对象可包括的操作如下:
分块上传对象:初始化分块上传,上传分块,完成所有分块上传。
分块续传:查询已上传的分块,上传分块,完成所有分块上传。
删除已上传分块。

查询分块上传

功能说明

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

方法原型

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

使用案例

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

response = client.list_multipart_uploads(
Bucket='examplebucket-1250000000',
Prefix='dir'
)

全部参数请求示例

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

参数说明

参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Prefix
默认为空,对分块上传的 key 进行筛选,匹配 prefix 为前缀的分块上传
String
Delimiter
默认为空,设置分隔符
String
KeyMarker
和 UploadIdMarker 一起使用,指明列出分块上传的起始位置
String
UploadIdMarker
和 KeyMarker 一起使用,指明列出分块上传的起始位置。如果未指定 KeyMarker,UploadIdMarker 将被忽略
String
MaxUploads
最多返回的分块上传的数量,默认为最大的1000
Int
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String

返回结果说明

获取分块上传的信息,类型为 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'
},
],
}
参数名称
参数描述
类型
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Prefix
默认为空,对分块上传的 key 进行筛选,匹配 prefix 为前缀的分块上传
String
Delimiter
默认为空,设置分隔符
String
KeyMarker
和 UploadIdMarker 一起使用,指明列出分块上传的 key 起始位置
String
UploadIdMarker
和 KeyMarker 一起使用,指明列出分块上传的 uploadId 起始位置。如果未指定 KeyMarker,UploadIdMarker 将被忽略
String
NextKeyMarker
当 IsTruncated 为 true 时,指明下一次列出分块上传的 key 的起始位置
String
NextUploadIdMarker
当 IsTruncated 为 true 时,指明下一次列出分块上传的 uploadId 的起始位置
String
MaxUploads
最多返回的分块上传的数量,默认为最大的1000
Int
IsTruncated
表示返回的分块上传是否被截断
String
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String
Upload
包含所有分块上传的 list,包括 'UploadId','StorageClass','Key','Owner','Initiator','Initiated' 等信息
List
CommonPrefixes
所有以 Prefix 开头,以 Delimiter 结尾的 Key 被归到同一类
List

初始化分块上传

功能说明

初始化分块上传(Initiate Multipart Upload),成功执行此请求后将返回 UploadId,用于后续的 Upload Part 请求。

方法原型

create_multipart_upload(Bucket, Key, **kwargs):

使用案例

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

response = client.create_multipart_upload(
Bucket='examplebucket-1250000000',
Key='exampleobject',
StorageClass='STANDARD'
)
response = client.create_multipart_upload(
Bucket='examplebucket-1250000000',
Key='multipart.txt',
StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
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']
参数名称
参数描述
类型
是否必填
Bucket
Bucket 名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
StorageClass
设置对象的存储类型,STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD。更多存储类型,请参见 存储类型概述
String
Expires
设置 Expires
String
CacheControl
缓存策略,设置 Cache-Control
String
ContentType
内容类型,设置 Content-Type
String
ContentDisposition
文件名称,设置 Content-Disposition
String
ContentEncoding
编码格式,设置 Content-Encoding
String
ContentLanguage
语言类型,设置 Content-Language
String
Metadata
用户自定义的对象元数据
Dict
ACL
设置对象的 ACL,例如 'private','public-read'
String
GrantFullControl
赋予被授权者所有的权限,格式为 id="OwnerUin",例如 id="100000000001"
String
GrantRead
赋予被授权者读的权限,格式为 id="OwnerUin",例如 id="100000000001"
String

返回结果说明

获取分块上传的初始化信息,类型为 dict:
{
'UploadId': '150219101333cecfd6718d0caea1e2738401f93aa531a4be7a2afee0f8828416f3278e5570',
'Bucket': 'examplebucket-1250000000',
'Key': 'exampleobject'
}
参数名称
参数描述
类型
UploadId
标识分块上传的 ID
String
Bucket
存储桶名称,由 BucketName-APPID 组成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String

上传分块

功能说明

分块上传对象(Upload Part)。

方法原型

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

使用案例

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

# 注意,上传分块的块数最多10000块
response = client.upload_part(
Bucket='examplebucket-1250000000',
Key='exampleobject',
Body=b'b'*1024*1024,
PartNumber=1,
UploadId='exampleUploadId'
)
# 注意,上传分块的块数最多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',
TrafficLimit='1048576'
)
参数名称
参数描述
类型
是否必填
Bucket
Bucket 名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
Body
上传分块的内容,可以为本地文件流或输入流
file/bytes
PartNumber
标识上传分块的序号
Int
UploadId
标识分块上传的 ID
String
EnableMD5
是否需要 SDK 计算 Content-MD5,默认关闭,打开后会增加上传耗时
Bool
ContentLength
设置传输长度
String
ContentMD5
设置上传对象的 MD5 值用于校验
String
TrafficLimit
单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即800Kb/s - 800Mb/s
String

返回结果说明

除 HTTP 公共响应头外,还包括上传分块的属性,类型为 dict:
{
'ETag': 'string',
'x-cos-hash-crc64ecma': 'string',
'x-cos-request-id': 'string',
'x-cos-storage-class': 'string'
}
参数名称
参数描述
类型
ETag
上传分块的 MD5 值
String
x-cos-hash-crc64ecma
分块的 CRC64 校验码
String
x-cos-request-id
请求 ID
String
x-cos-storage-class
分块的存储类型
String

查询已上传分块

功能说明

查询正在进行中的分块上传任务(List Multipart Uploads)。

方法原型

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

使用案例

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

response = client.list_parts(
Bucket='examplebucket-1250000000',
Key='exampleobject',
UploadId='exampleUploadId'
)
response = client.list_parts(
Bucket='examplebucket-1250000000',
Key='exampleobject',
UploadId=uploadid,
MaxParts=1000,
PartNumberMarker=100,
EncodingType='url'
)
参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
UploadId
标识分块上传的 ID
String
MaxParts
最多返回的分块的数量,默认为最大的1000
Int
PartNumberMarker
默认为0,从第一块列出分块,从 PartNumberMarker 下一个分块开始列出
Int
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String

返回结果说明

所有上传分块的信息,类型为 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'
}
}
参数名称
参数描述
类型
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
UploadId
标识分块上传的 ID
String
EncodingType
默认不编码,规定返回值的编码方式,可选值:url
String
MaxParts
最多返回的分块的数量,默认为最大的1000
String
IsTruncated
表示返回的分块是否被截断
String
PartNumberMarker
默认为0,从第一块列出分块,从 PartNumberMarker 下一个分块开始列出
String
NextPartNumberMarker
指明下一次列出分块的起始位置
String
StorageClass
对象的存储类型,STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD,更多存储类型,请参见 存储类型概述
String
Part
上传分块的相关信息,包括 ETag,PartNumber,Size,LastModified
String
Initiator
分块上传的创建者,包括 DisplayName 和 ID
Dict
Owner
对象拥有者的信息,包括 DisplayName 和 ID
Dict

完成分块上传

功能说明

完成整个分块上传(Complete Multipart Upload)。

方法原型

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

使用案例

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region 等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

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

参数名称
参数描述
类型
是否必填
Bucket
Bucket 名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
UploadId
标识分块上传的 ID
String
MultipartUpload
所有分块的 ETag 和 PartNumber 信息
Dict

返回结果说明

组装后的对象的相关信息,类型为 dict:
{
'ETag': '"3f866d0050f044750423e0a4104fa8cf-2"',
'Bucket': 'examplebucket-1250000000',
'Location': 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject',
'Key': 'exampleobject'
}
参数名称
参数描述
类型
ETag
合并后对象的唯一标签值,该值不是对象内容的 MD5 校验值,仅能用于检查对象唯一性。如需校验对象内容,可以在上传过程中校验单个分块的 ETag 值。
String
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Location
URL 地址
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String

终止分块上传

功能说明

终止一个分块上传并删除已上传的分块(Abort Multipart Upload)。

方法原型

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

使用案例

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

# 正常情况日志级别使用 INFO,需要定位时可以修改为 DEBUG,此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除,请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID'] # 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
# COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https' # 指定使用 http/https 协议来访问 COS,默认为 https,可不填

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

response = client.abort_multipart_upload(
Bucket='examplebucket-1250000000',
Key='exampleobject',
UploadId='exampleUploadId'
)
参数名称
参数描述
类型
是否必填
Bucket
存储桶名称,由 BucketName-APPID 构成
String
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
String
UploadId
标识分块上传的 ID
String

返回结果说明

该方法返回值为 None。

API 操作

关于简单操作的 API 接口说明,请参见 PUT Object 文档。
关于分块操作的 API 接口说明,请参见 List Multipart UploadsInitiate Multipart UploadUpload PartList PartsAbort Multipart UploadComplete Multipart Upload文档。