tencent cloud

对象存储

动态与公告
产品动态
产品公告
产品简介
产品概述
功能概览
应用场景
产品优势
基本概念
地域和访问域名
规格与限制
产品计费
计费概述
计费方式
计费项
免费额度
计费示例
查看和下载账单
欠费说明
常见问题
快速入门
控制台快速入门
COSBrowser 快速入门
用户指南
创建请求
存储桶
对象
数据管理
批量处理
全球加速
监控与告警
运维中心
数据处理
内容审核
智能工具箱
数据工作流
应用集成
工具指南
工具概览
环境安装与配置
COSBrowser 工具
COSCLI 工具
COSCMD 工具
COS Migration 工具
FTP Server 工具
Hadoop 工具
COSDistCp 工具
HDFS TO COS 工具
GooseFS-Lite 工具
在线辅助工具
自助诊断工具
实践教程
概览
访问控制与权限管理
性能优化
使用 AWS S3 SDK 访问 COS
数据容灾备份
域名管理实践
图片处理实践
COS 音视频播放器实践
工作流实践
数据直传
内容审核实践
数据安全
数据校验
大数据实践
COS 成本优化解决方案
在第三方应用中使用 COS
迁移指南
本地数据迁移至 COS
第三方云存储数据迁移至 COS
以 URL 作为源地址的数据迁移至 COS
COS 之间数据迁移
Hadoop 文件系统与 COS 之间的数据迁移
数据湖存储
云原生数据湖
元数据加速
数据加速器 GooseFS
数据处理
数据处理概述
图片处理
媒体处理
内容审核
文件处理
文档处理
故障处理
获取 RequestId 操作指引
通过外网上传文件至 COS 缓慢
访问 COS 时返回403错误码
资源访问异常
POST Object 常见异常
API 文档
简介
公共请求头部
公共响应头部
错误码
请求签名
操作列表
Service 接口
Bucket 接口
Object 接口
批量处理接口
数据处理接口
任务与工作流
内容审核接口
云查毒接口
SDK 文档
SDK 概览
准备工作
Android SDK
C SDK
C++ SDK
.NET(C#) SDK
Flutter SDK
Go SDK
iOS SDK
Java SDK
JavaScript SDK
Node.js SDK
PHP SDK
Python SDK
React Native SDK
小程序 SDK
错误码
鸿蒙(Harmony) SDK
终端 SDK 质量优化
安全与合规
数据容灾
数据安全
访问管理
常见问题
热门问题
一般性问题
计费计量问题
域名合规问题
存储桶配置问题
域名和 CDN 问题
文件操作问题
日志监控问题
权限管理问题
数据处理问题
数据安全问题
预签名 URL 问题
SDK 类问题
工具类问题
API 类问题
服务协议
Service Level Agreement
隐私政策
数据处理和安全协议
联系我们
词汇表

Upload Part

PDF
聚焦模式
字号
最后更新时间: 2025-12-15 10:02:19

功能描述

Upload Part 接口请求实现将对象按照分块的方式上传到 COS。最多支持10000分块,每个分块大小为1MB - 5GB,最后一个分块可以小于1MB。

分块上传步骤说明

分块上传首先需要进行初始化,使用 Initiate Multipart Upload 接口实现,初始化后将得到一个 UploadId(用于唯一标识本次上传)。
在每次请求 Upload Part 时,需要携带初始化时所指定的 Key(对象键)、 partNumber(块的编号) 和 uploadId,支持乱序上传。
注意:
如果传入 uploadId 和 partNumber 都相同时,后发起上传请求的块将覆盖之前已传入的块。如果分块上传的对象刚好为低频存储/低频存储(多 AZ)、归档存储或者深度归档存储类型的对象,则覆盖操作将会产生提前删除费用,详情请参见 关于提前删除的说明
如果传入的 uploadId 不存在,将返回404错误 NoSuchUpload。
只有主账号或者被授权 Upload Part 接口权限的子账号可以调用该接口。


授权说明

授权策略中 action 设置为 cos:UploadPart 。查看所有 action

请求

请求示例

PUT /<ObjectKey>?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-Type: Content Type
Content-Length: Content Length
Content-MD5: MD5
Authorization: Auth String

[Object Part]
说明
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com,其中 <BucketName-APPID> 为带 APPID 后缀的存储桶名字,例如 examplebucket-1250000000,可参阅 存储桶概览 > 基本信息存储桶概述 > 存储桶命名规范 文档;<Region> 为 COS 的可用地域,可参阅 地域和访问域名 文档。
Authorization: Auth String(详情请参见 请求签名 文档)。

请求参数

名称
描述
类型
是否必选
ObjectKey
调用 Initiate Multipart Upload 接口初始化时所指定的对象键(Object 的名称),详情请参见 对象概述
string
partNumber
标识本次分块上传的编号,范围在1 - 10000
integer
uploadId
标识本次分块上传的 ID,使用 Initiate Multipart Upload 接口初始化分块上传时得到的 UploadId
string

请求头

此接口除使用公共请求头部外,还支持以下请求头部,了解公共请求头部详情请参见 公共请求头部 文档。
名称
描述
类型
是否必选
x-cos-traffic-limit
针对本分块上传进行流量控制的限速值,必须为数字,单位默认为 bit/s。限速值设置范围为819200 - 838860800,即800Kb/s-800Mb/s,如果超出该范围将返回400错误
integer
x-cos-psize-max
限定上传分块大小最大值,单位 Byte。分块大小大于该值会被判为上传失败。
说明:
配合 Complete Multipart Upload 接口的 x-cos-pnum-max 头部(用于限制分块数量的最大值)一起使用,可以限制分块上传文件大小的最大值。
integer
x-cos-psize-min
限定上传分块大小最小值,单位 Byte。分块大小小于该值会被判为上传失败。
说明:
配合 Complete Multipart Upload 接口的 x-cos-pnum-min 头部(用于限制分块数量的最小值)一起使用,可以限制分块上传文件大小的最小值。
integer
服务端加密(SSE)相关头部
如果当前分块上传在初始化时使用了 SSE-C,那么在上传分块时需指定与初始化分块上传时所指定的加密算法和密钥信息,否则不能指定下列头部。
名称
描述
类型
是否必选
x-cos-server-side-encryption-customer-algorithm
服务端加密算法,目前仅支持 AES256
string
x-cos-server-side-encryption-customer-key
服务端加密密钥的 Base64 编码
例如MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
string
x-cos-server-side-encryption-customer-key-MD5
服务端加密密钥的 MD5 哈希值,使用 Base64 编码
例如U5L61r7jcwdNvT7frmUG8g==
string

请求体

此接口请求的请求体为对象(文件)分块内容。

响应

响应头

此接口除返回公共响应头部外,还返回以下响应头部,了解公共响应头部详情请参见 公共响应头部 文档。
服务端加密(SSE)相关头部
如果当前分块上传在初始化时使用了服务端加密,则此接口将返回服务端加密专用头部,请参见 服务端加密专用头部

响应体

此接口响应体为空。

错误码

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

实际案例

案例一:简单案例

请求

PUT /exampleobject?partNumber=1&uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:14 GMT
Content-Type: application/octet-stream
Content-Length: 1048576
Content-MD5: OScKloo1fSQgfpkRFiUH6w==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1585130834;1585138034&q-key-time=1585130834;1585138034&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=partnumber;uploadid&q-signature=a815da18232cfec87e8218f32f31b1e2c5eb****
Connection: close

[Object Part]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Wed, 25 Mar 2020 10:07:14 GMT
ETag: "39270a968a357d24207e9911162507eb"
Server: tencent-cos
x-cos-hash-crc64ecma: 9973912126177188060
x-cos-request-id: NWU3YjJkNTJfZDBjODJhMDlfMjU4NTZfMjc5MzBh****

案例二:使用服务端加密 SSE-COS

请求

PUT /exampleobject?partNumber=1&uploadId=1590862540251355295a5c736513d70d42b92bbde4f0fafb5e0ecb314b55aa0018cc9fa76f HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:15:50 GMT
Content-Type: application/octet-stream
Content-Length: 13
Content-MD5: EI9SjrY7Zec08nrjMfX/qg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862550;1590869750&q-key-time=1590862550;1590869750&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=partnumber;uploadid&q-signature=2a0085596de5861410bcc43f3d107dc9dda5****
Connection: close

[Object Part]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Sat, 30 May 2020 18:15:51 GMT
ETag: "108f528eb63b65e734f27ae331f5ffaa"
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEyZDZfYjNjMjJhMDlfMmJlM18zOWI2****
x-cos-server-side-encryption: AES256

案例三:使用服务端加密 SSE-KMS

请求

PUT /exampleobject?partNumber=1&uploadId=15908625793957d71176fa878282d266a95b79dc2aec159b4a73d1d79c80d4f931cda6ad65 HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:16:29 GMT
Content-Type: application/octet-stream
Content-Length: 13
Content-MD5: EI9SjrY7Zec08nrjMfX/qg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862589;1590869789&q-key-time=1590862589;1590869789&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=partnumber;uploadid&q-signature=2d1231c77c72727bd1c2454726813e095a7e****
Connection: close

[Object Part]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Sat, 30 May 2020 18:16:30 GMT
ETag: "1d3e8ae9da423b440341b09f1616f074"
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEyZmRfYTRiOTJhMDlfMTE0ZGRfMmE3OTk4****
x-cos-server-side-encryption: cos/kms
x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****

案例四:使用服务端加密 SSE-C

请求

PUT /exampleobject?partNumber=1&uploadId=1590862610acd643927bad05cd3947bf98b56b04b0b0b2a45a49969f87cc95b7fd5fcc065a HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Sat, 30 May 2020 18:17:01 GMT
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
Content-Type: application/octet-stream
Content-Length: 13
Content-MD5: EI9SjrY7Zec08nrjMfX/qg==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1590862621;1590869821&q-key-time=1590862621;1590869821&q-header-list=content-length;content-md5;content-type;date;host;x-cos-server-side-encryption-customer-algorithm;x-cos-server-side-encryption-customer-key;x-cos-server-side-encryption-customer-key-md5&q-url-param-list=partnumber;uploadid&q-signature=6d0914f1db0e03569b6b5d340dc8d71616bf****
Connection: close

[Object Part]

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: close
Date: Sat, 30 May 2020 18:17:01 GMT
ETag: "ff14981a35a58eb97bca838b055c573b"
Server: tencent-cos
x-cos-hash-crc64ecma: 4510578591875220731
x-cos-request-id: NWVkMmEzMWRfYjRjOTJhMDlfYWRhXzFhZmYw****
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈