API 接口文档

概念和术语

AccessKey（访问秘钥）、SecretKey

使用KS3，您需要KS3颁发给您的AccessKey（长度为20个字符的ASCII字符串）和SecretKey（长度为40个字符的ASCII字符串）。AccessKey用于标识客户的身份，SecretKey作为私钥形式存放于客户服务器不在网络中传递。SecretKey通常用作计算请求签名的密钥，用以保证该请求是来自指定的客户。使用AccessKey进行身份识别，加上SecretKey进行数字签名，即可完成应用接入与认证授权。

Region（区域）

地区包含：中国(北京）、中国（上海）、中国（香港）

创建bucket时需要选择Region

如果不配置成对应的域名将返回307，会跳转到Bucket所在的Region。

Service（服务）

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

Bucket（存储空间）

Bucket是存放Object的容器，所有的Object都必须存放在特定的Bucket中。每个用户最多可以创建20个Bucket，每个Bucket中可以存放无限多个Object。Bucket不能嵌套，每个Bucket中只能存放Object，不能再存放Bucket，Bucket下的Object是一个平级的结构。Bucket的名称全局唯一且命名规则与DNS命名规则相同：

• 仅包含小写英文字母（a-z），数字，点（.），中线，即： abcdefghijklmnopqrstuvwxyz0123456789.-
• 必须由字母或数字开头
• 长度在3和63个字符之间
• 不能是IP的形式，类似192.168.0.1
• 不能以kss开头

Object（对象，文件）

在KS3中，用户操作的基本数据单元是Object。单个Object允许存储0~5TB的数据。 Object 包含key和data。其中，key是Object的名字；data是Object 的数据。key为UTF-8编码，且编码后的长度不得超过1024个字节。

Key（文件名）

即Object的名字，key为UTF-8编码，且编码后的长度不得超过1024个字节。Key中可以带有斜杠，当Key中带有斜杠的时候，将会自动在控制台里组织成目录结构。

ACL（访问控制权限）

对Bucket和Object相关访问的控制策略，例如允许匿名用户公开访问等。

目前ACL支持READ, WRITE, FULL_CONTROL三种权限。对于bucket的拥有者,总是FULL_CONTROL。可以授予所有用户(包括匿名用户)或指定用户READ， WRITE, 或者FULL_CONTROL权限。

目前提供了三种预设的ACL.分别是private、public-read和public-read-write。public-read表示为所有用户授予READ权限，public-read-write表示为所有用户授予WRITE权限.使用的时候通过在header中添加x-kss-acl实现。

对于BUCKET来说，READ是指罗列Bucket中的文件、罗列Bucket中正在进行的分块上传、罗列某个分块上传已经上传的块。WRITE是指可以上传，删除BUCKET中文件的功能。FULL_CONTROL则包含所有操作。可以通过PUT Bucket acl接口设置。

对于Object来说，READ是指查看或者下载文件的功能。WRITE无意义。FULL_CONTROL则包含所有操作。可以通过PUT Object acl设置。

Logging（日志）

对Bucket和Object的日志配置。

当给Bucket配置Logging之后，每天将会自动把该Bucket的操作日志上传到指定的Bucket。

请求签名

当用户请求KS3时，可以使用AccessKey和SecretKey对请求做签名，当KS3收到带签名信息的请求之后，将使用相同的算法验证签名，如果发现签名不一致，KS3将会返回403给用户。如果KS3验证签名一致，且AccessKey对应的用户有权限操作请求的资源，则请求成功，否则KS3返回403。

如果用户请求KS3时，在请求中没有携带签名信息，那么KS3认为该请求是匿名的。当KS3接收到匿名请求时，如果发现用户请求的资源不允许匿名请求，将会返回403。

通过 HTTP 请求 Header 发送签名

方法: 在请求中加入名为 Authorization 的 Header，值为签名值。形如：

Authorization: KSS P3UPCMORAFON76Q6RTNQ:vU9XqPLcXd3nWdlfLWIhruZrLAM=

 Authorization = “KSS YourAccessKey:Signature”

 Signature = Base64(HMAC-SHA1(YourSecretKey, UTF-8-Encoding-Of( StringToSign ) ) );

 StringToSign = HTTP-Verb + "\n" +
               Content-MD5 + "\n" +
               Content-Type + "\n" +
               Date + "\n" +
               [CanonicalizedKssHeaders + "\n" +]
               CanonicalizedResource;

Content-MD5, Content-Type, CanonicalizedKssHeaders可为空， 若为空，则使用空字符串("")替代, HTTP-Verb、Date和CanonicalizedResource不能为空

• HTTP-Verb 表示请求的方法，如：GET\PUT\POST\DELETE等
• Content-MD5 表示请求内容数据的MD5值, 使用Base64编码。当请求的header中包含Content-MD5时，需要在StringToSign中包含，否则用("")替代。 注意：Content-MD5的算法为先对数据做MD5摘要，再将MD5摘要做Base64编码。中间不需要做HEX编码，由于部分语言或工具包的MD5是默认做HEX编码的，所以当MD5算出来的结果为HEX编码的，首先需要对算出来的结果做HEX解码，然后再做Base64编码。详解RFC2616
• Content-Type 表示请求内容的类型，取HTTP header中的Content-Type
• Date 表示此次操作的时间,且必须为 HTTP1.1 中支持的 GMT 格式。取HTTP Header中的Date,如果该时间与KS3服务端时间相差15分钟以外，将导致KS3返回403。比如：Wed, 17 Feb 2012 15:31:56 GMT
• CanonicalizedKssHeaders 表示HTTP请求中的以x-kss开头的Header组合
• CanonicalizedResource 表示用户访问的资源

CanonicalizedResource CanonicalizedResource 代表了请求的目标资源,构造过程如下:

/[BucketName/[ObjectKey[?SubResource]]]

• BucketName:用户请求的Bucket名称。

• ObjectKey:用户请求的Object名称,需要对Object名称做URL编码。

• SubResource:用户请求的子资源。把URL参数中的"acl","lifecycle","location","logging","policy","torrent","uploadId","uploads","versionId","versioning","versions","website","delete","thumbnail","cors","adp","response-content-type","response-content-language","response-expires","response-cache-control","response-content-disposition","response-content-encoding"筛选出来，将这些查询字符串及其请求值(不做URL编码的请求值)按照字典序，从小到大排列，以&为分隔符排列，即可得到SubResource。

  比如：

  {BucketName}.kss.ksyun.com/{ObjectKey}?acl ,则SubResource为acl

  {BucketName}.kss.ksyun.com/{ObjectKey}?response-content-type=application%2Fjson&response-content-disposition=attachment%3Bfilename%3DXXX , 则SubResource为response-content-disposition=attachment;filename=XXX&response-content-type=application/json

构造方法：

CanonicalizedResource = "/"

1、如果BucketName不为空,则 CanonicalizedResource = CanonicalizedResource + BucketName + "/"

2、如果ObjectKey不为空,则 CanonicalizedResource = CanonicalizedResource + ObjectKey

3、替换CanonicalizedResource中的双斜杠("//")为"/%2F"

4、如果SubResource不为空，则CanonicalizedResource = CanonicalizedResource + "?" + SubResource

CanonicalizedKssHeaders

构造过程如下：

1. 先选出所有以x-kss-开头的 HTTP 请求Header，并把Header Name全部转成小写，如： X-KSS-Meta-Myname: Jack 把Header Name转成小写后为 x-kss-meta-myname: Jack
2. 将这些Header按Header Name的名字顺序排序
3. 将这些Header Name， Header Value对使用"\n"连接在一起并去除Name与Value之间的空格。 如 x-kss-meta-myname: Jack, x-kss-meta-yourname: Lee 连在一起是 x-kss-meta-myname:Jack\nx-kss-meta-yourname:Lee\n

计算签名的例子： 示例中的ObjectKey为经过URL编码的ObjectKey

PUT /{BucketName}/{ObjectKey} HTTP/1.0
Content-Md5: 1B2M2Y8AsgTpgAmY7PhCfg==
Content-Type: text/html
Content-Length: 1024
Date: Wed, 17 Feb 2012 15:31:56 GMT
Host: kss.ksyun.com

假设 SecretKey 为：Ik90eHJ6eElzZnBGakE3U3dQeklMd3k,其签名算法为：

import base64
import hmac
from hashlib import sha1
h = hmac.new("Ik90eHJ6eElzZnBGakE3U3dQeklMd3k", "PUT\n1B2M2Y8AsgTpgAmY7PhCfg==\ntext/html\nWed, 17 Feb 2012 15:31:56 GMT\n/{BucketName}/{ObjectKey}", sha1)
Signature = base64.encodestring(h.digest()).strip()

通过 URL QueryString 发送签名

携带签名的URL示例：

 https://kss.ksyun.com/{BucketName}/{ObjectKey}?KSSAccessKeyId=VSDNT6SHFNDWBXYZRS3A&Expires=1435550417&Signature=a2JnaLMuN%2FWmcKL%2FW4aibMCa4BY%3D

KSSAccessKeyId为用户的AccessKey

Expires为该链接的过期时间，使用Unix_Time表示

Signature的计算法同上，只是把Date换成Expires值

Bucket 访问控制

KS3提供Bucket级别的权限访问控制（ACL），Bucket目前有以下三种访问权限：public-read-write，public-read和private，它们的含义如下：

• public-read-write：任何人（包括匿名访问）都可以对该bucket 中的object进行PUT，Get和Delete操作。
• public-read：任何人（包括匿名访问）只能对该bucket中的object进行读操作，而不能进行写操作。注意，对Bucket有读操作不表示对Object有读操作。
• private：只有该bucket的创建者可以对该bucket及bucket中的object进行读写操作

Obejct 访问控制

KS3提供Bucket级别的权限访问控制（ACL），Object目前有以下两种访问权限：public-read和private，它们的含义如下：

• public-read：任何人（包括匿名访问）都可以对该object进行读操作（即下载）
• private：只有object的拥有者可以对该object进行操作。

REST API 集合

公共 HTTP 头定义

公共请求头

错误码列表