对象存储 InitiateMultipartUpload

InitiateMultipartUpload 接口请求实现初始化分块上传，成功执行此请求后将返回一个全局唯一的 UploadId，用于后续 UploadPart、UploadPartCopy、CompleteMultipartUpload、AbortMultipartUpload、ListParts 等接口。
注意事项
适用场景
分块上传仅用于上传文件对象，目标对象键不应以 / 结尾。目录对象的创建请直接使用 PutObject。
元数据头部归属
本接口在初始化阶段携带的 Cache-Control、Content-Disposition、Content-Encoding、Content-Language、Content-Type、Expires、x-cos-meta-* 等头部，将作为最终对象的元数据保存，并在 CompleteMultipartUpload 完成时一并固化。
未完成的分块上传
调用本接口后，若长时间未调用 CompleteMultipartUpload 或 AbortMultipartUpload，对应 UploadId 及其已上传分块会持续占用存储桶空间。建议调用方在适当时机主动调用 AbortMultipartUpload 释放，或通过 ListMultipartUploads 进行盘点。
请求
请求语法
POST /<ObjectKey>?uploads HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Content-Type: <Content Type>
Content-Length: 0
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。
请求参数
参数名称
描述
类型
是否必选
uploads
用于声明本次请求为初始化分块上传，固定为空串。
string
是
请求头部
除 公共请求头部 外，本接口还支持以下请求头部：
常规请求头部
Header 名称
描述
类型
是否必选
Cache-Control
RFC 2616 中定义的缓存指令，将作为对象元数据保存
string
否
Content-Disposition
RFC 2616 中定义的文件名称，将作为对象元数据保存
string
否
Content-Encoding
RFC 2616 中定义的编码格式，将作为对象元数据保存
string
否
Content-Language
RFC 2616 中定义的内容语言，将作为对象元数据保存
string
否
Content-Type
RFC 2616 中定义的 HTTP 请求内容类型（MIME），用于描述待上传对象的内容类型，将作为对象元数据保存。本接口不支持指定为 application/x-directory，否则返回 InvalidArgument
string
否
Expires
RFC 2616 中定义的缓存失效时间，将作为对象元数据保存
string
否
专用请求头部
Header 名称
描述
类型
是否必选
x-cos-meta-[自定义后缀]
用户自定义元数据头部，例如 x-cos-meta-test: test metadata。自定义后缀仅支持减号（-）、数字、英文小写字母（a~z），英文大写字母会被归一为小写
string
否
x-cos-storage-class
对象存储类型，当前仅支持 RAPID（默认值）。指定其他取值时返回 NotSupportedStorageClass
enum
否
请求体
该请求的请求体为空。
响应
响应头部
仅返回 公共响应头部，本接口无私有响应头部。
响应体
请求成功，返回 application/xml 数据，包含分块上传初始化信息。
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
    <Bucket>string</Bucket>
    <Key>string</Key>
    <UploadId>string</UploadId>
</InitiateMultipartUploadResult>
具体节点说明：
节点名称
父节点
描述
类型
InitiateMultipartUploadResult
无
保存 InitiateMultipartUpload 结果的所有信息
Container
Bucket
InitiateMultipartUploadResult
目标存储桶名称，形式为 <BucketName-APPID>
string
Key
InitiateMultipartUploadResult
目标对象键
string
UploadId
InitiateMultipartUploadResult
本次分块上传的全局唯一标识，后续 UploadPart、CompleteMultipartUpload、AbortMultipartUpload 等接口需要使用
string
错误码
本接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。
实际案例
案例一：初始化一个分块上传
请求
POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: video/mp4
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;content-type;date;host&q-url-param-list=uploads&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
<Bucket>examplebucket-x--1250000000</Bucket>
    <Key>exampleobject</Key>
    <UploadId>1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361</UploadId>
</InitiateMultipartUploadResult>
案例二：初始化时指定元数据
本案例在初始化分块上传时携带 Cache-Control、Content-Disposition 以及自定义元数据，这些头部会随分块上传完成一并保存为目标对象的元数据。
请求
POST /exampleobject?uploads HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
Content-Type: video/mp4
Cache-Control: max-age=86400
Content-Disposition: attachment; filename=example.mp4
x-cos-meta-author: alice
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=cache-control;content-disposition;content-length;content-type;date;host;x-cos-meta-author&q-url-param-list=uploads&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
﻿
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
<Bucket>examplebucket-x--1250000000</Bucket>
    <Key>exampleobject</Key>
    <UploadId>1590654934dfb1343b4323b711afc22569c18af51596d4f2e40faf392fe1bb469c5b77115f</UploadId>
</InitiateMultipartUploadResult>
﻿

参数名称	描述	类型	是否必选
uploads	用于声明本次请求为初始化分块上传，固定为空串。	string	是

Header 名称	描述	类型	是否必选
Cache-Control	RFC 2616 中定义的缓存指令，将作为对象元数据保存	string	否
Content-Disposition	RFC 2616 中定义的文件名称，将作为对象元数据保存	string	否
Content-Encoding	RFC 2616 中定义的编码格式，将作为对象元数据保存	string	否
Content-Language	RFC 2616 中定义的内容语言，将作为对象元数据保存	string	否
Content-Type	RFC 2616 中定义的 HTTP 请求内容类型（MIME），用于描述待上传对象的内容类型，将作为对象元数据保存。本接口不支持指定为 `application/x-directory`，否则返回 `InvalidArgument`	string	否
Expires	RFC 2616 中定义的缓存失效时间，将作为对象元数据保存	string	否

节点名称	父节点	描述	类型
InitiateMultipartUploadResult	无	保存 InitiateMultipartUpload 结果的所有信息	Container
Bucket	InitiateMultipartUploadResult	目标存储桶名称，形式为 `<BucketName-APPID>`	string
Key	InitiateMultipartUploadResult	目标对象键	string
UploadId	InitiateMultipartUploadResult	本次分块上传的全局唯一标识，后续 UploadPart、CompleteMultipartUpload、AbortMultipartUpload 等接口需要使用	string

InitiateMultipartUpload

本页目录：

注意事项

适用场景

元数据头部归属

未完成的分块上传

请求

请求语法

请求参数

请求头部

常规请求头部

专用请求头部

请求体

响应

响应头部

响应体

错误码

实际案例

案例一：初始化一个分块上传

请求

响应

案例二：初始化时指定元数据

请求

响应