帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>SDK 文档>Python SDK>高级传输接口>上传可读流

上传可读流

最近更新时间：2026-10-21 18:34:06
我的收藏

本页目录：

上传可读二进制流（upload_file_from_buffer）。适用于内容通过 read(size) 提供、无需先全部载入内存的场景；SDK 使用缓冲与并发分块上传，调用完成后返回结果。

注意事项

操作的存储桶应处于 Available 状态；传输失败可能表现为服务端、客户端或本地文件异常，处理方式见 Python SDK 异常处理。
Body 必须实现 read(size)，返回字节串。仅在到达 EOF 时短读；若数据源可能暂时只返回少量内容，请先适配成满足该约定的流，避免短读被当作文件结束。空字节串表示 EOF。
第一次读取不足一个分块时直接上传，否则进入分块上传；与 upload_file 的“大小不超过阈值直接上传”边界不同。
流从当前位置开始读取；调用方负责关闭流，不要同时在其他线程读取或改变位置。本接口没有自动断点续传；失败后再次调用前应重新打开流或恢复到原起点。
本页上传文件对象，对象键末尾 / 严格区分类型，不将流上传当作目录创建接口。文件不能覆盖同名目录，目录创建见 Python SDK 上传对象。
ForbidOverwrite 仅接受 "true" / "false"；设为 "true" 时，直接上传和最终 Complete 均保留本次防覆盖条件，已有同名目标返回 409 FileAlreadyExists。
每个分块不超过 5GB，总分块数不超过 10000。本接口不根据总长度自动增大分块，请根据预计数据量选择 PartSize，不用于无限流。
MaxBufferSize 用于限制等待调度的分块数量，不是进程内存硬上限；在途请求、当前读取块及其他开销也占内存。建议设置为不小于 PartSize 的整数倍。
本接口没有 EnableMD5 或 progress_callback 命名参数；不要照搬 upload_file 的参数。
分块传输或读取失败可能遗留未完成任务；Complete 抛错时会尝试终止任务。不能假定所有失败都已自动清理；重试或手动清理前先核对最终对象和相应 UploadId。
高性能桶不支持对象版本与服务端回调，传入 VersionId、Callback、CallbackVar 会在本地报错。

请求

方法原型

def upload_file_from_buffer(self, Bucket, Key, Body, MaxBufferSize=100, PartSize=10, MAXThread=5, **kwargs)

参数说明

参数
说明
类型
是否必选
Bucket
高性能桶完整名称，例如 examplebucket-x--1250000000
string
是
Key
文件对象键，不以 / 结尾
string
是
Body
具有 read(size) 方法的二进制流
file-like
是
MaxBufferSize
排队缓冲预算，正整数，默认 100，单位 MB
int
否
PartSize
分块大小，正整数，默认 10，单位 MB
int
否
MAXThread
分块并发线程数，正整数，默认 5
int
否
ForbidOverwrite
关键字参数，仅 "true" / "false"
string
否
ContentType / Metadata
内容类型与自定义元数据；元数据键以 x-cos-meta- 开头
string / dict
否
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

返回字典，可读取 ETag。直接上传返回响应头，分块上传返回 Complete 结果；分块对象 ETag 不等同于完整内容 MD5。

错误码

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

实际案例

# -*- 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'

with open('report.bin', 'rb') as source:
    result = client.upload_file_from_buffer(
        Bucket=bucket, Key='streams/report.bin', Body=source,
        PartSize=8, MaxBufferSize=32, MAXThread=4,
        ForbidOverwrite='true', ContentType='application/octet-stream')
print('stream upload completed, ETag: %s' % result['ETag'])

中国站