5. 开放接口规范

5.3 关于Bucket的操作

5.3.1 Delete Bucket

Delete Bucket用于删除某个Bucket。

请求语法：

DELETE / HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

细节分析：

1) 如果Bucket不存在，返回404 no content错误。错误码：NoSuchBucket。

2) 为了防止误删除的发生，OSS不允许用户删除一个非空的Bucket。

3) 如果试图删除一个不为空的Bucket，返回409 Conflict错误，错误码：BucketNotEmpty。

4) 只有Bucket的拥有者才能删除这个Bucket。如果试图删除一个没有对应权限的Bucket，返回403 Forbidden错误。错误码：AccessDenied。

请求示例：

DELETE / HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 05:31:04 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:ceOEyZavKY4QcjoUWYSpYbJ3naA=

返回示例：

HTTP/1.1 204 No Content

x-oss-request-id: 7faf664d-0cad-852e-4b38-2ac2232e7e7f

Date: Fri, 24 Feb 2012 05:31:04 GMT

Connection: close

Content-Length: 0

Server: AliyunOSS

相关阅读：

5.3.2 Get Bucket (List Object)

Get Bucket操作可用来list Bucket中所有Object的信息。

请求语法：

GET / HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

请求参数(Request Parameters)：

GetBucket（ListObject）时，可以通过prefix，marker，delimiter和max-keys对list做限定，返回部分结果。

名称	描述
delimiter	是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。数据类型：字符串默认值：无
marker	设定结果从marker之后按字母排序的第一个开始返回。数据类型：字符串默认值：无
max-keys	限定此次返回object的最大数，如果不设定，默认为1000，max-keys取值不能大于1000。数据类型：字符串默认值：100
prefix	限定返回的object key必须以prefix作为前缀。注意使用prefix查询时，返回的key中仍会包含prefix。数据类型：字符串默认值：无

响应元素(Response Elements)

名称	描述
Contents	保存每个返回Object meta的容器。类型：容器父节点：ListBucketResult
CommonPrefixes	如果请求中指定了delimiter参数，则在OSS返回的响应中包含CommonPrefixes元素。该元素标明那些以delimiter结尾，并有共同前缀的object名称的集合。类型：字符串父节点：ListBucketResult
Delimiter	是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。类型：字符串父节点：ListBucketResult
DisplayName	Object 拥有者的名字。类型：字符串父节点：ListBucketResult.Contents.Owner
ETag	ETag (entity tag) 在每个Object生成的时候被创建，用于标示一个Object的内容。对于Put Object请求创建的Object，ETag值是其内容的MD5值；对于其他方式创建的Object，ETag值是其内容的UUID。ETag值可以用于检查Object内容是否发生变化。类型：字符串父节点：ListBucketResult.Contents
ID	Bucket拥有者的用户ID。类型：字符串父节点：ListBucketResult.Contents.Owner
IsTruncated	指明是否所有的结果都已经返回；“true”标示所有结果都已经返回；“false”表示本次请求只返回了部分结果。类型：枚举字符串有效值：true \| false 父节点：ListBucketResult
Key	Object的Key. 类型：字符串父节点：ListBucketResult.Contents
LastModified	Object最后被修改的时间。类型：时间父节点：ListBucketResult.Contents
ListBucketResult	保存Get Bucket请求结果的容器. 类型：容器子节点：Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents 父节点：None
Marker	标明这次Get Bucket（List Object）的起点。类型：字符串父节点：ListBucketResult
MaxKeys	响应请求内返回结果的最大数目。类型：字符串父节点：ListBucketResult
Name	Bucket名字类型：字符串父节点：ListBucketResult
Owner	保存Bucket拥有者信息的容器。类型：容器子节点：DisplayName, ID 父节点：ListBucketResult
Prefix	本次查询结果的开始前缀。类型：字符串父节点：ListBucketResult
Size	Object的字节数。类型：字符串父节点：ListBucketResult.Contents
StorageClass	Object的存储类型，目前只能是“Standard” 类型：字符串父节点：ListBucketResult.Contents

细节分析：

1) Object中用户自定义的meta，在GetBucket请求时不会返回。

2) 如果访问的Bucket不存在，包括试图访问因为命名不规范无法创建的Bucket，返回404 Not Found错误，错误码：NoSuchBucket。

3) 如果没有访问该Bucket的权限，返回403 Forbidden错误，错误码：AccessDenied。

4) 如果因为max-keys的设定无法一次完成listing，返回结果会附加一个<NextMarker>，提示继续listing可以以此为marker。NextMarker中的值仍在list结果之中。

5) 在做条件查询时，即使marker实际在列表中不存在，返回也从符合marker字母排序的下一个开始打印。如果max-keys小于0或者大于1000，将返回400 Bad Request错误。错误码：InvalidArgument。

6) 若prefix，marker，delimiter参数不符合长度要求，返回400 Bad Request。错误码：InvalidArgument。

7) prefix，marker用来实现分页显示效果，参数的长度必须小于1024字节。

8) 如果把prefix设为某个文件夹名，就可以罗列以此prefix开头的文件，即该文件夹下递归的所有的文件和子文件夹。如果再把delimiter设置为 / 时，返回值就只罗列该文件夹下的文件，该文件夹下的子文件名返回在CommonPrefixes部分，子文件夹下递归的文件和文件夹不被显示。如一个bucket存在三个object :

fun/test.jpg， fun/movie/001.avi， fun/movie/007.avi。

若设定prefix为”fun/” ，则返回三个object；如果增加设定delimiter为“/”，则返回文件”fun/test.jpg”和前缀”fun/movie/”；即实现了文件夹的逻辑。

举例场景：

在bucket“my_oss”内有4个object，名字分别为：

l oss.jpg

l fun/test.jpg

l fun/movie/001.avi

l fun/movie/007.avi

请求示例：

GET / HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 08:43:27 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 248c6483-2a95-622e-3022-ebe65d8aad5f

Date: Fri, 24 Feb 2012 08:43:27 GMT

Content-Type: application/xml

Content-Length: 1866

Connection: close

Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>

<Name>oss-example</Name>

<IsTruncated>false</IsTruncated>

<Key>fun/movie/001.avi</Key>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user-example</DisplayName>

</Owner>

</Contents>

<Key>fun/movie/007.avi</Key>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user-example</DisplayName>

</Owner>

</Contents>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user-example</DisplayName>

</Owner>

</Contents>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user-example</DisplayName>

</Owner>

</Contents>

</ListBucketResult>

请求示例(含Prefix参数)：

GET /?prefix=fun HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 08:43:27 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 25cb535f-1feb-1e90-2f22-12176bcb563e

Date: Fri, 24 Feb 2012 08:43:27 GMT

Content-Type: application/xml

Content-Length: 1464

Connection: close

Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>

<Name>oss-example</Name>

<IsTruncated>false</IsTruncated>

<Key>fun/movie/001.avi</Key>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user_example</DisplayName>

</Owner>

</Contents>

<Key>fun/movie/007.avi</Key>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user_example</DisplayName>

</Owner>

</Contents>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user_example</DisplayName>

</Owner>

</Contents>

</ListBucketResult>

请求示例(含prefix和delimiter参数)：

GET /?prefix=fun/&delimiter=/ HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 08:43:27 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 0b05f9b1-539e-a858-0a81-9ca13d8a8011

Date: Fri, 24 Feb 2012 08:43:27 GMT

Content-Type: application/xml

Content-Length: 712

Connection: close

Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>

<Name>oss-example</Name>

<IsTruncated>false</IsTruncated>

<Type>Normal</Type>

<StorageClass>Standard</StorageClass>

<Owner>

<DisplayName>user_example</DisplayName>

</Owner>

</Contents>

<Prefix>fun/movie/</Prefix>

</CommonPrefixes>

</ListBucketResult>

相关阅读：

5.3.3 Get Bucket Acl

Get Bucket ACL用来获取某个Bucket的访问权限。

请求语法：

GET /?acl HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

响应元素(Response Elements)

名称	描述
AccessControlList	存储ACL信息的容器类型：容器父节点：AccessControlPolicy
AccessControlPolicy	保存Get Bucket ACL结果的容器类型：容器父节点：None
DisplayName	Bucket拥有者的名称.。(目前和ID一致) 类型：字符串父节点：AccessControlPolicy.Owner
Grant	Bucket的ACL权限。类型：枚举字符串有效值：private \| public-read \| public-read-write 父节点：AccessControlPolicy.AccessControlList
ID	Bucket拥有者的用户ID 类型：字符串父节点：AccessControlPolicy.Owner
Owner	保存Bucket拥有者信息的容器。类型：容器父节点：AccessControlPolicy

细节分析：

1) 只有Bucket的拥有者才能使用Get Bucket ACL这个接口。

请求示例：

GET /?acl HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 04:11:23 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:CTkuxpLAi4XZ+WwIfNm0FmgbrQ0=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 6f720c98-40fe-6de0-047b-e7fb08c4059b

Date: Fri, 24 Feb 2012 04:11:23 GMT

Content-Length: 253

Content-Tupe: application/xml

Connection: close

Server: AliyunOSS

<?xml version="1.0" ?>

<Owner>

<DisplayName>user_example</DisplayName>

</Owner>

<Grant>public-read</Grant>

</AccessControlList>

</AccessControlPolicy>

相关阅读：

Ø Get Bucket (List Object)

Ø Get Bucket Acl

5.3.4 Put Bucket

PutBucket用于创建Bucket（不支持匿名访问）。

请求语法：

PUT / HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

细节分析：

1) 如果请求的Bucket已经存在，并且请求者是所有者，同样返回200 OK成功。

2) 如果请求的Bucket已经存在，但是不是请求者所拥有的，返回409 Conflict。错误码：BucketAlreadyExists。

3) 如果想创建的Bucket不符合命名规范，返回400 Bad Request消息。错误码：InvalidBucketName。

4) 如果用户发起PUT Bucket请求的时候，没有传入用户验证信息，返回403 Forbidden消息。错误码：AccessDenied。

5) 如果PutBucket的时候发现已经超过bucket最大创建数——10时，返回400 Bad Request消息。错误码：TooManyBuckets。

6) 创建的Bucket，如果没有指定访问权限，则默认使用“Private”权限。

请求示例：

PUT / HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 03:15:40 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:77Dvh5wQgIjWjwO/KyRt8dOPfo8=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 7c9e8b71-3c6a-1b7d-2361-093f1af5f5e9

Date: Fri, 24 Feb 2012 03:15:40 GMT

Location: /oss-example

Content-Length: 0

Connection: close

Server: AliyunOSS

相关阅读：

Ø Delete Bucket

5.3.5 Put Bucket Acl

Put Bucket ACL接口用于修改Bucket访问权限。目前Bucket有三种访问权限：public-read-write，public-read和private。Put Bucket ACL操作通过Put请求中的“x-oss-acl”头来设置。这个操作只有该Bucket的创建者有权限执行。如果操作成功，则返回200；否则返回相应的错误码和提示信息。

请求语法：

PUT / HTTP/1.1

x-oss-acl: Permission

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

细节分析：

1) 如果bucket存在，发送时带的权限和已有权限不一样，并且请求发送者是bucket拥有者时。该请求不会改变bucket内容，但是会更新权限。

2) 如果用户发起Put Bucket请求的时候，没有传入用户验证信息，返回403 Forbidden消息。错误码：AccessDenied。

3) 如果请求中没有，“x-oss-acl”头，并且该bucket已存在，并属于该请求发起者，则维持原bucket权限不变。

请求示例：

PUT / HTTP/1.1

x-oss-acl: public-read

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 03:21:12 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZHiA=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 248c6483-2a95-622e-3022-ebe65d8aad5f

Date: Fri, 24 Feb 2012 03:21:12 GMT

Content-Length: 0

Connection: close

Server: AliyunOSS

如果该设置的权限不存在，示例400 Bad Request消息：

错误返回示例：

HTTP/1.1 400 Bad Request

x-oss-request-id: 4e63c87a-71dc-87f7-11b5-583a600e0038

Date: Fri, 24 Feb 2012 03:55:00 GMT

Content-Length: 309

Content-Type: text/xml; charset=UTF-8

Connection: close

Server: AliyunOSS

<?xml version="1.0" ?>

<Code>

InvalidArgument

</Code>

</Message>

error-acl

</ArgumentValue>

x-oss-acl

</ArgumentName>

4e63c87a-71dc-87f7-11b5-583a600e0038

</RequestId>

oss.aliyuncs.com

</HostId>

</Error>

相关阅读：

Ø Get Bucket Acl

5.4 关于Object操作

5.4.1 Copy Object

拷贝一个在OSS上已经存在的object成另外一个object，可以发送一个PUT请求给OSS，并在PUT请求头中添加元素“x-oss-copy-source”来指定拷贝源。OSS会自动判断出这是一个Copy操作，并直接在服务器端执行该操作。如果拷贝成功，则返回新的object信息给用户。

请求语法：

PUT / /ObjectName HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

x-oss-copy-source: /SourceBucketName/SourceObjectName

请求Header：

名称	描述
x-oss-copy-source	复制源地址（必须有可读权限）类型：字符串默认值：无
x-oss-copy-source-if-match	如果源Object的ETAG值和用户提供的ETAG相等，则执行拷贝操作；否则返回412 HTTP错误码（预处理失败）。类型：字符串默认值：无
x-oss-copy-source-if-none-match	如果源Object自从用户指定的时间以后就没有被修改过，则执行拷贝操作；否则返回412 HTTP错误码（预处理失败）。类型：字符串默认值：无
x-oss-copy-source-if-unmodified-since	如果传入参数中的时间等于或者晚于文件实际修改时间，则正常传输文件，并返回200 OK；否则返回412 precondition failed错误。类型：字符串默认值：无
x-oss-copy-source-if-modified-since	如果源Object自从用户指定的时间以后被修改过，则执行拷贝操作；否则返回412 HTTP错误码（预处理失败）。类型：字符串默认值：无
x-oss-metadata-directive	有效值为COPY和REPLACE。如果该值设为COPY，则新的Object的meta都从源Object复制过来；如果设为REPLACE，则忽视所有源Object的meta值，而采用用户这次请求中指定的meta值；其他值则返回400 HTTP错误码。类型：字符串默认值：COPY 有效值：COPY \| REPLACE

响应元素(Response Elements)：

名称	描述
CopyObjectResult	Copy Object结果类型：字符串默认值：无
ETag	新Object的ETag值。类型：字符串父元素：CopyObjectResult
LastModified	新Object最后更新时间。类型：字符串父元素：CopyObjectResult

细节分析：

1) 可以通过拷贝操作来实现修改已有Object的meta信息。

2) 如果拷贝操作的源Object地址和目标Object地址相同，则无论x-oss-metadata-directive为何值，都会直接替换源Object的meta信息。

3) OSS支持拷贝操作的四个预判断Header任意个同时出现，相应逻辑参见Get Object操作的细节分析。

4) 拷贝操作需要请求者对源Object有读权限。

5) 拷贝操作的计费统计会对源Object所在的Bucket增加一次Get请求次数，并对目标Object所在的Bucket增加一次Put请求次数，以及相应的新增存储空间。

6) 拷贝操作涉及到的请求头，都是以“x-oss-”开头的，所以要加入签名字符串中。

请求示例：

PUT /copy_oss.jpg HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 07:18:48 GMT

x-oss-copy-source: /oss-example/oss.jpg

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A+n0=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 3dfb2597-72a0-b3f7-320f-8b6627a96e68

Content-Type: application/xml

Content-Length: 193

Connection: close

Date: Fri, 24 Feb 2012 07:18:48 GMT

Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>

</CopyObjectResult>

相关阅读：

5.4.2 Delete Object

DeleteObject用于删除某个Object。

请求语法：

DELETE /ObjectName HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

细节分析：

1) DeleteObject要求对该Object要有写权限。

2) 如果要删除的Object不存在，OSS也返回状态码204（ No Content）。

3) 如果Bucket不存在，返回404 Not Found。

请求示例：

DELETE /copy_oss.jpg HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 07:45:28 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:zUglwRPGkbByZxm1+y4eyu+NIUs=

返回示例：

HTTP/1.1 204 NoContent

x-oss-request-id: 1a61ecd1-5de8-4e2e-20b5-c66e135bc379

Date: Fri, 24 Feb 2012 07:45:28 GMT

Content-Length: 0

Connection: close

Server: AliyunOSS

相关阅读：

Ø Delete Multiple Objects

5.4.3 Delete Multiple Objects

Delete Multiple Object操作支持用户通过一个HTTP请求删除同一个Bucket中的多个Object。Delete Multiple Object操作支持一次请求内最多删除1000个Object，并提供两种返回模式：详细(verbose)模式和简单(quiet)模式:

l 详细模式：OSS返回的消息体中会包含每一个删除Object的结果。

l 简单模式：OSS返回的消息体中只包含删除过程中出错的Object结果；如果所有删除都成功的话，则没有消息体。

请求语法：

POST /?delete HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Content-Length: ContentLength

Content-MD5: MD5Value

Authorization: SignatureValue

<?xml version="1.0" encoding="UTF-8"?>

</Object>

…

</Delete>

请求元素(Request Elements)：

名称	描述
Delete	保存Delete Multiple Object请求的容器。类型：容器子节点：一个或多个Object元素，可选的Quiet元素父节点： None.
Key	被删除Object的名字。类型：字符串父节点：Object
Object	保存一个Object信息的容器。类型：容器子节点：key 父节点：Delete.
Quiet	打开“安静”响应模式的开关。类型：枚举字符串有效值：true \| false 默认值：false 父节点：Delete

响应元素(Response Elements)：

名称	描述
Deleted	保存被成功删除的Object的容器。类型：容器子节点：Key 父节点：DeleteResult
DeleteResult	保存Delete Multiple Object请求结果的容器。类型：容器子节点：Deleted 父节点：None
Key	OSS执行删除操作的Object名字。类型：字符串父节点：Deleted

细节分析：

1) Delete Multiple Object请求必须填Content-Length和Content-MD5字段。OSS会根据这些字段验证收到的消息体是正确的，之后才会执行删除操作。

2) 生成Content-MD5字段内容方法：首先将Delete Multiple Object请求内容经过MD5加密后得到一个128位字节数组；再将该字节数组用base64算法编码；最后得到的字符串即是Content-MD5字段内容。

3) Delete Multiple Object请求默认是详细(verbose)模式。

4) 在Delete Multiple Object请求中删除一个不存在的Object，仍然认为是成功的。

5) Delete Multiple Object的消息体最大允许2MB的内容，超过2MB会返回MalformedXML错误码。

6) Delete Multiple Object请求最多允许一次删除1000个Object；超过1000个Object会返回MalformedXML错误码。

请求示例I：

POST /?delete HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Wed, 29 Feb 2012 12:26:16 GMT

Content-Length:151

Content-MD5: fae2e404736a78a0067b62d80b1cc7d8

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:+z3gBfnFAxBcBDgx27Y/jEfbfu8=

<?xml version="1.0" encoding="UTF-8"?>

<Quiet>false</Quiet>

<Key>multipart.data</Key>

</Object>

</Object>

</Object>

</Delete>

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 78320852-7eee-b697-75e1-b6db0f4849e7

Date: Wed, 29 Feb 2012 12:26:16 GMT

Content-Length: 244

Content-Type: application/xml

Connection: close

Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>

<Key>multipart.data</Key>

</Deleted>

</Deleted>

</Deleted>

</DeleteResult>

请求示例II：

POST /?delete HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Wed, 29 Feb 2012 12:33:45 GMT

Content-Length:151

Content-MD5: fae2e404736a78a0067b62d80b1cc7d8

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:WuV0Jks8RyGSNQrBca64kEExJDs=

<?xml version="1.0" encoding="UTF-8"?>

<Key>multipart.data</Key>

</Object>

</Object>

</Object>

</Delete>

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 501ad9bb-1383-771d-0ee9-59a810bd5fde

Date: Wed, 29 Feb 2012 12:33:45 GMT

Content-Length: 0

Connection: close

Server: AliyunOSS

相关阅读：

5.4.4 Get Object

用于获取某个Object，此操作要求用户对该Object有读权限。

请求语法：

GET /ObjectName HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

Range: bytes=ByteRange(可选)

请求参数：

OSS支持用户在发送GET请求时，可以自定义OSS返回请求中的一些Header，这些Header包括：

名称	描述
response-content-type	设置OSS返回请求的content-type头类型：字符串默认值：无
response-content-language	设置OSS返回请求的content-language头类型：字符串默认值：无
response-expires	设置OSS返回请求的expires头类型：字符串默认值：无
response-cache-control	设置OSS返回请求的cache-control头类型：字符串默认值：无
response-content-disposition	设置OSS返回请求的content-disposition头类型：字符串默认值：无
response-content-encoding	设置OSS返回请求的content-encoding头类型：字符串默认值：无

请求Header：

名称	描述
Range	指定文件传输的范围。如，设定 bytes=0-9，表示传送第0到第9这10个字符。类型：字符串默认值：无
If-Modified-Since	如果指定的时间早于实际修改时间，则正常传送文件，并返回200 OK；否则返回304 not modified 类型：字符串默认值：无
If-Unmodified-Since	如果传入参数中的时间等于或者晚于文件实际修改时间，则正常传输文件，并返回200 OK；否则返回412 precondition failed错误类型：字符串默认值：无
If-Match	如果传入期望的ETag和object的 ETag匹配，则正常传输文件，并返回200 OK；否则返回412 precondition failed错误类型：字符串默认值：无
If-None-Match	如果传入的ETag值和Object的ETag不匹配，则正常传输文件,并返回200 OK；否则返回304 Not Modified 类型：字符串默认值：无

细节分析：

1) GetObject通过range参数可以支持断点续传，对于比较大的Object建议使用该功能。

2) 如果在请求头中使用Range参数；则返回消息中会包含整个文件的长度和此次返回的范围，例如：Content-Range: bytes 0-9/44，表示整个文件长度为44，此次返回的范围为0-9。如果不符合范围规范，则传送整个文件，并且不在结果中提及Content-Range。

3) 如果“If-Modified-Since”元素中设定的时间不符合规范，直接返回文件，并返回200 OK。

4) If-Modified-Since和If-Unmodified-Since可以同时存在，If-Match和If-None-Match也可以同时存在。

5) 如果包含If-Unmodified-Since并且不符合或者包含If-Match并且不符合，返回412 precondition failed

6) 如果包含If-Modified-Since并且不符合或者包含If-None-Match并且不符合，返回304 Not Modified

7) 如果文件不存在返回404 Not Found错误。错误码：NoSuchKey。

8) OSS不支持在匿名访问的GET请求中，通过请求参数来自定义返回请求的header。

9) 在自定义OSS返回请求中的一些Header时，只有请求处理成功（即返回码为200时），OSS才会将请求的header设置成用户GET请求参数中指定的值。

请求示例：

GET /oss.jpg HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 06:38:30 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:UNQDb7GapEgJCZkcde6OhZ9Jfe8=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 3a89276f-2e2d-7965-3ff9-51c875b99c41

Date: Fri, 24 Feb 2012 06:38:30 GMT

Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT

ETag: "5B3C1A2E053D763E1B002CC607C5A0FE "

Content-Type: image/jpg

Content-Length: 344606

Server: AliyunOSS

[344606 bytes of object data]

Range请求示例：

GET //oss.jpg HTTP/1.1

Host:oss-example. oss.aliyuncs.com

Date: Fri, 28 Feb 2012 05:38:42 GMT

Range: bytes=100-900

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:qZzjF3DUtd+yK16BdhGtFcCVknM=

返回示例：

HTTP/1.1 206 Partial Content

x-oss-request-id: 28f6508f-15ea-8224-234e-c0ce40734b89

Date: Fri, 28 Feb 2012 05:38:42 GMT

Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT

ETag: "5B3C1A2E053D763E1B002CC607C5A0FE "

Accept-Ranges: bytes

Content-Range: bytes 100-900/344606

Content-Type: image/jpg

Content-Length: 801

Server: AliyunOSS

[801 bytes of object data]

自定义返回消息头的请求示例（URL签名方式）：

GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT& response-content-type=text&response-cache-control=No-cache&response-content-disposition=attachment%253B%2520filename%253Dtesting.txt&response-content-encoding=utf-8&response-content-language=%E4%B8%AD%E6%96%87 HTTP/1.1

Host: oss-example.oss.aliyuncs.com:

Date: Fri, 24 Feb 2012 06:09:48 GMT

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 1144d124-055c-4052-2c65-a1e3439d41c1

Date: Fri, 24 Feb 2012 06:09:48 GMT

Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT

ETag: "5B3C1A2E053D763E1B002CC607C5A0FE "

Content-Length: 344606

Connection: close

Content-disposition: attachment; filename:testing.txt

Content-language: 中文

Content-encoding: utf-8

Content-type: text

Cache-control: no-cache

Expires: Fri, 24 Feb 2012 17:00:00 GMT

Server: AliyunOSS

[344606 bytes of object data]

相关阅读：

5.4.5 Head Object

Head Object只返回某个Object的meta信息，不返回文件内容。

请求语法：

HEAD /ObjectName HTTP/1.1

Host: BucketName/oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

请求Header：

名称	描述
If-Modified-Since	如果指定的时间早于实际修改时间，则返回200 OK和Object Meta；否则返回304 not modified 类型：字符串默认值：无
If-Unmodified-Since	如果传入参数中的时间等于或者晚于文件实际修改时间，则返回200 OK和Object Meta；否则返回412 precondition failed错误类型：字符串默认值：无
If-Match	如果传入期望的ETag和object的 ETag匹配，则返回200 OK和Object Meta；否则返回412 precondition failed错误类型：字符串默认值：无
If-None-Match	如果传入的ETag值和Object的ETag不匹配，则返回200 OK和Object Meta；否则返回304 Not Modified 类型：字符串默认值：无

细节分析：

1) 不论正常返回200 OK还是非正常返回，Head Object都不返回消息体。

2) HeadObject支持在头中设定If-Modified-Since, If-Unmodified-Since, If-Match，If-None-Match的查询条件。具体规则请参见GetObject中对应的选项。如果没有修改，返回304 Not Modified。

3) 如果用户在PutObject的时候传入以x-oss-meta-为开头的user meta，比如x-oss-meta-location，返回消息时，返回这些user meta。

4) 如果文件不存在返回404 Not Found错误。

请求示例：

HEAD /oss.jpg HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Fri, 24 Feb 2012 07:32:52 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JbzF2LxZUtanlJ5dLA092wpDC/E=

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 06d4be30-2216-9264-757a-8f8b19b254bb

Date: Fri, 24 Feb 2012 07:32:52 GMT

Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT

ETag: "fba9dede5f27731c9771645a39863328"

Content-Length: 344606

Content-Type: image/jpg

Connection: close

Server: AliyunOSS

相关阅读：

5.4.6 Put Object

Put Object用于上传文件。

请求语法：

PUT /ObjectName HTTP/1.1

Content-Length：ContentLength

Content-Type: ContentType

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

请求Header：

名称	描述
Cache-Control	指定该Object被下载时的网页的缓存行为；更详细描述请参照RFC2616。类型：字符串默认值：无
Content-Disposition	指定该Object被下载时的名称；更详细描述请参照RFC2616。类型：字符串默认值：无
Content-Encoding	指定该Object被下载时的内容编码格式；更详细描述请参照RFC2616。类型：字符串默认值：无
Expires	过期时间（milliseconds）；更详细描述请参照RFC2616。类型：整数默认值：无

细节分析：

1) Put Object请求处理成功后，OSS会将收到文件的MD5值放在返回给用户的请求头“ETag”中，以便用户检查OSS上的数据和要上传的数据内容一致。

2) 如果请求头中的“Content-Length”值小于实际请求体（body）中传输的数据长度，OSS仍将成功创建文件；但Object大小只等于“Content-Length”中定义的大小，其他数据将被丢弃。

3) 如果试图添加的Object的同名文件已经存在，并且有访问权限。新添加的文件将覆盖原来的文件，成功返回200 OK。

4) 如果在PutObject的时候，携带以x-oss-meta-为前缀的参数，则视为user meta，比如x-oss-meta-location。一个Object可以有多个类似的参数，但所有的user meta总大小不能超过2k。

5) 如果Head中没有加入Content length参数，会返回411 Length Required错误。错误码：MissingContentLength。

6) 如果设定了长度，但是没有发送消息Body，或者发送的body大小小于给定大小，服务器会一直等待，直到time out，返回400 Bad Request消息。错误码：RequestTimeout。此时OSS上的这个文件内容是用户已经上传完的数据。

7) 如果试图添加的Object所在的Bucket不存在，返回404 Not Found错误。错误码：NoSuchBucket。

8) 如果试图添加的Object所在的Bucket没有访问权限，返回403 Forbidden错误。错误码：AccessDenied。

9) 如果添加文件长度超过5G，返回错误消息400 Bad Request。错误码：InvalidArgument。

10) 如果传入的Object key长度大于1023，返回400 Bad Request。错误码：InvalidObjectName。

11) PUT一个Object的时候，OSS支持4个 HTTP RFC 2616协议规定的Header 字段：Cache-Control、Expires、Content-Encoding、Content-Disposition。如果上传Object时设置了这些Header，则这个Object被下载时，相应的Header值会被自动设置成上传时的值。

请求示例：

PUT /oss.jpg HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Cache-control: no-cache

Expires: Fri, 28 Feb 2012 05:38:42 GMT

Content-Encoding: utf-8

Content-Disposition: attachment;filename=oss_download.jpg

Date: Fri, 24 Feb 2012 06:03:28 GMT

Content-Type: image/jpg

Content-Length: 344606

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:kZoYNv66bsmc10+dcGKw5x2PRrk=

[344606 bytes of object data]

返回示例：

HTTP/1.1 200 OK

x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e

Date: Fri, 24 Feb 2012 06:03:28 GMT

ETag: 5B3C1A2E053D763E1B002CC607C5A0FE

Connection: close

Content-Length: 0

Server: AliyunOSS

相关阅读：

Ø Complete Multipart Upload

5.5 关于Multipart Upload的操作

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

l 需要支持断点上传。

l 上传超过100MB大小的文件。

l 网络条件较差，和OSS的服务器之间的链接经常断开。

l 需要流式地上传文件。

l 上传文件之前，无法确定上传文件的大小。

5.5.1 Initiate Multipart Upload

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

请求语法：

POST /ObjectName?uploads HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT date

Authorization: SignatureValue

请求Header：

名称	描述
Cache-Control	指定该Object被下载时的网页的缓存行为；更详细描述请参照RFC2616。类型：字符串默认值：无
Content-Disposition	指定该Object被下载时的名称；更详细描述请参照RFC2616。类型：字符串默认值：无
Content-Encoding	指定该Object被下载时的内容编码格式；更详细描述请参照RFC2616。类型：字符串默认值：无
Expires	过期时间（milliseconds）；更详细描述请参照RFC2616。类型：整数默认值：无

响应元素(Response Elements)：

名称	描述
Bucket	初始化一个Multipart Upload事件的Bucket名称。类型：字符串父节点：InitiateMultipartUploadResult
InitiateMultipartUploadResult	保存Initiate Multipart Upload请求结果的容器。类型：容器子节点：Bucket, Key, UploadId 父节点：None
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-oss-meta-”开头的用户自定义Headers。具体含义请参见PUT Object接口。

3) 初始化Multipart Upload请求，并不会影响已经存在的同名object。

4) 服务器收到初始化Multipart Upload请求后，会返回一个XML格式的请求体。该请求体内有三个元素：Bucket，Key和UploadID。请记录下其中的UploadID，以用于后续的Multipart相关操作。

请求示例：

POST /multipart.data?uploads HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Wed, 22 Feb 2012 08:32:21 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:/cluRFtRwMTZpC2hTj4F67AGdM4=

返回示例：

HTTP/1.1 200 OK

Content-Length: 230

Server: AliyunOSS

Connection: close

x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eaec618

Date: Wed, 22 Feb 2012 08:32:21 GMT

Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<Bucket> multipart_upload</Bucket>

<Key>multipart.data</Key>

</InitiateMultipartUploadResult>

相关阅读：

Ø List Multipart Uploads

Ø Abort Multipart Upload

5.5.2 Upload Part

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

请求语法：

PUT /ObjectName? partNumber=PartNumber&uploadid=UploadId HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Content-Length: Size

Authorization: SignatureValue

细节分析：

1) 调用该接口上传Part数据前，必须调用Initiate Multipart Upload接口，获取一个OSS服务器颁发的Upload ID。

2) Multipart Upload要求除最后一个Part以外，其他的Part大小都要大于5MB。但是Upload Part接口并不会立即校验上传Part的大小（因为不知道是否为最后一块）；只有当Complete Multipart Upload的时候才会校验。

3) OSS会将服务器端收到Part数据的MD5值放在ETag头内返回给用户。为了保证数据在网络传输过程中不出现错误，强烈推荐用户在收到OSS的返回请求后，用该MD5值验证上传数据的正确性。

4) Part号码的范围是1~10000。如果超出这个范围，OSS将返回InvalidArgument的错误码。

请求示例:

PUT /multipart.data?partNumber=1&uploadId=0004B9895DBBB6EC98E36 HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Content-Length：6291456

Date: Wed, 22 Feb 2012 08:32:21 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:J/lICfXEvPmmSW86bBAfMmUmWjI=

[6291456 bytes data]

返回示例:

HTTP/1.1 200 OK

Server: AliyunOSS

Connection: close

ETag: 7265F4D211B56873A381D321F586E4A9

x-oss-request-id: 3e6aba62-1eae-d246-6118-8ff42cd0c21a

Date: Wed, 22 Feb 2012 08:32:21 GMT

相关阅读：

Ø Complete Multipart Upload

Ø List Parts

5.5.3 Complete Multipart Upload

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

请求语法：

POST /ObjectName?uploadId=UploadId HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Content-Length: Size

Authorization: Signature

<Part>

<PartNumber>PartNumber</PartNumber>

</Part>

...

</CompleteMultipartUpload>

请求元素(Request Elements)：

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

响应元素(Response Elements)：

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

细节分析：

1) Complete Multipart Upload时，会确认除最后一块以外所有块的大小都大于5MB，并检查用户提交的Partlist中的每一个Part号码和Etag。所以在上传Part时，客户端除了需要记录Part号码外，还需要记录每次上传Part成功后，服务器返回的ETag值。

2) OSS处理Complete Multipart Upload请求时，会持续一定的时间。在这段时间内，如果客户端和OSS之间的链接断掉，OSS仍会继续将请求做完。

3) 用户提交的Part List中,Part号码可以是不连续的。例如第一块的Part号码是1；第二块的Part号码是5。

4) OSS处理Complete Multipart Upload请求成功后，该Upload ID就会变成无效。

5) 同一个Object可以同时拥有不同的Upload Id，当Complete一个Upload ID后，该Object的其他Upload ID不受影响。

请求示例:

POST /multipart.data? uploadId=0004B9B2D2F7815C432C9057C03134D4 HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Content-Length: 1056

Date: Fri, 24 Feb 2012 10:19:18 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:8VwFhFUWmVecK6jQlHlXMK/zMT0=

<Part>

</Part>

<Part>

</Part>

<Part>

</Part>

</CompleteMultipartUpload>

返回示例:

HTTP/1.1 200 OK

Server: AliyunOSS

Content-Length: 329

Content-Type: Application/xml

Connection: close

x-oss-request-id: 594f0751-3b1e-168f-4501-4ac71d217d6e

Date: Fri, 24 Feb 2012 10:19:18 GMT

<?xml version="1.0" encoding="UTF-8"?>

<Location>http://storage.aliyun-inc.com/multipart_upload/multipart.data</Location>

<Bucket>multipart_upload</Bucket>

<Key>multipart.data</Key>

</CompleteMultipartUploadResult>

相关阅读：

Ø List Parts

5.5.4 Abort Multipart Upload

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

请求语法：

DELETE /ObjectName?uploadId=UploadId HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: Signature

细节分析：

1) 中止一个Multipart Upload事件时，如果其所属的某些Part仍然在上传，那么这次中止操作将无法删除这些Part。所以如果存在并发访问的情况，为了彻底释放OSS上的空间，需要调用几次Abort Multipart Upload接口。

2) 如果输入的Upload Id不存在，OSS会返回404错误，错误码为：NoSuchUpload。

请求示例:

Delete /multipart.data?partNumber=1&uploadId=0004B9895DBBB6EC98E HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Wed, 22 Feb 2012 08:32:21 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:J/lICfXEvPmmSW86bBAfMmUmWjI=

返回示例:

HTTP/1.1 204

Server: AliyunOSS

Connection: close

x-oss-request-id: 059a22ba-6ba9-daed-5f3a-e48027df344d

Date: Wed, 22 Feb 2012 08:32:21 GMT

相关阅读：

Ø List Multipart Uploads

5.5.5 List Multipart Uploads

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

请求语法：

Get /?uploads HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: Signature

请求参数：

名称	描述
delimiter	是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。类型：字符串
max-uploads	限定此次返回Multipart Uploads事件的最大数目，如果不设定，默认为1000，max-keys取值不能大于1000。类型：字符串
key-marker	与upload-id-marker参数一同使用来指定返回结果的起始位置。 l 如果upload-id-marker参数未设置，查询结果中包含：所有Object名字的字典序大于key-marker参数值的Multipart事件。 l 如果upload-id-marker参数被设置，查询结果中包含：所有Object名字的字典序大于key-marker参数值的Multipart事件和Object名字等于key-marker参数值，但是Upload ID比upload-id-marker参数值大的Multipart Uploads事件。类型：字符串
prefix	限定返回的object key必须以prefix作为前缀。注意使用prefix查询时，返回的key中仍会包含prefix。类型：字符串
upload-id-marker	与key-marker参数一同使用来指定返回结果的起始位置。 l 如果key-marker参数未设置，则OSS忽略upload-id-marker参数。 l 如果key-marker参数被设置，查询结果中包含：所有Object名字的字典序大于key-marker参数值的Multipart事件和Object名字等于key-marker参数值，但是Upload ID比upload-id-marker参数值大的Multipart Uploads事件。类型：字符串

响应元素(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
IsTruncated	标明是否本次返回的Multipart Upload结果列表被截断。“true”表示本次没有返回全部结果；“false”表示本次已经返回了全部结果。类型：枚举字符串有效值：false \| true 默认值：false 父节点：ListMultipartUploadsResult
Upload	保存Multipart Upload事件信息的容器。类型：容器子节点：Key, UploadId, Initiated 父节点：ListMultipartUploadsResult
Key	初始化Multipart Upload事件的Object名字。类型：字符串父节点：Upload
UploadId	Multipart Upload事件的ID。类型：字符串父节点：Upload
Initiated	Multipart Upload事件初始化的时间. 类型：日期父节点：Upload

细节分析：

1) “max-uploads”参数最大值为1000。

2) 在OSS的返回结果首先按照Object名字字典序升序排列；对于同一个Object，则按照时间序，升序排列。

3) 可以灵活地使用prefix参数对bucket内的object进行分组管理（类似与文件夹的功能）。

4) List Multipart Uploads请求支持5种请求参数： prefix，marker，delimiter，upload-id-marker和max-keys。通过这些参数的组合，可以设定查询Multipart Uploads事件的规则，获得期望的查询结果。

请求示例:

Get /?uploads HTTP/1.1

Host:oss-example. oss.aliyuncs.com

Date: Thu, 23 Feb 2012 06:14:27 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:JX75CtQqsmBBz+dcivn7kwBMvOY=

返回示例:

HTTP/1.1 200

Server: AliyunOSS

Connection: close

Content-length: 1839

Content-type: application/xml

x-oss-request-id: 58a41847-3d93-1905-20db-ba6f561ce67a

Date: Thu, 23 Feb 2012 06:14:27 GMT

<?xml version="1.0" encoding="UTF-8"?>

<Bucket>oss-example</Bucket>

<IsTruncated>false</IsTruncated>

<Key>multipart.data</Key>

</Upload>

<Key>multipart.data</Key>

</Upload>

</Upload>

</ListMultipartUploadsResult>

相关阅读：

Ø List Parts

5.5.6 List Parts

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

请求语法：

Get /ObjectName?uploadId=UploadId HTTP/1.1

Host: BucketName.oss.aliyuncs.com

Date: GMT Date

Authorization: Signature

请求参数(Request Parameters)：

名称	描述
uploadId	Multipart Upload事件的ID。类型：字符串默认值：无
max-parts	规定在OSS响应中的最大Part数目。类型：整数默认值：1,000
part-number-marker	指定List的起始位置，只有Part Number数目大于该参数的Part会被列出。类型：整数默认值：无

名称	描述
uploadId	Upload ID identifying the multipart upload whose parts are being listed. Type: String Default: None
max-parts	Sets the maximum number of parts to return in the response body. Type: Integer Default: 1,000
part-number-marker	Specifies the part after which listing should begin. Only parts with higher part numbers will be listed. Type: Integer Default: None

响应元素(Response Elements)：

名称	描述
ListPartsResult	保存List Part请求结果的容器。类型：容器子节点：Bucket, Key, UploadId, PartNumberMarker, NextPartNumberMarker, MaxParts, IsTruncated, Part 父节点：无
Bucket	Bucket名称。类型：字符串父节点：ListPartsResult
Key	Object名称。类型：字符串父节点：ListPartsResult
UploadId	Upload事件ID。类型：字符串父节点：ListPartsResult
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) 在OSS的返回结果按照Part号码升序排列。

4) 由于网络传输可能出错，所以不推荐用List Part出来的结果（Part Number和ETag值）来生成最后Complete Multipart的Part列表。

请求示例:

Get /multipart.data?uploadId=0004B999EF5A239BB9138C6227D69F95 HTTP/1.1

Host: oss-example.oss.aliyuncs.com

Date: Thu, 23 Feb 2012 07:13:28 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:4qOnUMc9UQWqkz8wDqD3lIsa9P8=

返回示例:

HTTP/1.1 200

Server: AliyunOSS

Connection: close

Content-length: 1221

Content-type: application/xml

x-oss-request-id: 106452c8-10ff-812d-736e-c865294afc1c

Date: Thu, 23 Feb 2012 07:13:28 GMT

<?xml version="1.0" encoding="UTF-8"?>

<Bucket>multipart_upload</Bucket>

<Key>multipart.data</Key>

<IsTruncated>false</IsTruncated>

<Part>

</Part>

<Part>

</Part>

<Part>

</Part>

</ListPartsResult>

相关阅读：