. 3

1.     阿里云存储服务简介. 4

2.     基本概念. 5

2.1         Object 5

2.2         Bucket 5

2.3         Access Key IDAccess Key Secret 5

2.4         Service. 6

3.     OSS功能简介. 7

3.1         OSS基本功能... 7

3.2         Object外链地址的构成规则... 7

3.3         OSS防盗链... 8

3.4         自定义域名绑定(CNAME... 8

3.5         访问日志记录(Server Access Logging) 9

4.     访问控制. 13

4.1         用户签名验证(Authentication... 13

4.2         Head中包含签名... 13

4.3         URL中包含签名... 18

4.4         Bucket权限控制... 19

5.     开放接口规范. 21

5.1         公共HTTP头定义... 22

5.1.1             公共请求头(Common Request Headers... 22

5.1.2             公共响应头(Common Response Headers... 23

5.2         关于Service的操作... 24

5.2.1             GetService (ListBucket) 24

5.3         关于Bucket的操作... 27

5.3.1             Delete Bucket 27

5.3.2             Get Bucket (List Object) 29

5.3.3             Get Bucket Acl 37

5.3.4             Put Bucket 39

5.3.5             Put Bucket Acl 41

5.4         关于Object操作... 43

5.4.1             Copy Object 43

5.4.2             Delete Object 46

5.4.3             Delete Multiple Objects. 47

5.4.4             Get Object 51

5.4.5             Head Object 55

5.4.6             Put Object 57

5.5         关于Multipart Upload的操作... 60

5.5.1             Initiate Multipart Upload. 60

5.5.2             Upload Part 63

5.5.3             Complete Multipart Upload. 65

5.5.4             Abort Multipart Upload. 69

5.5.5             List Multipart Uploads. 70

5.5.6             List Parts. 74

6.     OSS的错误响应. 78

6.1.        OSS的错误响应格式... 78

6.2.        OSS的错误码... 79

6.3.        OSS不支持分块传输编码... 81

6.4.        OSS不支持的操作... 82

6.5.        OSS操作支持但参数不支持的操作... 84

 


 

本文档是阿里云存储服务(OSS)的开发帮助指南,描述了OSS中的基本概念、提供的服务以及可用的API


 

1. 阿里云存储服务简介

阿里云存储服务(OpenStorageService,简称OSS),是阿里云对外提供的海量,安全,低成本,高可靠的云存储服务。用户可以通过简单的REST接口,在任何时间、任何地点、任何互联网设备上进行上传和下载数据,也可以使用WEB页面对数据进行管理。同时,OSS提供Java Python PHPC#语言的SDK,简化用户的编程。基于OSS,用户可以搭建出各种多媒体分享网站、网盘、个人和企业数据备份等基于大规模数据的服务。

公网的OSS访问地址: http://oss.aliyuncs.com

阿里云主机的内网OSS访问地址[1]http://oss-internal.aliyuncs.com

OSSweb控制台地址:http://oss.aliyun.com/

 


 

2. 基本概念

2.1          Object

OSS中,用户操作的基本数据单元是Object。单个Object最大允许存储5TB的数据。Object包含keymetadata。其中,keyObject的名字;meta是用户对该object的描述,由一系列name-value对组成;dataObject的数据。

n  Object命名规范

Ø  使用UTF-8编码

Ø  长度必须在1-1023字节之间

Ø  不能以“/”或者“\”字符开头

2.2          Bucket

BucketOSS上的命名空间,也是计费、权限控制、日志记录等高级功能的管理实体;Bucket名称在整个OSS服务中具有全局唯一性,且不能修改;存储在OSS上的每个Object必须都包含在某个Bucket中。一个应用,例如图片分享网站,可以对应一个或多个Bucket。一个用户最多可创建10Bucket,但每个Bucket中存放的Object的数量和大小总和没有限制,用户不需要考虑数据的可扩展性。

n  Bucket命名规范

Ø  只能包括小写字母,数字,短横线(-

Ø  必须以小写字母或者数字开头

Ø  长度必须在3-63字节之间

 

2.3          Access Key IDAccess Key Secret

用户注册OSS时,系统会给用户分配一对Access Key IDAccess Key Secret,称为ID对,用于标识用户,为访问OSS做签名验证。

2.4          Service

OSS提供给用户的虚拟存储空间,在这个虚拟空间中,每个用户可拥有一个到多个Bucket


 

3. OSS功能简介

 

3.1          OSS基本功能

OSS为用户提供数据存储服务,用户可以通过以下操作来处理OSS上的数据:

n  创建、查看、罗列、删除 Bucket

n  修改、获取Bucket的访问权限

n  上传、查看、罗列、删除、批量删除Object

n  对于大文件支持分片上传(Multi-Part Upload

n  访问时支持If-Modified-SinceIf-MatchHTTP参数

 

3.2          Object外链地址的构成规则

如果一个bucket设置成公开读权限(详见下一章:访问控制),意味着你允许其他用户来访问属于你的object。你的object的外链地址构成规则如下:

http:// <你的bucket名字>.oss.aliyuncs.com/<你的object名字>

例如,在一个名为oss-examplebucket中,有一个名为"aliyun-log.png"objectcontent-typeimage/png)。那么这个object的外链URL为:

http://oss-example.oss.aliyuncs.com//image/aliyun-logo.png

构成规则的示意图如下:

 用户可以直接该URL链接放入HTML中使用:

<img src="http://oss-example.oss.aliyuncs.com/aliyun-logo.png"/>

 

3.3          OSS防盗链

OSS是按使用收费的服务,为了防止用户在OSS上的数据被其他人盗链,OSS支持基于HTTP header中表头字段referer的防盗链方法。目前,只有通过OSS的控制台(http://oss.aliyun.com)可以对一个bucket设置referer字段的白名单和是否允许referer字段为空的请求访问。例如,对于一个名为oss-examplebucket,设置其referer白名单为http://www.aliyun.com。则所有refererhttp://www.aliyun.com的请求才能访问oss-example这个bucket中的Object

 

细节分析:

1)        用户只有通过URL签名或者匿名访问Object时,才会做防盗链验证。请求的Header中有“Authorization”字段的,不会做防盗链验证。

2)        一个bucket可以支持多个referer参数,这些参数之间由“,”号分隔。

3)        Referer参数支持通配符“*”和“?”。

4)        用户可以设置是否允许referer字段为空的请求访问。

5)        白名单为空时,不会检查referer字段是否为空(不然所有的请求都会被拒绝)。

6)        白名单不为空,且设置了不允许referer字段为空的规则;则只有referer属于白名单的请求被允许,其他请求(包括referer为空的请求)会被拒绝。

7)        如果白名单不为空,但设置了允许referer字段为空的规则;则referer为空的请求和符合白名单的请求会被允许;其他请求都会被拒绝。

8)        Bucket的三种权限(privatepublic-readpublic-read-write)都会检查referer字段。

 

注意:OSS更多的防盗链的规则正在开发中。

3.4          自定义域名绑定(CNAME

OSS支持用户将自定义的域名绑定在属于自己的bucket上面,这个操作必须通过OSS控制台(http://oss.aliyun.com)来实现。按照中国《互联网管理条例》的要求,所有需要开通这项功能的用户,必须提供阿里云备案号,域名持有者身份证等有效资料,经由阿里云审批通过后才可以使用。在开通CNAME功能后,OSS将自动处理对该域名的访问请求。

 

CNAME应用场景例子:

Ø  用户A拥有一个域名为abc.com的网站;这个网站的所有图片存储在img.abc.com这个子域名下;

Ø  为了应对日益增长的图片流量压力,用户AOSS上创建了一个名为abc-imgbucket,并将所有图片存在OSS上;

Ø  通过OSS控制台,提交将img.abc.com CNAME abc-img.oss.aliyuncs.com的申请,并提供相应的材料

Ø  通过阿里云审核后,在自己的域名服务器上,添加一条CNAME规则,将img.abc.com映射成abc-img.oss.aliyuncs.com,这样所有对img.abc.com的访问都将变成访问abc-img这个bucket。例如:一个对http://img.abc.com/logo.png的访问,实际上访问的是http://abc-img.oss.aliyuncs.com/logo.png

 

3.5          访问日志记录[2](Server Access Logging)

OSS为用户提供自动保存访问日志记录功能。Bucket的拥有者可以通过OSS控制台(http://oss.aliyun.com),为其所拥有的bucket开启访问日志记录功能。当一个bucket(源BucketSource Bucket)开启访问日志记录功能后,OSS自动将访问这个bucket的请求日志,以小时为单位,按照固定的命名规则,生成一个Object写入用户指定的bucket(目标BucketTarget Bucket)。

 

存储访问日志记录的object命名规则:

<TargetPrefix><SourceBucket>-YYYY-mm-DD-HH-MM-SS-UniqueString

命名规则中,TargetPrefix由用户指定;YYYY, mm, DD, HH, MMSS分别是该Object被创建时的阿拉伯数字的年,月,日,小时,分钟和秒(注意位数);UniqueStringOSS系统生成的字符串。一个实际的用于存储OSS访问日志的Object名称例子如下:

MyLog-oss-example-2012-09-10-04-00-00-0000

上例中,“MyLog-”是用户指定的Object前缀;“oss-example”是源bucket的名称;“2012-09-10-04-00-00”是该Object被创建时的北京时间;“0000 OSS系统生成的字符串。

 

LOG文件格式(从左至右,以空格分隔):

Remote IP

119.140.142.11

请求发起的IP地址(Proxy代理或用户防火墙可能会屏蔽该字段)

Reserved

-

保留字段

Reserved

-

保留字段

Time

[02/May/2012:00:00:04 +0800]

OSS收到请求的时间

Request-URI

“GET /aliyun-logo.png HTTP/1.1“

用户请求的URI(包括query-string)

HTTP Status

200

OSS返回的HTTP状态码

SentBytes

5576

用户从OSS下载的流量

RequestTime (ms)

71

完成本次请求的时间(毫秒)

Referrer

http://oss.aliyun.com

请求的HTTP Referrer

User-Agent

curl/7.15.5

HTTPUser-Agent

HostName

oss-example.oss.aliyuncs.com

请求访问域名

Request ID

505B01695037C2AF032593A4

用于唯一标示该请求的UUID

LoggingFlag

true

是否开启了访问日志功能

Reserved

-

保留字段

Requester Aliyun ID

1657136103983691

请求者的阿里云ID;匿名访问为“-

Operation

GetObject

请求类型

Bucket

oss-example

请求访问的Bucket名字

Key

/aliyun-logo.png

用户请求的Key

ObjectSize

5576

Object大小

Server Cost Time (ms)

17

OSS服务器处理本次请求所花的时间(毫秒)

Error Code

NoSuchBucket

OSS返回的错误码

UserID

1657136103983691

Bucket拥有者ID

Delta DataSize

280

Bucket大小的变化量;若没有变化为“-

 

细节分析:

1)  Bucket和目标Bucket必须属于同一个用户。

2)  TargetPrefix表示存储访问日志记录的object名字前缀,可以为空。

3)  bucket和目标bucket可以是同一个Bucket,也可以是不同的Bucket;用户也可以将多个的bucketLOG都保存在同一个目标bucket内(建议指定不同的TargetPrefix)。

4)  OSS以小时为单位生成bucket访问的Log文件,但并不表示这个小时的所有请求都记录在这个小时的LOG文件内,也有可能出现在上一个或者下一个LOG文件中。

5)  OSS生成的Log文件命名规则中的“UniqueString”仅仅是OSS为其生成的UUID,用于唯一标识该文件。

6)  OSS生成一个bucket访问的Log文件,算作一次PUT操作,并记录其占用的空间,但不会记录产生的流量。LOG生成后,用户可以按照普通的Object来操作这些LOG文件。

7)  OSS会忽略掉所有以“x-”开头的query-string参数,但这个query-string会被记录在访问LOG中。如果你想从海量的访问日志中,标示一个特殊的请求,可以在URL中添加一个“x-”开头的query-string参数。如:

http://oss-example.oss.aliyuncs.com/aliyun-logo.png

http://oss-example.oss.aliyuncs.com/aliyun-logo.png?x-user=admin

OSS处理上面两个请求,结果是一样的。但是在访问LOG中,你可以通过搜索“x-user=admin”,很方便地定位出经过标记的这个请求。

8)  OSSLOG中的任何一个字段,都可能出现“-”,用于表示未知数据或对于当前请求该字段无效。

9)  根据需求,OSSLOG格式将来会在尾部添加一些字段,请开发者开发Log处理工具时考虑兼容性的问题。

 


 

4.  访问控制

4.1          用户签名验证(Authentication

OSS通过使用Access Key ID/ Access Key Secret对称加密的方法来验证某个请求的发送者身份。Access Key ID用于标示用户,Access Key Secret是用户用于加密签名字符串和OSS用来验证签名字符串的密钥,其中Access Key Secret必须保密,只有用户和OSS知道。每个ACCESS Key对(Access Key IDAccess Key Secret)都有active/inactive两种状态。

n  active表明用户可以用此ID对签名验证请求

n  inactive表明用户暂停此ID对签名验证的功能

一个用户可以同时拥有02active或者inactiveID对。用户可以登录http://oss.aliyun.com/,在OSS管理控制台申请新增或删除ID对。

当用户想以个人身份向OSS发送请求时,需要首先将发送的请求按照OSS指定的格式生成签名字符串;然后使用Access Key Secret对签名字符串进行加密产生验证码。 OSS收到请求以后,会通过Access Key ID找到对应的Access Key Secret,以同样的方法提取签名字符串和验证码,如果计算出来的验证码和提供的一样即认为该请求是有效的;否则,OSS将拒绝处理这次请求,并返回HTTP 403错误。

4.2          Head中包含签名

用户可以在HTTP请求中增加Authorization(授权)的Head来包含签名(Signature)信息,表明这个消息已被授权。

 

Authorization字段计算方法如下:

"Authorization: OSS " + Access Key ID + ":" + Signature

 

Signature = base64(hmac-sha1(VERB + "\n"

                    + CONTENT-MD5 + "\n"

                    + CONTENT-TYPE + "\n"

                    + DATE + "\n"

                    + CanonicalizedOSSHeaders

                    + CanonicalizedResource))

n   CONTENT-MD5表示请求内容数据的MD5

n   CONTENT-TYPE表示请求内容的类型

n   DATE表示此次操作的时间,且必须为HTTP1.1中支持的GMT格式

n   CanonicalizedOSSHeaders表示 http中的object meta组合

n   CanonicalizedResource 表示用户想要访问的OSS资源

其中,DATECanonicalizedResource不能为空;如果请求中的DATE时间和OSS服务器的时间差正负15分钟以上,OSS服务器将拒绝该服务,并返回HTTP 403错误。

 

构建CanonicalizedOSSHeaders的方法:

所有以“x-oss-”为前缀的HTTP Header被称为CanonicalizedOSSHeaders。它的构建方法如下:

1)         将所有以“x-oss-”为前缀的HTTP请求头的名字转换成小写字母。如’X-OSS-Meta-Name: TaoBao’转换成’x-oss-meta-name: TaoBao’

2)         将上一步得到的所有HTTP请求头按照字典序进行升序排列。

3)         如果有相同名字的请求头,则根据标准RFC 2616, 4.2章进行合并(两个值之间只用逗号分隔)。如有两个名为’x-oss-meta-name’的请求头,对应的值分别为’TaoBao’’Alipay’,则合并后为:’x-oss-meta-name:TaoBao,Alipay’

4)         删除请求头和内容之间分隔符两端出现的任何空格。如’x-oss-meta-name: TaoBao,Alipay’转换成:’x-oss-meta-name:TaoBao,Alipay’

5)         将所有的头和内容用’\n’分隔符分隔拼成最后的CanonicalizedOSSHeader

 

构建CanonicalizedResource的方法:

   用户发送请求中想访问的OSS目标资源被称为CanonicalizedResource。它的构建方法如下:

1)         CanonicalizedResource置成空字符串(“”);

2)         放入要访问的OSS资源:“ /BucketName/ObjectName”(无ObjectName则不填)

3)         如果请求的资源包括子资源(sub-resource)[3],那么将所有的子资源按照字典序,从小到大排列并以’&’为分隔符生成子资源字符串。在CanonicalizedResource字符串尾添加“?”和子资源字符串。此时的CanonicalizedResource例子如:/BucketName/ObjectName?acl &uploadId=UploadId

4)         如果用户请求在查询字符串(query string)中指定了要重写(override)返回请求的header[4],那么将这些查询字符串及其请求值按照字典序,从小到大排列,以’&’为分隔符,按参数的字典序添加到CanonicalizedResource中。此时的CanonicalizedResource例子:

/BucketName/ObjectName?acl&response-content-type=ContentType & uploadId =UploadId

 

例如:想签名以下信息:

PUT /nelson HTTP/1.0

Content-Md5: c8fdb181845a4ca6b8fec737b3581d76

Content-Type: text/html

Date: Thu, 17 Nov 2005 18:49:58 GMT

Host: oss-example.oss.aliyuncs.com

X-OSS-Meta-Author: foo@bar.com

X-OSS-Magic: abracadabra

假如Access Key ID是: "44CF9590006BF252F707"

Access Key Secret "OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV"可用以下方法签名(Signature):

python示例代码:

import base64

import hmac

import sha

h = hmac.new("OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV",

             "PUT\nc8fdb181845a4ca6b8fec737b3581d76\ntext/html\nThu, 17 Nov 2005 18:49:58 GMT\nx-oss-magic:abracadabra\nx-oss-meta-author:foo@bar.com\n/oss-example/nelson", sha)

base64.encodestring(h.digest()).strip()

签名(Signature)计算结果应该为”63mwfl+zYIOG6k95yxbgMruQ6QI=”, 然后加上Authorization头来组成最后需要发送的消息:

PUT /nelson HTTP/1.0

Authorization: OSS 44CF9590006BF252F707: 63mwfl+zYIOG6k95yxbgMruQ6QI=

Content-Md5: c8fdb181845a4ca6b8fec737b3581d76

Content-Type: text/html

Date: Thu, 17 Nov 2005 18:49:58 GMT

Host: oss-example.oss.aliyuncs.com

X-OSS-Meta-Author: foo@bar.com

X-OSS-Magic: abracadabra

   

在计算签名头的时候请遵循如下规则: 

1)  用来签名的字符串必须为UTF-8格式。含有中文字符的签名字符串必须先进行UTF-8编码,再与Access Key Secret计算最终签名。

2)  签名的方法用RFC 2104 (http://www.ietf.org/rfc/rfc2104.txt)中定义的HMAC-SHA1方法,其中KeyAccess Key Secret

3)  content-typecontent-md5在请求中不是必须的,但是如果请求需要签名验证,空值的话以换行符“\n”代替。

4)  在所有非HTTP标准定义的header中,只有以“x-oss-”开头的header,需要加入签名字符串;其他非HTTP标准header将被OSS忽略(如上例中的x-oss-magic)。

5)  以“x-oss-”开头的head在签名验证前需要符合以下规范:

Ø  head的名字需要变成小写。

Ø  head按字典序自小到大排序。

Ø  分割head namevalue的冒号前后不能有空格。

Ø  每个Head之后都有一个换行符“\n”,如果没有HeadCanonicalizedOSSHeaders就设置为空。

 

细节分析:

1)  如果传入的Access Key ID不存在或inactive,返回403 Forbidden。错误码:InvalidAccessKeyId

2)  若用户请求头中Authorization值的格式不对,返回400 Bad Request。错误码:InvalidArgument

3)  OSS所有的请求都必须使用HTTP 1.1协议规定的GMT时间格式。其中,日期的格式有三种:

date1 = 2DIGIT SP month SP 4DIGIT; day month year (e.g., 02 Jun 1982)            

date2 = 2DIGIT "-" month "-" 2DIGIT; day-month-year (e.g., 02-Jun-82)

date3 = month SP ( 2DIGIT | ( SP 1DIGIT )); month day (e.g., Jun  2)  【注意“2”前面有两个空格】

上述这三种日期格式中,“天”所占位数都是“2 DIGIT”。因此,“Jun 2”、“2 Jun 1982”和“2-Jun-82”都是非法日期格式。

4)  如果签名验证的时候,头中没有传入Date或者格式不正确,返回403 Forbidden错误。错误码:AccessDenied

5)  传入请求的时间必须在OSS服务器当前时间之后的15分钟以内,否则返回403 Forbidden。错误码:RequestTimeTooSkewed

6)  如果Access Key IDactive的,但OSS判断用户的请求发生签名错误,则返回403 Forbidden,并在返回给用户的response中告诉用户正确的用于验证加密的签名字符串。用户可以根据OSSresponse来检查自己的签名字符串是否正确。

返回示例:

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

<Error xmlns=”http://doc.oss.aliyuncs.com”>

<Code>

           SignatureDoesNotMatch

</Code>

<Message>

           The request signature we calculated does not match the signature you provided. Check your key and signing method.

</Message>

<StringToSignBytes>

           47 45 54 0a 0a 0a 57 65 64 2c 20 31 31 20 4d 61 79 20 32 30 31 31 20 30 37 3a 35 39 3a 32 35 20 47 4d 54 0a 2f 75 73 72 65 61 6c 74 65 73 74 3f 61 63 6c

</StringToSignBytes>

<RequestId>

           1E446260FF9B10C2

</RequestId>

<HostId>

           oss.aliyuncs.com

</HostId>

<SignatureProvided>

           y5H7yzPsA/tP4+0tH1HHvPEwUv8=

</SignatureProvided>

<StringToSign>

           GET

Wed, 11 May 2011 07:59:25 GMT

/oss-example?acl

</StringToSign>

<OSSAccessKeyId>

           AKIAIVAKMSMOY7VOMRWQ

</OSSAccessKeyId>

</Error>

 

4.3          URL中包含签名

除了使用Authorization Head,用户还可以在URL中加入签名信息,这样用户就可以把该URL转给第三方实现授权访问。

 

URL中包含签名示例:

http://oss-example.oss.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=44CF9590006BF252F707&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D

 

URL中实现签名,必须至少包含SignatureExpiresOSSAccessKeyId三个参数。Expires这个参数的值是一个UNIX时间(自UTC时间197011号开始的秒数,详见wiki),用于标识该URL的超时时间。如果OSS接收到这个URL请求的时候晚于签名中包含的Expires参数时,则返回请求超时的错误码。例如:当前时间是1141889060,开发者希望创建一个60秒后自动失效的URL,则可以设置Expires时间为1141889120

所有的OSS支持的请求和各种Head参数,在URL中进行签名的方法和上节介绍的签名算法基本一样。主要区别如下:

1)        通过URL包含签名时,之前的Date参数换成Expires参数。

2)        不支持同时在URLHead中包含签名。

3)        如果传入的SignatureExpiresOSSAccessKeyId出现不止一次,以第一次为准。

4)        请求先验证请求时间是否晚于Expires时间,然后再验证签名。

 

URL中添加签名的python示例代码为:

import base64

import hmac

import sha

import urllib

h = hmac.new("OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV",

             "GET\n\n\n1141889120\n/oss-example/oss-api.pdf",

             sha)

urllib.quote_plus (base64.encodestring(h.digest()).strip())

 

细节分析:

1)        使用在URL中签名的方式,会将你授权的数据在过期时间以内曝露在互联网上,请预先评估使用风险。

2)        PUTGET请求都支持在URL中签名。

3)        URL中添加签名时,SignatureExpiresOSSAccessKeyId顺序可以交换,但是如果SignatureExpiresOSSAccessKeyId缺少其中的一个或者多个,返回403 Forbidden。错误码:AccessDenied

4)        如果访问的当前时间晚于请求中设定的Expires时间,返回403 Forbidden。错误码:AccessDenied

5)        如果传入请求时间,必须在OSS服务器当前时间之后的15分钟以内。否则返回403 Forbidden。错误码:RequestTimeTooSkewed

6)        如果Expires时间格式错误,返回403 Forbidden。错误码:AccessDenied

7)        如果URL中包含参数SignatureExpiresOSSAccessKeyId中的一个或者多个,并且Head中也包含签名消息,返回消息400 Bad Request。错误码:InvalidArgument

8)        生成签名字符串时,除Date被替换成Expires参数外,仍然包含content-typecontent-md5等上节中定义的Header。(请求中虽然仍然有Data这个请求头,但不需要将Data加入签名字符串中)

 

4.4          Bucket权限控制

OSS提供Bucket级别的权限访问控制,Bucket目前有三种访问权限:public-read-writepublic-readprivate,它们的含义如下:

n  public-read-write任何人(包括匿名访问)都可以对该bucket中的object进行PUTGetDelete操作;所有这些操作产生的费用由该bucket的创建者承担,请慎用该权限。

n  public-read只有该bucket的创建者可以对该bucket内的Object进行写操作(包括PutDelete Object);任何人(包括匿名访问)可以对该bucket中的object进行读操作(Get Object)。

n  private只有该bucket的创建者可以对该bucket内的Object进行读写操作(包括PutDeleteGet Object);其他人无法访问该Bucket内的Object

用户新创建一个新Bucket时,如果不指定Bucket权限,OSS会自动为该Bucket设置private权限。对于一个已经存在的Bucket,只有它的创建者可以通过OSS Put Bucket Acl接口修改该Bucket的权限。

 

相关阅读:

Ø  Put Bucket Acl

Ø  Get Bucket Acl


Ø   

5.  开放接口规范

本章主要介绍OSS的开放接口。开发者在发送请求给OSS时,既可以使用带签名认证的请求,也可以使用匿名访问。当签名验证错误或者是访问没有权限的资源时,OSS返回的错误码请参考下一章,本章就不在举例了。


 

5.1          公共HTTP头定义

5.1.1                公共请求头(Common Request Headers

OSSRESTful接口中使用了一些公共请求头。这些请求头可以被所有的OSS请求所使用,其详细定义如下:

名称

描述

Authorization

用于验证请求合法性的认证信息。

类型:字符串

默认值:无

使用场景:非匿名请求

Content-Length

RFC 2616中定义的HTTP请求内容长度。

类型:字符串

默认值:无

使用场景:需要向OSS提交数据的请求

Content-Type

RFC 2616中定义的HTTP请求内容类型。

类型:字符串

默认值:无

使用场景:需要向OSS提交数据的请求

Date

HTTP 1.1协议中规定的GMT时间,例如:Wed, 05 Sep. 2012 23:00:00 GMT

类型:字符串

默认值:无

Host

访问Host值,格式为:<bucketname>.oss.aliyuncs.com

类型:字符串

默认值:无


 

5.1.2                公共响应头(Common Response Headers

OSSRESTful接口中使用了一些公共响应头。这些响应头可以被所有的OSS请求所使用,其详细定义如下:

名称

描述

Content-Length

RFC 2616中定义的HTTP请求内容长度。

类型:字符串

默认值:无

使用场景:需要向OSS提交数据的请求

Connection

标明客户端和OSS服务器之间的链接状态。

类型:枚举

有效值:open | close

默认值:无

Date

HTTP 1.1协议中规定的GMT时间,例如:Wed, 05 Sep. 2012 23:00:00 GMT

类型:字符串

默认值:无

ETag

ETag (entity tag) 在每个Object生成的时候被创建,用于标示一个Object的内容。对于Put Object请求创建的ObjectETag值是其内容的MD5值;对于其他方式创建的ObjectETag值是其内容的UUIDETag值可以用于检查Object内容是否发生变化。

类型:字符串

默认值:无

Server

生成Response的服务器。

类型:字符串

默认值:AliyunOSS

x-oss-request-id

x-oss-request-id是由Aliyun OSS创建,并唯一标识这个responseUUID。如果在使用OSS服务时遇到问题,可以凭借该字段联系OSS工作人员,快速定位问题。

类型:字符串

默认值:无


 

5.2          关于Service的操作

5.2.1                GetService (ListBucket)

对于服务地址作Get请求可以返回请求者拥有的所有Bucket,其中“/”表示根目录。

 

请求语法:

GET / HTTP/1.1

Host: oss.aliyuncs.com

Date: GMT Date

Authorization: SignatureValue

 

响应元素(Response Elements)

名称

描述

Bucket

保存bucket信息的容器.

类型:容器

子节点:Name, CreationDate

父节点:ListAllMyBucketsResult.Buckets

Buckets

保存多个Bucket信息的容器。

类型:容器

子节点:Bucket

父节点:ListAllMyBucketsResult

CreateDate

Bucket创建时间

类型:时间 (格式:yyyy-mm-ddThh:mm:ss.timezone, e.g.,

2011-12-01T12:27:13.000Z)

父节点:ListAllMyBucketsResult.Buckets.Bucket

DisplayName

Bucket拥有者的名称 (目前和ID一致)

类型:字符串

父节点:ListAllMyBucketsResult.Owner

ID

Bucket拥有者的用户ID

类型:字符串

父节点:ListAllMyBucketsResult.Owner

ListAllMyBucketsResult

保存Get Service请求结果的容器。

类型:容器

子节点: Owner, Buckets

父节点:None

Name

Bucket名称。

类型:字符串

父节点:ListAllMyBucketsResult.Buckets.Bucket

Owner

用于存放Bucket拥有者信息的容器。

类型:容器

父节点:ListAllMyBucketsResult

 

细节分析:

1)  GetService这个API只对验证通过的用户有效。

2)  如果请求中没有用户验证信息(即匿名访问),返回403 Forbidden。错误码:AccessDenied

 

请求示例:

GET / HTTP/1.1

Host: oss.aliyuncs.com

Date: Fri, 24 Feb 2012 02:58:28 GMT

Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:MiorP5BDFDhKAn44wDnkSSv2Z94=

返回示例:

HTTP/1.1 200 OK

x-oss-request-id: 60633d3c-1293-0d72-7739-759423f02d36

Date: Fri, 24 Feb 2012 02:58:28 GMT

Content-type: application/xml

Content-Length: 685

Connection: close

Server: AliyunOSS

 

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

<ListAllMyBucketsResult xmlns=”http://doc.oss.aliyuncs.com”>

    <Owner>

        <ID>00220120222</ID>

        <DisplayName>oss_doc</DisplayName>

    </Owner>

    <Buckets>

        <Bucket>

            <Name>multipart_upload</Name>

            <CreationDate>2012-02-22T08:25:07.000Z</CreationDate>

        </Bucket>

        <Bucket>

            <Name>my_oss</Name>

            <CreationDate>2012-02-24T02:53:26.000Z</CreationDate>

        </Bucket>

    </Buckets>

</ListAllMyBucketsResult>

 

相关阅读:

Ø  Get Bucket (List Object)

Ø  Get Object


 

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

 

相关阅读:

Ø  Put Bucket

Ø  Delete Object

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)

   GetBucketListObject)时,可以通过prefixmarkerdelimitermax-keyslist做限定,返回部分结果。

名称

描述

delimiter

是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes

数据类型:字符串

默认值:无

marker

设定结果从marker之后按字母排序的第一个开始返回。

数据类型:字符串

默认值:无

max-keys

限定此次返回object的最大数,如果不设定,默认为1000max-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请求创建的ObjectETag值是其内容的MD5值;对于其他方式创建的ObjectETag值是其内容的UUIDETag值可以用于检查Object内容是否发生变化。

类型:字符串

父节点:ListBucketResult.Contents

ID

Bucket拥有者的用户ID

类型:字符串

父节点:ListBucketResult.Contents.Owner

IsTruncated

指明是否所有的结果都已经返回;“true”标示所有结果都已经返回;“false”表示本次请求只返回了部分结果。

类型:枚举字符串

有效值:true | false

父节点:ListBucketResult

Key

ObjectKey.

类型:字符串

父节点:ListBucketResult.Contents

LastModified

Object最后被修改的时间。

类型:时间

父节点:ListBucketResult.Contents

ListBucketResult

保存Get Bucket请求结果的容器.

类型:容器

子节点:Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents

父节点:None

Marker

标明这次Get BucketList 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可以以此为markerNextMarker中的值仍在list结果之中。

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

6)  prefixmarkerdelimiter参数不符合长度要求,返回400 Bad Request。错误码:InvalidArgument

7)  prefixmarker用来实现分页显示效果,参数的长度必须小于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/”;即实现了文件夹的逻辑。

 

举例场景:

bucketmy_oss”内有4object,名字分别为:

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"?>

<ListBucketResult xmlns=”http://doc.oss.aliyuncs.com”>

<Name>oss-example</Name>

<Prefix></Prefix>

<Marker></Marker>

<MaxKeys>100</MaxKeys>

<Delimiter></Delimiter>

    <IsTruncated>false</IsTruncated>

    <Contents>

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

        <LastModified>2012-02-24T08:43:07.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user-example</DisplayName>

        </Owner>

    </Contents>

    <Contents>

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

        <LastModified>2012-02-24T08:43:27.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user-example</DisplayName>

        </Owner>

    </Contents>

<Contents>

        <Key>fun/test.jpg</Key>

        <LastModified>2012-02-24T08:42:32.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user-example</DisplayName>

        </Owner>

    </Contents>

    <Contents>

        <Key>oss.jpg</Key>

        <LastModified>2012-02-24T06:07:48.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <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"?>

<ListBucketResult xmlns=”http://doc.oss.aliyuncs.com”>

<Name>oss-example</Name>

<Prefix>fun</Prefix>

<Marker></Marker>

<MaxKeys>100</MaxKeys>

<Delimiter></Delimiter>

    <IsTruncated>false</IsTruncated>

    <Contents>

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

        <LastModified>2012-02-24T08:43:07.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user_example</DisplayName>

        </Owner>

    </Contents>

    <Contents>

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

        <LastModified>2012-02-24T08:43:27.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user_example</DisplayName>

        </Owner>

    </Contents>

    <Contents>

        <Key>fun/test.jpg</Key>

        <LastModified>2012-02-24T08:42:32.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user_example</DisplayName>

        </Owner>

    </Contents>

</ListBucketResult>

 

请求示例(prefixdelimiter参数)

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"?>

<ListBucketResult xmlns=”http://doc.oss.aliyuncs.com”>

<Name>oss-example</Name>

<Prefix>fun/</Prefix>

<Marker></Marker>

<MaxKeys>100</MaxKeys>

<Delimiter>/</Delimiter>

    <IsTruncated>false</IsTruncated>

    <Contents>

        <Key>fun/test.jpg</Key>

        <LastModified>2012-02-24T08:42:32.000Z</LastModified>

        <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>

        <Type>Normal</Type>

        <Size>344606</Size>

        <StorageClass>Standard</StorageClass>

        <Owner>

            <ID>00220120222</ID>

            <DisplayName>user_example</DisplayName>

        </Owner>

    </Contents>

   <CommonPrefixes>

        <Prefix>fun/movie/</Prefix>

   </CommonPrefixes>

</ListBucketResult>

 

相关阅读:

Ø  Put Bucket

Ø  Put Object

Ø  Get Object


 

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

BucketACL权限。

类型:枚举字符串

有效值: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" ?>

<AccessControlPolicy>

    <Owner>

        <ID>00220120222</ID>

        <DisplayName>user_example</DisplayName>

    </Owner>

    <AccessControlList>

        <Grant>public-read</Grant>

    </AccessControlList>

</AccessControlPolicy>

 

相关阅读:

Ø  Put Bucket

Ø  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

 

相关阅读:

Ø  Get Bucket (List Object)

Ø  Delete Bucket

Ø  Put Object


 

5.3.5                Put Bucket Acl

Put Bucket ACL接口用于修改Bucket访问权限。目前Bucket有三种访问权限:public-read-writepublic-readprivatePut 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" ?>

<Error xmlns=”http://doc.oss.aliyuncs.com”>

        <Code>

                InvalidArgument

        </Code>

        <Message>

        </Message>

        <ArgumentValue>

                error-acl

        </ArgumentValue>

        <ArgumentName>

                x-oss-acl

        </ArgumentName>

        <RequestId>

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

        </RequestId>

        <HostId>

                oss.aliyuncs.com

        </HostId>

</Error>

 

相关阅读:

Ø  Put Bucket

Ø  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

如果源ObjectETAG值和用户提供的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

有效值为COPYREPLACE。如果该值设为COPY,则新的Objectmeta都从源Object复制过来;如果设为REPLACE,则忽视所有源Objectmeta值,而采用用户这次请求中指定的meta值;其他值则返回400 HTTP错误码。

类型:字符串

默认值:COPY

有效值:COPY | REPLACE

 

响应元素(Response Elements)

名称

描述

CopyObjectResult

Copy Object结果

类型:字符串

默认值:无

ETag

ObjectETag值。