API 接口文档


概念和术语

AccessKey(访问秘钥)、SecretKey

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

Region(区域)

地区包含:中国(北京)、中国(上海)、中国(香港)

创建bucket时需要选择Region

Region中文名称 外网域名 内网域名
中国(北京) ks3-cn-beijing.ksyun.com ks3-cn-beijing-internal.ksyun.com
中国(上海) ks3-cn-shanghai.ksyun.com ks3-cn-shanghai-internal.ksyun.com
中国(香港) ks3-cn-hk-1.ksyun.com ks3-cn-hk-1-internal.ksyun.com

如果不配置成对应的域名将返回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:SignatureSignature = 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示例:

http://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 头定义

公共请求头

Header 名字 描述 必须
Authorization 请求的验证信息 Y
Content-Length HTTP Request Body 长度 N
Content-MD5 HTTP Request Body MD5 值,Base64 编码 N
Content-Type HTTP Request Body 的 MIME 类型 N
Date 请求的时间戳 Y
Host 请求的 URI Y

错误码列表

messageHTTP Status描述
AccessDenied403拒绝访问
BadDigest400错误的摘要
BucketAlreadyExists409Bucket已经存在
BucketAlreadyOwnedByYou409用户已经是Bucket的拥有者
BucketNotEmpty409Bucket不为空
InternalError500内部错误
InvalidAccessKey403无效的AccessKey
InvalidACLString400ACL配置无效
InvalidAuthorizationString400无效的验证字符串
InvalidBucketName400无效的Bucket名称
InvalidDateFormat400无效的日期格式
InvalidDigest400无效的摘要
InvalidEncryptionAlgorithm400无效的指定加密算法
InvalidHostHeader400无效的头信息
InvalidParameter400无效的参数
InvalidPath400无效的路径
InvalidQueryString400无效的请求字符串
InvalidRange416无效的range
KeyTooLong400Key太长
MetadataTooLarge400metadata过大
MethodNotAllowed405不支持的方法
MissingDateHeader400头信息中缺少data
MissingHostHeader400头信息中缺少host
NoSuchBucket404该Bucket不存在
NoSuchKey404该Key不存在
NotImplemented501无法处理的方法
RequestTimeTooSkewed403发起请求的时间和服务器时间超出15分钟
SignatureDoesNotMatch403签名不匹配
TooManyBuckets400用户的Bucket数目超过限制
URLExpired403url过期
BadParams400参数错误
ImageTypeNotSupport400图片类型不支持
MissingFormArgs400没有上传Policy
ContentRangeError400Range错误
ContentLengthOutOfRange400上传文件内容大于range
PolicyError400Policy错误
ExpirationError400Policy中没有expiration
FormUnmatchPolicy400表单中的内容和policy不匹配