该接口用于列出所有已经通过Initiate Multipart Upload请求初始化,但未完成或未终止的分片上传过程。
响应中最多返回1000个分片上传过程的信息,它既是响应能返回的最大分片上传过程数目,也是请求的默认值。用户也可以通过设置max-uploads参数来限制响应中的分片上传过程数目。如果当前的分片上传过程数超出了这个值,则响应中会包含一个值为true的IsTruncated元素。如果用户要列出多于这个值的分片上传过程信息,则需要继续调用List Multipart Uploads请求,并在请求中设置key-marker和upload-id-marker参数。
在响应体中,分片上传过程的信息通过key来排序。如果用户的应用程序中启动了多个使用同一key文件开头的分片上传过程,那么响应体中分片上传过程首先是通过key来排序,在相同key的分片上传内部则是按上传启动的起始时间的升序来进行排列。
请求语法
GET /?uploads HTTP/1.1
Host: BucketName.oos-cn.ctyunapi.cn
Date: Date
Authorization: SignatureValue
请求参数
名称 | 描述 | 是否必须 |
---|---|---|
BucketName | 存储桶名称。 | 是 |
delimiter | 分隔符,一个用来对关键字们进行分组的字符。所有的关键字都包含delimiter和prefix间的相同子串,prefix之后第一个遇到delimiter的字符串都会加到一个叫CommonPrefix的组中。如果没有特别定义prefix,所有的关键字都会被返回,但不会有CommonPrefix。delimiter只支持”/”,不支持其他分隔符。 类型:字符串。 |
否 |
max-uploads | 设置返回的分片上传过程的最大数目。 类型:整型。 取值:[1, 1000]。 默认值:1000。 |
否 |
key-marker | 与upload-id-marker参数一起,该参数指定列表操作从什么位置后面开始。如果upload-id-marker参数没有被指定,那么只有比key-marker参数指定的key更大的key会被列出。如果upload-id-marker参数被指定,任何包含与key-marker指定值相等或大于key的分片上传过程都会被包括,假设这些分片上传过程包含了比upload-id-marker指定值更大的ID。 类型:字符串。 |
否 |
prefix | 该参数用于列出那些以prefix为前缀的正在进行的上传过程,用户可以使用多个prefix来把一个bucket分成不同的组(可以考虑采用类似文件系统中的文件夹的作用那样,使用prefix来对key进行分组)。 类型:字符串。 |
否 |
encoding-type | 指定响应中KeyMarker、NextKeyMarker、Key、Prefix、Delimiter的编码类型。如果KeyMarker、NextKeyMarker、Key、Prefix、Delimiter包含xml 1.0标准不支持的控制字符,可通过设置该参数对响应中的KeyMarker、NextKeyMarker、Key、Prefix、Delimiter进行编码。 类型:字符串。 取值:url,字母不区分大小写。 |
否 |
upload-id-marker | 与key-marker参数一起,指定列表操作从什么位置后面开始。如果key-marker没有被指定,upload-id-marker参数也会被忽略。否则,任何key值等于或大于key-marker的上传过程都会被包含在列表中,只要ID大于upload-id-marker指定的值。 | 否 |
响应结果
名称 描述 ListMultipartUploadsResult 包含整个响应的容器。
类型:容器。
子节点:Bucket、KeyMarker、UploadIdMarker、NextKeyMarker、NextUploadIdMarker、Maxuploads、Delimiter、Prefix、CommonPrefixes、IsTruncated、EncodingType、Upload。
Bucket 分片上传对应的容器名称。
类型:字符串。
父节点:ListMultipartUploadsResult。
KeyMarker 指定key值,在这个key当前位置或它之后开始列表操作。
类型:字符串。
父节点:ListMultipartUploadsResult。
UploadIdMarker 指定分片上传ID,在这个ID所在位置之后开始列表操作。
类型:字符串。
父节点:ListMultipartUploadsResult。
NextKeyMarker 当此次列表不能将所有正在执行的分片上传过程列举完成时,NextKeyMarker作为下一次列表请求的key-marker参数的值。
类型:字符串。
父节点:ListMultipartUploadsResult。
NextUploadIdMarker 当此次列表不能将所有正在执行的分片上传过程列举完成时,NextKeyMarker作为下一次列表请求的upload-id-marker参数的值。
类型:字符串。
父节点:ListMultipartUploadsResult。
MaxUploads 响应中包含的上传过程的最大数目。
类型:字符串。
父节点:ListMultipartUploadsResult。
IsTruncated 标识此次分片上传过程中的所有片段是否全部被列出,如果为true则表示没有全部列出。如果分片上传过程的片段数超过了MaxParts元素指定的最大数,则会导致一次列表请求无法将所有片段数列出。
类型:Boolean。
父节点:ListMultipartUploadsResult。
EncodingType KeyMarker、NextKeyMarker、Key、Prefix、Delimiter的编码类型。
类型:字符串。
父节点:ListMultipartUploadsResult。
Upload 某个分片上传过程的容器,响应体中可能包含0个或多个Upload元素。
类型: 容器。
父节点: ListMultipartUploadsResult。
子节点: Key、UploadId、Initiator、Owner、StorageClass、Initiated。
Key 分片上传过程起始位置文件的Key值。
类型: String。
父节点: Upload。
UploadId 分片上传过程的ID号。
类型: 整型。
父节点: Upload。
Initiator 指定执行此次分片上传过程的用户账户。
类型:容器。
父节点:Upload。
子节点:ID,DisplayName。
ID OOS账户的ID。
类型:字符串。
父节点:Initiator。
StorageClass 文件的存储类型:
STANDARD
STANDARD_IA
类型:字符串。
父节点:Upload。
Initiated 分片上传过程启动的时间。
类型:Date。
父节点:Upload。
Prefix 如果请求中包含了Prefix参数,则这个字段会包含Prefix的值。返回的结果只包含那些key值以Prefix开头的文件。
类型:字符串。
父节点:ListMultipartUploadsResult。
Delimiter 分割符,用来对关键字们进行分组的字符。所有的关键字都包含delimiter和prefix间的相同子串,prefix之后第一个遇到delimiter的字符串都会加到一个叫CommonPrefix的组中。如果没有特别定义prefix,所有的关键字都会被返回,但不会有CommonPrefix。
类型:字符串。
父节点:ListMultipartUploadsResult。
CommonPrefixes 当定义delimiter之后,返回结果中会包含CommonPrefixes,CommonPrefix中包含以prefix开头,delimiter结束的字符串组合,例如prefix是note/,同时delimiter是斜杠(/),结果中的note/summer/july/lotus.jpg将返回note/summer/,其余结果将按照max-uploads要求返回。
类型:容器。
父节点:ListMultipartUploadsResult。
子节点:Prefix。
CommonPrefixes.Prefix 如果请求中不包含Prefix参数,那么这个元素只显示那些在delimiter字符第一次出现之前的key的子字符串,且这些key不在响应的其它位置出现。
如果请求中包含Prefix参数,那么这个元素显示在prefix之后,到第一次出现delimiter之间的子串。
类型:字符串。
父节点:CommonPrefixes。
请求示例
下面的请求列出正在进行的三个分片上传过程。请求指定了max-uploads参数来设置响应中返回的分片上传过程的最大数目。
GET /?uploads&max-uploads=3 HTTP/1.1
Host: example-bucket.oos-cn.ctyunapi.cn
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: SignatureValue
响应示例
下面的示例表示这次List操作无法将分片上传过程列举完,需要指定NextKeyMarker和NextUploadIdMarker元素。用户需要在下一次List操作中指定这两个值。也就是说,在下一次List操作中指定 key-marker =my-image.my(NextKeyMarker的值)和 upload-id-marker =AW56IGBkZQEgd3h6ILVsdmluUydzIWVwbP9hTCAmQZlsQZW(NextUploadIdMarker的值)。
响应示例中也显示了一个两个分片上传过程拥有同一个key(my-image.my)的例子。响应包含了两个通过key来排序的上传过程,在每个key内部上传过程是根据上传启动的起始时间来排序的。
HTTP/1.1 200 OK
x-amz-request-id: eec6eee8e3ff42e305786b7a6f7c7e8443454c393b3d3f4143
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 1359
Server: CTYUN
<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<Bucket>bucket</Bucket>
<KeyMarker></KeyMarker>
<UploadIdMarker></UploadIdMarker>
<NextKeyMarker> my-image.my</NextKeyMarker>
<NextUploadIdMarker>1638428231343309201</NextUploadIdMarker>
<MaxUploads>3</MaxUploads>
<IsTruncated>true</IsTruncated>
<EncodingType></EncodingType>
<Upload>
<Key>my-divisor</Key>
<UploadId>1638428231343309198</UploadId>
<Initiator>
<ID>mailaddress@ctyun.cn</ID>
<DisplayName> </DisplayName>
</Initiator>
<Owner>
<ID></ID>
<DisplayName></DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
<Initiated>2010-11-10T20:48:33.000Z</Initiated>
</Upload>
<Upload>
<Key>my-movie.m2ts</Key>
<UploadId>1638428231343309199</UploadId>
<Initiator>
<ID>mailaddress@ctyun.cn</ID>
<DisplayName> </DisplayName>
</Initiator>
<Owner>
<ID> </ID>
<DisplayName> </DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
<Initiated>2010-11-10T20:48:33.000Z</Initiated>
</Upload>
<Upload>
<Key> my-image.my</Key>
<UploadId>1638428231343309200</UploadId>
<Initiator>
<ID>mailaddress@ctyun.cn</ID>
<DisplayName> </DisplayName>
</Initiator>
<Owner>
<ID> </ID>
<DisplayName> </DisplayName>
</Owner>
<StorageClass>STANDARD</StorageClass>
<Initiated>2010-11-10T20:49:33.000Z</Initiated>
</Upload>
</ListMultipartUploadsResult>