文档中心

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中。每个用户最多可以创建30个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~100GB的数据。 Object 包含key和data。其中,key是Object的名字;data是Object 的数据。key为UTF-8编码,且编码后的长度不得超过1024个字节。

Key(文件名)

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

ACL(访问控制列表)

KS3使用ACL(访问控制列表)方便用户管理Bucket和Object的访问权限,每个一个Bucket和Object都拥有一个ACL,ACL定义了哪些用户被授予访问权限以及访问的类型,KS3收到针对某个资源的请求后,将检查相应的ACL以验证请求者是否拥有所需的访问权限。

下表列出了KS3在ACL中支持的权限集。注意,对于对象ACL和存储桶ACL,ACL权限集相同。但根据上下文(存储桶ACL或对象ACL),这些ACL权限授予对存储桶或对象操作的特定权限。下表列出了许可并介绍了它们在Bucket和Object许可语境中的含义。

ACL权限 对Bucket(存储桶)授权 对Object(对象)授权
READ 允许被授权者列出存储桶中的对象 允许被授权者读取对象数据及其元数据
WRITE 允许被授权者创建、覆盖和删除存储桶中的任意对象 不适用
FULL_CONTROL 授予被授权者在存储桶上的READ、WRITE 权限 授予被授权者在对象上的READ权限

从上图得知,ACL仅允许授予有限数量的权限。其中的每个权限允许一个或多个 KS3 操作。下表显示每个ACL权限如何映射到相应的访问策略权限。ACL 主要用于授予基本读/写权限,这与文件系统权限类似。

ACL权限 在Bucket(存储桶)授予ACL权限时的相应访问策略 在Objetc(文件对象)授予ACL权限时的相应访问策略
READ List Bucket,List Multipart Upload Get Object,Head Object, List Parts
WRITE Put Object, Post Object, Put Object Copy, Upload Part Copy,Delete Object,Initiate Multipart Upload, Upload Part, Complete Multipart Upload, Abort Multipart Upload 不适用
FULL_CONTROL 等同于授予READ和WRITE ACL权限 等同于授予READ ACL权限。

预设ACL

KS3支持一系列预定义的授权,称为预设ACL。每个预设ACL都有一组预定义的被授权者和权限。下表列出了一系列预设ACL和相关联的预定义授权。

预设ACL 适用于 预设ACL的权限
private Bucket和Object 所有者将获得 FULL_CONTROL。其他人没有访问权限(默认)。
public-read Bucket和Object 所有者将获得 FULL_CONTROL。其他人(包括匿名用户)将获得 READ 访问权限。
public-read-write Bucket和Object 所有者将获得 FULL_CONTROL。其他人(包括匿名用户)将获得 READ 和 WRITE 访问权限。通常不建议在存储桶上授予该权限。

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)计算方法:
 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+
               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组合,详见CanonicalizedKssHeaders计算方法
  • CanonicalizedResource 表示用户访问的资源,详见CanonicalizedResource的计算方法
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. 删除请求头和内容之间分隔符两端出现的任何空格。如x-kss-meta-myname: Jack转换为:x-kss-meta-myname:Jack
  4. 将这些Header Name, Header Value对使用"\n"分隔符连接在一起。

注意:

  • CanonicalizedKssHeaders为空,无需添加最后的\n
  • 如果只有一个,则需要在最后添加\n,例如:x-kss-meta-yourname:Lee\n
  • 如果有多个,则使用使用"\n"分隔符连接在一起,并且在最后添加\n,例如:x-kss-meta-myname:Jack\nx-kss-meta-yourname:Lee\n
CanonicalizedResource的计算方法

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

/[BucketName/[ObjectKey[?SubResource]]]
  • BucketName:用户请求的Bucket名称。

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

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

计算方法如下:

  1. CanonicalizedResource="/"

  2. 如果BucketName不为空,则 CanonicalizedResource = CanonicalizedResource + BucketName + "/"

  3. 如果ObjectKey不为空,则 CanonicalizedResource = CanonicalizedResource + ObjectKey

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

  5. 如果SubResource不为空,则CanonicalizedResource = CanonicalizedResource + "?" + SubResource

计算签名的例子:

示例中的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值

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不匹配
RequestEntityTooLarge413上传文件的大小不符合限制
Request Timeout408服务器等候请求时发生超时