使用Multipart Upload模式传输数据前，您必须先调用InitiateMultipartUpload接口来通知OSS初始化一个Multipart Upload事件。

注意事项

  • 调用接口会返回一个OSS服务器创建的全局唯一的Upload ID，用于标识本次Multipart Upload事件。您可以根据这个ID来发起相关的操作，例如中止Multipart Upload、查询Multipart Upload等。
  • 初始化Multipart Upload请求，并不影响已存在的同名Object。
  • 该操作计算认证签名时，需要添加?uploads到CanonicalizedResource中。
  • 要通知OSS初始化一个Multipart Upload事件，您必须有oss:PutObject权限。具体操作，请参见为RAM用户授权自定义的权限策略。

请求语法

POST /ObjectName?uploads HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT date
Authorization: SignatureValue

当您在OSS ON云盒中调用该接口时，您需要将Host替换为云盒Endpoint。更多信息，请参见云盒Endpoint。

请求头

初始化Multipart Upload请求时，支持标准的HTTP请求头Cache-Control、Content-Disposition、Content-Encoding、Content-Type、Expires以及以x-oss-meta-开头的用户自定义Header。更多信息，请参见PutObject。

名称类型描述
Cache-Control字符串 指定该Object被下载时的网页的缓存行为。更多信息，请参见RFC 2616。

默认值：无

Content-Disposition字符串 指定该Object被下载时的名称。更多信息，请参见RFC 2616。

默认值：无

Content-Encoding字符串 指定该Object被下载时的内容编码格式。更多信息，请参见RFC 2616。

默认值：无

Expires整数 缓存内容的过期时间，单位为毫秒。更多信息，请参见RFC 2616。

默认值：无

x-oss-forbid-overwrite字符串指定InitiateMultipartUpload操作时是否覆盖同名Object。当目标Bucket处于已开启或已暂停的版本控制状态时，x-oss-forbid-overwrite请求Header设置无效，即允许覆盖同名Object。
  • 不指定x-oss-forbid-overwrite或者指定x-oss-forbid-overwrite为false时，表示允许覆盖同名Object。
  • 指定x-oss-forbid-overwrite为true时，表示禁止覆盖同名Object。

设置x-oss-forbid-overwrite请求Header会导致QPS处理性能下降，如果您有大量的操作需要使用x-oss-forbid-overwrite请求Header（QPS>1000），请联系技术支持，避免影响您的业务。

x-oss-server-side-encryption字符串 指定上传该Object的每个part时使用的服务器端加密方式。

取值：AES256、KMS或SM4

重要
  • 在OSS ON云盒使用场景中，仅支持AES256。
  • 使用KMS加密算法前，您需要先开通密钥管理服务KMS。

指定此参数后，在响应头中会返回此参数，OSS会对上传的每个part进行加密编码存储。当下载该Object时，响应头中会包含x-oss-server-side-encryption，且该值会被设置成此Object的加密算法。

x-oss-server-side-data-encryption字符串指定Object的加密算法。如果未指定此选项，表明Object使用AES256加密算法。此选项仅当x-oss-server-side-encryption为KMS时有效。

取值：SM4

说明 在OSS ON云盒使用场景中，不支持使用此选项。
x-oss-server-side-encryption-key-id字符串表示KMS托管的用户主密钥。

该参数在x-oss-server-side-encryption值为KMS时有效。

说明 在OSS ON云盒使用场景中，不支持使用此选项。
x-oss-storage-class字符串 指定Object的存储类型。

对于任意存储类型Bucket，如果上传Object时指定该值，则此次上传的Object将存储为指定的类型。例如在IA类型的Bucket中上传Object时，如果指定x-oss-storage-class为Standard，则该Object直接存储为Standard类型。

取值：
  • Standard：标准存储
  • IA：低频访问
  • Archive：归档存储
  • ColdArchive：冷归档存储
  • DeepColdArchive：深度冷归档存储
说明 在OSS ON云盒使用场景中，仅支持Standard类型。

关于存储类型的更多信息，请参见存储类型介绍。

x-oss-tagging字符串指定Object的标签，可同时设置多个标签，例如： TagA=A&TagB=B
说明 Key和Value需要先进行URL编码，如果某项没有=，则看作Value为空字符串。

请求参数

调用此接口时，可以通过encoding-type对返回结果中的Key进行编码。

名称类型描述
encoding-type字符串指定对返回的Key进行编码，目前支持URL编码。Key使用UTF-8字符，但XML 1.0标准不支持解析一些控制字符，例如ASCII值从0到10的字符。对于Key中包含XML 1.0标准不支持的控制字符，可以通过指定encoding-type对返回的Key进行编码。

默认值：无

可选值：url

响应元素

服务器收到初始化Multipart Upload请求后，会返回一个XML格式的请求体。该请求体内包含Bucket、Key和UploadID三个元素。

名称类型描述
InitiateMultipartUploadResult容器保存Initiate Multipart Upload请求结果的容器。

子节点：Bucket, Key, UploadId, EncodingType

父节点：None

Bucket字符串 初始化一个Multipart Upload事件的Bucket名称。

父节点：InitiateMultipartUploadResult

Key字符串初始化一个Multipart Upload事件的Object名称。

父节点：InitiateMultipartUploadResult

UploadId字符串 唯一标识此次Multipart Upload事件的ID，用于后续调用UploadPart和CompleteMultipartUpload接口。

父节点：InitiateMultipartUploadResult

EncodingType字符串指明返回结果中编码使用的类型。如果请求的参数中指定了encoding-type，那返回的结果会对Key进行编码。

父节点：InitiateMultipartUploadResult

此接口还包含其他公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

示例

  • 请求示例 
    POST /multipart.data?uploads HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Wed, 22 Feb 2012 08:32:21 GMT 
x-oss-storage-class: Archive
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:/cluRFtRwMTZpC2hTj4F67AG****
  • 返回示例 
    HTTP/1.1 200 OK
Content-Length: 230
Server: AliyunOSS
Connection: keep-alive
x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eae****
Date: Wed, 22 Feb 2012 08:32:21 GMT
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
    <Bucket> oss-example</Bucket>
    <Key>multipart.data</Key>
    <UploadId>0004B9894A22E5B1888A1E29F823****</UploadId>
</InitiateMultipartUploadResult>

SDK

此接口所对应的各语言SDK如下：

错误码

错误码HTTP状态码描述
InvalidEncryptionAlgorithmError400指定OSS服务器端除AES256、KMS或SM4以外的加密方式。
InvalidArgument400在上传每个part时继续添加x-oss-server-side-encryption请求头。
InvalidArgument400指定存储类型的值不合法。
KmsServiceNotEnabled403使用KMS加密算法时，没有在控制台开通密钥管理服务KMS。
FileAlreadyExists409当请求的Header中携带x-oss-forbid-overwrite=true时，表示禁止覆盖同名文件。如果已存在同名文件，则返回该错误。