简介

除了通过 PUT Object 接口上传文件到 MSS 以外,MSS 还提供了另外一种上传模式——Multipart Upload。用户可以在如下的应用场景内(但不仅限于此),使用 Multipart Upload 上传模式,如:

  1. 需要支持断点上传。
  2. 上传超过 100MB 大小的文件。
  3. 网络条件较差,和 MSS 的服务器之间的链接经常断开。
  4. 上传文件之前,无法确定上传文件的大小。

Initiate Multipart Upload

初始化MultipartUpload,使用 Multipart Upload 传输数据前,必须先调用该接口来通知 MSS 初始化一个 Multipart Upload 事件。该接口会返回一个 MSS 服务器创建的全局唯一的 UploadID,用于标识本次 Multipart Upload 事件。 用户可以根据这个 ID 来发起相关的操作,如中止 Multipart Upload、查询 Multipart Upload 等。

请求语法

POST /mss-test-bucket/multi-part-obj?uploads HTTP/1.1
Host: mtmss.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

请求头部

名称 描述
Cache-Control 指定该 Object 被下载时的网页的缓存行为;更详细描述请参照RFC2616
类型:字符串
默认值:无
Content-Disposition 指定该 Object 被下载时的名称;更详细描述请参照RFC2616
类型:字符串
默认值:无
Content-Encoding 指定该Object被下载时的内容编码格式;更详细描述请参照RFC2616
类型:字符串
默认值:无
Content-MD5 根据协议RFC 1864对消息内容(不包括头部)计算MD5值获得128比特位数字,对该数字进行base64编码为一个消息的Content-MD5值。该请求头可用于消息合法性的检查(消息内容是否与发送时一致)。
类型:字符串
默认值:无
Expires 过期时间(milliseconds);更详细描述请参照RFC 1864
类型:字符串
默认值:无
x-amz-meta- 用户自定义变量,其中一个用处是:用户客户端加密时,设置秘钥对相关信息。
类型:字符串
默认值:无

响应元素(Response Elements)

名称 描述
InitiateMultipartUploadResult 保存 Initiate Multipart Upload 请求结果的容器。
类型:容器
子节点:Bucket, Key, UploadId
父节点:None
Bucket 初始化一个 Multipart Upload 事件的 Bucket 名称。
类型:字符串
父节点:InitiateMultipartUploadResult
Key 初始化一个 Multipart Upload 事件的 Object 名称。
类型:字符串
父节点:InitiateMultipartUploadResult
UploadId 唯一标示此次 Multipart Upload 事件的 ID。
类型:字符串
父节点:InitiateMultipartUploadResult

细节分析

  1. 该操作计算认证签名的时候,需要加“?uploads”到 CanonicalizedResource 中。
  2. 初始化 Multipart Upload 请求,支持如下标准的 HTTP 请求头:Cache-Control,Content- Disposition,Content-Encoding,Content-Type,Expires,以及以“x-amz-meta-”开头的用户自定义 Headers。具体含义请参见 PUT Object 接口。
  3. 初始化 Multipart Upload 请求,并不会影响已经存在的同名 object。
  4. 服务器收到初始化 Multipart Upload 请求后,会返回一个 XML 格式的请求体。该请求体内有三个元素:Bucket,Key 和 UploadID。请记录下其中的 UploadID,以用于后续的 Multipart 相关操作。

示例

请求示例:

POST /mss-test-bucket/multi-part-obj?uploads HTTP/1.1
Host: mtmss.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

返回示例:

HTTP/1.1 200 OK
Content-Length: 233
Content-Type: application/xml
Date: Wed, 28 Oct 2009 22:32:00 GMT
ETag: "fba9dede5f27731c9771645a39863328"
Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
Server: MeituanStorageService
X-Amz-Id-2: bb23c316f37ac11e3455df7d6b041a7e
X-Amz-Request-Id: 1511335933303653
X-Mss-Trace-Id: 1175465203335443831
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
    <Bucket>mss-test-bucket</Bucket>
    <Key>multi-part-obj</Key>
    <UploadId>00000007b1504008207616226/UploadId>
</InitiateMultipartUploadResult>

Upload Part

初始化一个 Multipart Upload 之后,可以根据指定的 Object 名和 Upload ID 来分片(Part)上传数据。每一个上传的 Part 都有一个标识它的号码(part number,范围是1~10,000)。 对于同一个 Upload ID,该号码不但唯一标识这一块数据,也标识了这块数据在整个文件内的相对位置。如果你用同一个 Part 号码,上传了新的数据,那么 MSS 上已有的这个号码的 Part 数据将被覆盖。 除了最后一块 Part 以外,其他的 Part 最小为5MB;最后一块 Part 没有大小限制。

请求语法

PUT /mss-test-bucket/multi-part-obj?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: mtmss.com
Content-Length:ContentLength
Content-MD5:ContentMD5
Date: GMT Date
Authorization: SignatureValue

响应头部

名称 描述
ETag ETag (entity tag) 在每个 Part 生成的时候被创建,ETag 值是该 Part 内容的 uuid,可以用于检查该 Part 内容是否发生变化。
类型:字符串

细节分析

  1. 调用该接口上传 Part 数据前,必须调用 Initiate Multipart Upload 接口,获取一个 MSS 服务器颁发的 Upload ID。
  2. 该 upload 必须是上传状态,不能为完成或者终止状态,否则返回 404 NoSuchUpload。
  3. Multipart Upload 要求除最后一个 Part 以外,其他的 Part 大小都要大于5MB。但是 Upload Part 接口并不会立即校验上传 Part 的大小(因为不知道是否为最后一块);只有当 Complete Multipart Upload 的时候才会校验。
  4. MSS 会将服务器端收到 Part 数据的 MD5 值放在 ETag 头内返回给用户,用户需记录 PartNum 与其 Etag 用于后续 Complete Multipart Upload 操作。
  5. Part 号码的范围是1~10000。如果超出这个范围,MSS 将返回 400 InvalidArgument 的错误码。
  6. 为了保证数据在网络传输过程中不出现错误,用户发送请求时携带 Content-MD5,MSS 会计算上传数据的 MD5 与用户上传的 MD5 值比较,如果不一致返回 400 BadDigest 错误码。

示例

请求示例:

PUT /mss-test-bucket/multi-part-obj?partNumber=1&uploadId=00000007b1504008207616226 HTTP/1.1
Host: mtmss.com
Content-Length: 11434
Content-MD5: pUNXr/BjKK5G2UKvaRRrOA==
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

返回示例:

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 0
ETag: "fba9dede5f27731c9771645a39863338"
Server: MeituanStorageService
x-amz-request-id: 1511257390801578
x-amz-id-2: bb23c316f37ac11e3455df7d6b041a7e
x-mss-trace-id: 1175465203331184840

Complete Multipart Upload

在将所有数据Part都上传完成后,必须调用Complete Multipart Upload API来完成整个文件的Multipart Upload。在执行该操作时,用户必须提供所有有效的数据Part的列表(包括part号码和ETAG);MSS收到用户提交的Part列表后,会逐一验证每个数据Part的有效性。当所有的数据Part验证通过后,MSS将把这些数据part组合成一个完整的Object。

请求语法

POST /mss-test-bucket/multi-part-obj?uploadId=UploadId HTTP/1.1
Host: mtmss.com
Content-Length:ContentLength
Date: GMT Date
Authorization: SignatureValue

<CompleteMultipartUpload>
  <Part>
    <PartNumber>PartNumber</PartNumber>
    <ETag>ETag</ETag>
  </Part>
  ...
</CompleteMultipartUpload>

请求元素(Request Elements)

名称 描述
CompleteMultipartUpload 保存 Complete Multipart Upload 请求内容的容器。
类型:容器
子节点:一个或多个 Part 元素
父节点:无
Part 保存已经上传 Part 信息的容器。
类型:容器
子节点:ETag, PartNumber
父节点:CompleteMultipartUpload
PartNumber Part 数目。
类型:整数
父节点:Part
ETag Part 成功上传后,MSS 返回的 ETag值。
类型:字符串
父节点:Part

响应元素(Response Elements)

名称 描述
CompleteMultipartUploadResult 保存 Complete Multipart Upload 请求结果的容器。
类型:容器
子节点:Bucket, Key, ETag, Location
父节点:None
Location 新创建 Object 的 URL。
类型:字符串
父节点:CompleteMultipartUploadResult
Bucket Bucket 名称。
类型:字符串
父节点:CompleteMultipartUploadResult
Key 新创建 Object 的名字。
类型:字符串
父节点:CompleteMultipartUploadResult
ETag ETag (entity tag) 在每个 Object 生成的时候被创建,用于标示一个 Object 的内容。Complete Multipart Upload 请求创建的 Object,ETag 值是其内容的 UUID。ETag 值可以用于检查 Object 内容是否发生变化。
类型:字符串
父节点:CompleteMultipartUploadResult

细节分析

  1. MSS 处理 Complete Multipart Upload 请求时,该 upload 必须是上传状态,不能为完成或者终止状态,否则返回 404 NoSuchUpload。处理成功后,该 Upload 状态变为完成,Upload ID 变为无效。
  2. Complete Multipart Upload 时,会确认除最后一块以外所有块的大小都大于 5MB,如果小于 5MB 返回 400 EntityTooSmall,并检查用户提交的 PartList 中的每一个 Part 号码和 Etag。所以在上传 Part 时,客户端除了需要记录 Part 号码外,还需要记录每次上传 Part 成功后,服务器返回的 ETag 值。如果 part 号码不规范,返回 400 InvalidPart。
  3. 用户提交的 Part List 中,Part 号码需要保持连续的。例如第一块的 Part 号码是1,第二块的 Part 号码是2,否则返回 400 InvalidPartOrder。
  4. 用户提交的 Part List 中的 Part 数量需要与已上传的 Part 数量一致,否则返回 400 InvalidPart。
  5. 同一个 Object 可以同时拥有不同的 Upload Id,当 Complete 一个 Upload ID 后,该 Object 的其他 Upload ID 不受影响。
  6. 如果用户上传了 Content-MD5 请求头,MSS 会计算 body 的 Content-MD5 并检查一致性,如果不一致,将返回 400 BadDigest 错误码。
  7. MSS 返回的 Etag 算法为:将所有 Part 的 Etag 顺序计算 MD5,Hex 后得到 MD5Hex,最终返回"MD5Hex-PartNum"作为 Etag。

示例

请求示例:

POST /mss-test-bucket/multi-part-obj?uploadId=00000007b1504008207616226 HTTP/1.1
Host: mtmss.com
Content-Length: 11434
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"0c78aef83f66abc1fa1e8477f296d394"</ETag>
  </Part>
  <Part>
    <PartNumber>3</PartNumber>
    <ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
  </Part>
</CompleteMultipartUpload>

返回示例:

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 233
Content-Type:  Application/xml
Server: MeituanStorageService
x-amz-request-id: 1511257390801578
x-amz-id-2: bb23c316f37ac11e3455df7d6b041a7e
x-mss-trace-id: 1175465203331184840

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult">
  <Location>http://mtmss.com/mss-test-bucket/multi-part-obj</Location>
  <Bucket>mss-test-bucket</Bucket>
  <Key>multi-part-obj</Key>
  <ETag>"3858f62230ac3c915f300c664312c11f-3"</ETag>
</CompleteMultipartUploadResult>

Abort Multipart Upload

该接口可以根据用户提供的 Upload ID 中止其对应的 Multipart Upload 事件。当一个 Multipart Upload 事件被中止后,就不能再使用这个 Upload ID 做任何操作,已经上传的 Part 数据也会被删除。

请求语法

DELETE /mss-test-bucket/multi-part-obj?uploadId=UploadId HTTP/1.1
Host: mtmss.com
Date: GMT Date
Authorization: SignatureValue

细节分析

  1. MSS 处理 Abort Multipart Upload 请求时,如果该 Upload ID 不存在,或者不为上传状态,否则返回 404 NoSuchUpload。处理成功后,该 Upload 状态变为中止,Upload ID 变为无效。
  2. 中止一个 Multipart Upload 事件时,如果其所属的某些 Part 仍然在上传,那么这次中止操作将无法删除这些 Part。所以如果存在并发访问的情况,为了彻底释放 MSS 上的空间,需要调用几次 Abort Multipart Upload 接口。

示例

请求示例:

Delete /mss-test-bucket/multi-part-obj?uploadId=00000007b1504008207616226 HTTP/1.1
Host: mtmss.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: authorization string

返回示例:

HTTP/1.1 204 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 0
Server: MeituanStorageService
x-amz-request-id: 1511257390801578
x-amz-id-2: bb23c316f37ac11e3455df7d6b041a7e
x-mss-trace-id: 1175465203331184840

List Multipart Uploads

List Multipart Uploads 可以罗列出所有执行中的 Multipart Upload 事件,即已经被初始化的 Multipart Upload 但是未被 Complete 或者 Abort 的 Multipart Upload 事件。MSS 返回的罗列结果中最多会包含1000个 Multipart Upload 信息。如果想指定 MSS 返回罗列结果内 Multipart Upload 信息的数目,可以在请求中添加 max-uploads 参数。另外,MSS 返回罗列结果中的 IsTruncated 元素标明是否还有其他的 Multipart Upload。

请求语法

GET /mss-test-bucket?uploads HTTP/1.1
Host: mtmss.com
Date: GMT Date
Authorization: SignatureValue

请求参数(Request Parameters)

名称 描述
prefix 限定返回的 object key 必须以 prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 prefix。
类型:字符串
默认值:无
delimiter 是一个用于对 object 名字进行分隔的字符。所有名字包含指定的前缀到第一次出现 delimiter 字符之间的 object 作为一组 CommonPrefixes 元素。
类型:字符串
默认值:无
max-uploads 限定此次返回 Multipart Uploads 事件的最大数目,如果不设定,默认为1000,max-uploads 取值不能大于1000。
类型:整数
默认值:1000
key-marker 与 upload-id-marker 参数一同使用来指定返回结果的起始位置。如果 upload-id-marker 参数未设置,查询结果中包含:所有 Object 名字的字典序大于 key-marker 参数值的 Multipart 事件。 如果 upload-id-marker 参数被设置,查询结果中包含:所有 Object 名字的字典序大于 key-marker 参数值的 Multipart 事件和 Object 名字等于 key-marker 参数值,但是 Upload ID 比 upload-id-marker 参数值大的 Multipart Uploads 事件。
类型:字符串
默认值:无
upload-id-marker 与 key-marker 参数一同使用来指定返回结果的起始位置。 如果 key-marker 参数未设置,则 MSS 忽略 upload-id-marker 参数。 l 如果 key-marker 参数被设置,查询结果中包含:所有 Object 名字的字典序大于 key-marker 参数值的 Multipart 事件和 Object 名字等于 key-marker 参数值,但是 Upload ID 比 upload-id-marker 参数值大的 Multipart Uploads 事件。
类型:字符串
默认值:无
encoding-type 指定对返回的内容进行编码,指定编码的类型。Delimiter、KeyMarker、Prefix、NextKeyMarker 和 Key 使用 UTF-8 字符,但 xml 1.0 标准不支持解析一些控制字符,比如 ascii 值从0到10的字符。对于包含 xml 1.0 标准不支持的控制字符,可以通过指定 encoding-type 对返回的 Delimiter、KeyMarker、Prefix、NextKeyMarker 和 Key 进行编码。
类型:字符串
默认值:无

响应元素(Response Elements)

名称 描述
ListMultipartUploadsResult 保存 List Multipart Upload 请求结果的容器。
类型:容器
子节点:Bucket, KeyMarker, UploadIdMarker, NextKeyMarker, NextUploadIdMarker, MasUploads, Delimiter, Prefix, CommonPrefixes, IsTruncated, Upload
父节点:None
Bucket Bucket 名称。
类型:字符串
父节点:ListMultipartUploadsResult
KeyMarker 列表的起始 Object 位置。
类型:字符串
父节点:ListMultipartUploadsResult
UploadIdMarker 列表的起始 UploadID 位置。
类型:字符串
父节点:ListMultipartUploadsResult
NextKeyMarker 如果本次没有返回全部结果,响应请求中将包含 NextKeyMarker 元素,用于标明接下来请求的 KeyMarker 值。
类型:字符串
父节点:ListMultipartUploadsResult
NextUploadMarker 如果本次没有返回全部结果,响应请求中将包含 NextUploadMarker 元素,用于标明接下来请求的 UploadMarker 值。
类型:字符串
父节点:ListMultipartUploadsResult
MaxUploads 返回的最大 Upload 数目。
类型:整数
父节点:ListMultipartUploadsResult
Delimiter 请求时的 delimiter。如果请求中不指定则响应时也不会有。
类型:字符串
父节点:ListMultipartUploadsResult
IsTruncated 标明是否本次返回的 Multipart Upload 结果列表被截断。“true”表示本次没有返回全部结果;“false”表示本次已经返回了全部结果。
类型:枚举字符串 有效值:false、true
默认值:false
父节点:ListMultipartUploadsResult
EncodingType 指明返回结果中编码使用的类型。如果请求的参数中指定了 encoding-type,那返回的结果会对 Delimiter、KeyMarker、Prefix、NextKeyMarker 和 Key 这些元素进行编码。
类型:字符串
父节点:ListMultipartUploadsResult
Upload 保存 Multipart Upload 事件信息的容器。
类型:容器
子节点:Key, UploadId, Initiator, Owner, StorageClass, Initiated
父节点:ListMultipartUploadsResult
Key 初始化 Multipart Upload 事件的 Object 名字。
类型:字符串
父节点:Upload
UploadId Multipart Upload 事件的 ID。
类型:字符串
父节点:Upload
Initiator 标识初始化 Multipart Upload 事件的用户。如果 Initiator 是 MSS 用户,这个容器提供的信息与 Owner 相同;如果 Initiator 是 IAM 用户,这个容器提供用户 ARN 和 Display Name。
类型:容器
子节点:ID, DisplayName
父节点:Upload
ID 如果这是一个 MSS 用户,那么它提供用户 ID;如果这是一个 IAM 用户,它提供用户的 ARN 值。
类型:字符串
父节点:Initiator, Owner
DisplayName 用户名称。
类型:字符串
父节点:Initiator, Owner
Owner 表示 Object 创建后的拥有者。如果 Multipart Upload 被 IAM 用户初始化,那么这个容器提供父用户的 ID 和 DisplayName
类型:容器
子节点:ID, DisplayName
父节点:Initiator, Owner
StorageClass Object 的存储类型。
类型:字符串
父节点:Upload
Initiated Multipart Upload 事件初始化的时间。
类型:日期
父节点:Upload
CommonPrefixes 如果请求指定 delimiter,在子节点 Prefix 中返回包含 delimiter 的 object 的不同前缀。
类型:容器
子节点:Prefix
父节点:ListMultipartUploadsResult
Prefix 如果请求指定 prefix,返回从 object 名字开始到 prefix 后第一次出现 delimiter 字符之间的不同子串。如果请求不指定 prefix,只返回第一次出现 delimiter 字符之前的 object 名字子串,这些值不在响应中其他地方出现。
类型:字符串
父节点:CommonPrefixes

细节分析

  1. “max-uploads”参数最大值为1000。
  2. 返回结果按 UploadID 字典序升序排列。
  3. 可以灵活地使用 prefix 参数对 bucket 内的 object 进行分组管理(类似与文件夹的功能)。
  4. List Multipart Uploads 请求支持5种请求参数: prefix,marker,delimiter,upload-id-marker和max-uploads。通过这些参数的组合,可以设定查询 Multipart Uploads 事件的规则,获得期望的查询结果。

示例

请求示例:

GET /mss-test-bucket?uploads HTTP/1.1
Host: mtmss.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: SignatureValue

返回示例:

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 233
Content-Type:  Application/xml
Server: MeituanStorageService
x-amz-request-id: 1511257390801578
x-amz-id-2: bb23c316f37ac11e3455df7d6b041a7e
x-mss-trace-id: 1175465203331184840

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
  <Bucket>bucket</Bucket>
  <KeyMarker></KeyMarker>
  <UploadIdMarker></UploadIdMarker>
  <NextKeyMarker>my-movie.m2ts</NextKeyMarker>
  <NextUploadIdMarker>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</NextUploadIdMarker>
  <MaxUploads>3</MaxUploads>
  <IsTruncated>false</IsTruncated>
  <Upload>
    <Key>my-divisor</Key>
    <UploadId>XMgbGlrZSBlbHZpbmcncyBub3QgaGF2aW5nIG11Y2ggbHVjaw</UploadId>
    <Initiator>
      <ID>arn:aws:iam::111122223333:user/user1-11111a31-17b5-4fb7-9df5-b111111f13de</ID>
      <DisplayName>user1-11111a31-17b5-4fb7-9df5-b111111f13de</DisplayName>
    </Initiator>
    <Owner>
      <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:48:33.000Z</Initiated> 
  </Upload>
  <Upload>
    <Key>my-movie.m2ts</Key>
    <UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
    <Initiator>
      <ID>b1d16700c70b0b05597d7acd6a3f92be</ID>
      <DisplayName>InitiatorDisplayName</DisplayName>
    </Initiator>
    <Owner>
      <ID>b1d16700c70b0b05597d7acd6a3f92be</ID>
      <DisplayName>OwnerDisplayName</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-10T20:48:33.000Z</Initiated>
  </Upload>
</ListMultipartUploadsResult>

假设 bucket 当前有这些 object 的 multipart upload :

photos/2006/January/sample.jpg
photos/2006/February/sample.jpg
photos/2006/March/sample.jpg
videos/2006/March/sample.wmv
sample.jpg

带delimiter的请求示例:

GET /mss-test-bucket?uploads&delimiter=/ HTTP/1.1
Host: mtmss.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: SignatureValue

因为除 sample.jpg 外的其他 object 名字包含了 delimiter "/", 所以返回的 Upload 中只有 sample.jpg,返回的 CommonPrefixes 包含其他 object 的前缀:从 object name 开始到第一次出现 delimiter "/" 的子字符串,photos/ 和 videos/, 表示当前有一个或多个带着这些前缀的 multipart upload。 推荐使用场景:使用子字符串创建逻辑上的文件夹结构。这样在返回结果中可以看到两个文件夹中正有 multipart upload。

响应示例

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
  <Bucket>example-bucket</Bucket>
  <KeyMarker/>
  <UploadIdMarker/>
  <NextKeyMarker>sample.jpg</NextKeyMarker>
  <NextUploadIdMarker>Xgw4MJT6ZPAVxpY0SAuGN7q4uWJJM22ZYg1W99trdp4tpO88.PT6.MhO0w2E17eutfAvQfQWoajgE_W2gpcxQw--</NextUploadIdMarker>
  <Delimiter>/</Delimiter>
  <Prefix/>
  <MaxUploads>1000</MaxUploads>
  <IsTruncated>false</IsTruncated>
  <Upload>
    <Key>sample.jpg</Key>
    <UploadId>Agw4MJT6ZPAVxpY0SAuGN7q4uWJJM22ZYg1N99trdp4tpO88.PT6.MhO0w2E17eutfAvQfQWoajgE_W2gpcxQw--</UploadId>
    <Initiator>
      <ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
      <DisplayName>s3-nickname</DisplayName>
    </Initiator>
    <Owner>
      <ID>314133b66967d86f031c7249d1d9a80249109428335cd0ef1cdc487b4566cb1b</ID>
      <DisplayName>s3-nickname</DisplayName>
    </Owner>
    <StorageClass>STANDARD</StorageClass>
    <Initiated>2010-11-26T19:24:17.000Z</Initiated>
  </Upload>
  <CommonPrefixes>
    <Prefix>photos/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>videos/</Prefix>
  </CommonPrefixes>
  </ListMultipartUploadsResult>

带prefix与delimiter的请求示例:

GET /mss-test-bucket?uploads&delimiter=/&prefix=photos/2006/ HTTP/1.1
Host: mtmss.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
Authorization: SignatureValue

带 prefix 时响应只包含带 prefix "photos/2006" 的 multipart upload。在 CommonPrefixes 中的是从开始到 prefix 后第一次出现 delimiter 的子字符串。

响应示例:

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
  <Bucket>example-bucket</Bucket>
  <KeyMarker/>
  <UploadIdMarker/>
  <NextKeyMarker/>
  <NextUploadIdMarker/>
  <Delimiter>/</Delimiter>
  <Prefix>photos/2006/</Prefix>
  <MaxUploads>1000</MaxUploads>
  <IsTruncated>false</IsTruncated>
  <CommonPrefixes>
    <Prefix>photos/2006/February/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>photos/2006/January/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>photos/2006/March/</Prefix>
  </CommonPrefixes>
</ListMultipartUploadsResult>

List Parts

List Parts 命令可以罗列出指定 Upload ID 所属的所有已经上传成功的 Part。

请求语法

GET /mss-test-bucket/multi-part-obj?uploadId=UploadId HTTP/1.1
Host: mtmss.com
Date: GMT Date
Authorization: SignatureValue

请求参数(Request Parameters)

名称 描述
uploadId Multipart Upload 事件的 ID。
类型:字符串
默认值:无
max-parts 规定在 MSS 响应中的最大 Part 数目。
类型:整数
默认值:1,000
part-number-marker 指定 List 的起始位置,只有 Part Number 数目大于该参数的 Part 会被列出。
类型:整数
默认值:无
encoding-type 指定对返回的内容进行编码,指定编码的类型。Key 使用 UTF-8 字符,但 xml 1.0 标准不支持解析一些控制字符,比如 ascii 值从0到10的字符。对于 Key 中包含 xml 1.0 标准不支持的控制字符,可以通过指定 encoding-type 对返回的 Key 进行编码。
数据类型:字符串
默认值:无,可选值:url

响应元素(Response Elements)

名称 描述
ListPartsResult 保存 List Part 请求结果的容器。
类型:容器
子节点:Bucket, Key, UploadId, PartNumberMarker, NextPartNumberMarker, MaxParts, IsTruncated, Part
父节点:无
Bucket Bucket 名称。
类型:字符串
父节点:ListPartsResult
EncodingType 指明对返回结果进行编码使用的类型。如果请求的参数中指定了 encoding-type,那会对返回结果中的Key进行编码。
类型:字符串
父节点:ListPartsResult
Key Object 名称。
类型:字符串
父节点:ListPartsResult
UploadID Upload 事件 ID。
类型:字符串
父节点:ListPartsResult
Initiator 标识初始化 Multipart Upload 事件的用户。如果 Initiator 是 MSS 用户,这个容器提供的信息与 Owner 相同;如果 Initiator 是 IAM 用户,这个容器提供用户 ARN 和 Display Name。
类型:容器
子节点:ID, DisplayName
父节点:Upload
ID 如果这是一个 MSS 用户,那么它提供用户 ID;如果这是一个 IAM 用户,它提供用户的 ARN 值。
类型:字符串
父节点:Initiator, Owner
DisplayName 用户名称。
类型:字符串
父节点:Initiator, Owner
Owner 表示 Object 创建后的拥有者。如果 Multipart Upload 被 IAM 用户初始化,那么这个容器提供父用户的 ID 和 DisplayName
类型:容器
子节点:ID, DisplayName
父节点:Initiator, Owner
StorageClass Object 的存储类型。
类型:字符串
父节点:Upload
PartNumberMarker 本次 List 结果的 Part Number 起始位置。
类型:整数
父节点:ListPartsResult
NextPartNumberMarker 如果本次没有返回全部结果,响应请求中将包含 NextPartNumberMarker 元素,用于标明接下来请求的 PartNumberMarker 值。
类型:整数
父节点:ListPartsResult
MaxParts 返回请求中最大的 Part 数目。
类型:整数
父节点:ListPartsResult
IsTruncated 标明是否本次返回的 List Part 结果列表被截断。“true”表示本次没有返回全部结果;“false”表示本次已经返回了全部结果。
类型:枚举字符串 有效值:true、false
父节点:ListPartsResult
Part 保存 Part 信息的容器。
类型:字符串
子节点:PartNumber,LastModified, ETag, Size
父节点:ListPartsResult
PartNumber 标示 Part 的数字。
类型:整数
父节点:ListPartsResult.Part
LastModified Part 上传的时间。
类型:日期
父节点:ListPartsResult.part
ETag 已上传 Part 内容的 ETag。
类型:字符串
父节点:ListPartsResult.Part
Size 已上传 Part 大小。
类型:整数
父节点:ListPartsResult.Part

细节分析

  1. List Parts 支持 max-parts 和 part-number-marker 两种请求参数。
  2. max-parts 参数最大值为1000;默认值也为1000。
  3. 在 MSS 的返回结果按照 Part 号码升序排列。
  4. 由于网络传输可能出错,所以不推荐用 List Part 出来的结果(Part Number和ETag值)来生成最后 Complete Multipart 的 Part 列表。

示例

请求示例:

GET /mss-test-bucket/multi-part-obj?uploadId=00000007b1504008207616226 HTTP/1.1
Host: mtmss.com
Date: Wed, 22 Nov 2017 19:16:10 GMT
Authorization: SignatureValue

返回示例:

HTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Content-Length: 1373
Content-Type:  Application/xml
Server: MeituanStorageService
x-amz-request-id: 1511257390801578
x-amz-id-2: bb23c316f37ac11e3455df7d6b041a7e
x-mss-trace-id: 1175465203331184840

<?xml version="1.0" encoding="UTF-8"?>
<ListPartsResult>
<Bucket>test_bucket_encrypt</Bucket>
<Key>40M</Key>
<UploadId>0a1050171511349261149759</UploadId>
<Initiator>
    <ID>WqsZjCjt7EWd6UdHZtAkHw==</ID>
    <DisplayName>WqsZjCjt7EWd6UdHZtAkHw==</DisplayName>
</Initiator>
<Owner>
    <ID>WqsZjCjt7EWd6UdHZtAkHw==</ID>
    <DisplayName>WqsZjCjt7EWd6UdHZtAkHw==</DisplayName>
</Owner>
<StorageClass>3R</StorageClass>
<PartNumberMarker>0</PartNumberMarker>
<NextPartNumberMarker>0</NextPartNumberMarker>
<MaxParts>1000</MaxParts>
<IsTruncated>false</IsTruncated>
<Part>
    <PartNumber>1</PartNumber>
    <LastModified>2017-11-22T11:14:21.000Z</LastModified>
    <ETag>"8f4e33f3dc3e414ff94e5fb6905cba8c"</ETag>
    <Size>20971520</Size>
</Part>
<Part>
    <PartNumber>2</PartNumber>
    <LastModified>2017-11-22T11:14:22.000Z</LastModified>
    <ETag>"8f4e33f3dc3e414ff94e5fb6905cba8c"</ETag>
    <Size>20971520</Size>
</Part>
</ListPartsResult>