帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>SDK 文档>Python SDK>对象操作>上传对象

上传对象

最近更新时间：2026-10-21 18:34:05
本文档已由 AI 辅助审校
我的收藏

本页目录：

上传文件对象或创建目录对象至高性能桶（PUT Object）。单次上传的对象大小不得超过 5GB，超过请使用 Python SDK 分块上传。对高性能桶发起请求时，SDK 自动完成会话鉴权。

注意事项

本地文件优先使用 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 os
from 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'')

中国站