对象存储 上传对象

一、注意事项

·本地文件优先使用 Python SDK 上传本地文件；可读流可使用 Python SDK 上传可读流。

·对象键不以 / 结尾表示文件对象，以 / 结尾表示目录对象；两者严格区分，不会自动转换类型。

·创建目录对象时，Body 必须为空，实际请求的 Content-Length 必须为 0；否则返回 400 DirectoryObjectContainsData。传入 Body=b'' 时 SDK 会发送 Content-Length: 0，无需另行设置 ContentLength。

·目录对象不携带 Metadata、CacheControl、ContentDisposition、ContentEncoding、ContentLanguage、ContentType、Expires 等元数据参数，携带会返回 400 InvalidArgument。文件对象的 ContentType 不使用 application/x-directory。

·文件与同名目录不能共存或相互覆盖。文件上传未开启防覆盖时，同名目录已存在会返回 409 DirAlreadyExists；文件上传设置 ForbidOverwrite='true' 时，同名文件或目录已存在均返回 409 FileAlreadyExists。创建目录时，同名文件已存在返回 409 FileAlreadyExists，同名目录已存在返回成功。

·文件对象的防覆盖条件为 ForbidOverwrite；目录创建的行为按上述目录规则处理。

·单次上传的对象大小不得超过 5GB，超过请使用分块上传（upload_file 或 Python SDK 分块上传）。

·高性能桶不支持对象版本，传入 VersionId 会本地报错；也不支持服务端 Callback/CallbackVar。

·文件对象的 ForbidOverwrite 仅接受字符串 "true" 或 "false"；置为 "true" 且同名文件已存在时会返回 409 FileAlreadyExists。

·对象键不能包含独立的 . 或 .. 路径段，SDK 会在本地报错。

·上传属于数据面接口，SDK 使用 session 临时凭证签名。

二、方法原型

def put_object(self, Bucket, Body, Key, EnableMD5=False, **kwargs)

三、参数说明

参数名称	参数描述	类型	是否必选
Bucket	高性能桶完整名称，格式为 <BucketName>-x–<APPID>	string	是
Body	上传的对象内容，可为文件流、字节流或字符串	file / bytes / string	是
Key	对象键（Object Key），即对象在桶中的完整路径	string	是
EnableMD5	是否需要 SDK 计算 Content-MD5，打开会增加上传耗时	bool	否
kwargs	可选请求参数，使用这篇列出的参数	dict	否

下列内容类型、缓存与自定义元数据参数用于文件对象：

参数名称	参数描述	类型	是否必选
ContentType	内容类型，设置 Content-Type	string	否
ContentLength	设置传输长度	int	否
ContentMD5	请求体内容的 MD5 校验值（Base64 编码），用于完整性校验	string	否
CacheControl	缓存策略，设置 Cache-Control	string	否
ContentDisposition	文件名展示方式，设置 Content-Disposition	string	否
ContentEncoding	编码格式，设置 Content-Encoding	string	否
ContentLanguage	内容语言，设置 Content-Language	string	否
Expires	设置 Expires	string	否
Metadata	用户自定义的对象元信息，键须以 x-cos-meta- 开头	dict	否
StorageClass	存储类型，高性能桶仅支持默认值（RAPID）	string	否
ForbidOverwrite	文件对象的防覆盖条件。字符串 "true" 表示不覆盖已存在的同名文件	string	否

四、响应

返回值为响应头部字典：

参数名称	参数描述	类型
响应头 dict	成功时返回响应头部字典，可通过 ETag 键读取上传对象的 ETag	dict
ETag	上传对象的 MD5 值，从响应头读取	string

五、错误码

本接口遵循统一的错误响应和错误码，详情请参见错误码文档。

六、实际案例

# -*- coding=utf-8 -*-import osfrom qcloud_cos import CosConfig, CosS3Client# 高性能桶经 VPC 内网 HTTP 80 端口接入，SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效；SDK 默认 https，此处需显式指定 http。config = CosConfig( Scheme='http', Region='ap-guangzhou', SecretId=os.environ['COS_SECRET_ID'], SecretKey=os.environ['COS_SECRET_KEY'], Token=os.environ.get('COS_SECURITY_TOKEN'), EnableRapidDomain=True)client = CosS3Client(config)bucket = 'examplebucket-x–1250000000'# 上传字节流。resp = client.put_object( Bucket=bucket, Key='exampleobject.txt', Body=b'hello rapid bucket', ContentType='text/plain')print('ETag: %s' % resp['ETag'])# 上传本地文件，并开启防覆盖。with open('local_file.txt', 'rb') as fp: resp = client.put_object( Bucket=bucket, Key='uploaded-local-file.txt', Body=fp, ForbidOverwrite='true')# 创建目录对象：空内容，不传内容类型或自定义元数据。client.put_object(Bucket=bucket, Key='photos/', Body=b'')