京东云存储开发者文档

Transcription

1 更新时间 更新内容 2013/05/21 创建文档 2013/07/10 增加分块上传 API 的内容 2013/07/12 增加桶和对象 API 的内容

2 目录 京东云存储开发者文档... 1 目录... 2 一 前言... 4 二 介绍... 5 三 相关概念 AccessKey 与 SecretKey Bucket 限制 Object 描述 系统预定义元数据 (System-Defined Metadata) 限制 Key 描述 限制 Host... 8 四 安全认证 构造认证请求 HMAC-SHA 构造 CanonicalizedResource 时间戳... 11

3 4.2 构造基于查询字符串的认证请求 概要 例子 五 REST API 错误响应 错误代码列表 错误相应结构 API 接口 通用请求头 通用响应头 Bucket 相关接口 Object 相关接口 Multipart Upload 相关接口... 32

4 一 前言 本文档是京东云存储开发者文档, 描述了 : 1. 京东云存储的核心概念, 包括 Bucket Object Key 等 2. 如何访问京东云存储提供的 API 3. 如何通过 API 管理与使用京东云存储

5 二 介绍 京东云存储是京东提供的一款基于互联网的云存储服务, 此服务让所有开发人员都能访 问同一个具备高扩展性 可靠性 安全性和性价比的基础设施, 而京东正是使用此种基础设 施来运行其全球的网站网络的 该服务旨让扩展带来的优势得以最大化, 并将这种优势传递 给开发人员

6 三 相关概念 3.1 AccessKey 与 SecretKey AccessKey 与 SecretKey 是用户访问京东云存储 API 的身份标识, 用户在使用京东云存 储之前, 应该向京东云鼎平台申请 AccessKey 与 SecretKey 并获得使用权限 具体信息请参 考 Bucket Bucket 是存放 文件 ( 云存储称之为 Object,) 的容器, 所有的 Object 都必须存放到 某个 Bucket 中 例如, 你有个 key 为 public/index.html 的 Object, 存放到名字为 mybucket 的 Bucket 中, 那么访问该 Object 的 URI 应该为 : 限制 每个用户最多可以创建 100 个 Bucket, 每个 Bucket 中可以存放无限多个 Object Bucket 不能嵌套, 每个 Bucket 中只能存放 Object, 不能再存放 Bucket Bucket 的数量对云存储的性能没有影响,10 万个 Object 存放在同一个 Bucket 中和 分布在 100 个不同的 Bucket 中的性能是一样的 Bucket 的操作是中心化的, 所以应尽量避免进行频繁的创建 删除 Bucket 等相关操 作, 推荐的方式是通过云存储控制台, 或者只在应用程序初始化时进行创建, 删除 Bucket 等 相关的操作

7 Bucket 的名称全局唯一且严格的限制, 包括 : 1. 仅包含小写英文字母 (a-z), 数字, 点 (.) 和横线 (-) 2. 必须由字母或数字开头和结尾 3. 长度在 3 和 63 个字符之间 4. 不能为 IP 地址形式, 比如 不能包含连续的点 (.) 与横线 (-) 组合 为了发挥云存储的最大功能, 我们强烈建议 Bucket 的名字符合域名规范, 比 如 :music.jd.com, ump.jd.com, 非域名格式的 bucket 无法享受某些服务 3.3 Object 描述 Object 是京东云存储中的基本实体, 由键 (Key), 数据 (Data) 和元数据 (Metadata) 三部分 组成 关于数据 (Data), 京东云存储并不关心其内容具体是什么 而元数据 (Metadata) 则是一 组键值 (Key-Value) 的组合, 分为系统预定义元数据 (System-Defined Metadata) 和用户自定义 元数据 (User-Defined Metadata) 两部分 注 : 用户自定义元数据 (User-Defined Metadata) 将在未来开放其功能 系统预定义元数据 (System-Defined Metadata) 为了系统内部管理的需要, 京东云存储对其存储的每一个的 Object 都维护一组系统定 义元数据, 包括数据的长度, 创建时间,MD5 值等

8 限制 1. 使用 PUT Object 接口上传数据, 数据长度限制为 5GB 3.4 Key 描述 Key 是一个 Object 的标识, 在每一个 Bucket 中, 每个 Object 有且仅有一个 Key 而用户可以通过 Bucket + Key 的方式唯一标识云存储中的一个 Object, 例如对于 URL: 域名之后到第一个斜线 ( / ) 是 Bucket, 为 mybucket, 之后是 Object 的 Key, 为 public/index.html 限制 Key 为 UTF-8 编码, 且符合如下规则 Key 不能以 / 开头 Key 只能包含字母 数字 中文 /. - _ 组成 Key 的长度在 1 个字符到 100 个字符之间 3.5 Host 京东云存储唯一的域名是 :storage.jcloud.com

9 四 安全认证 京东云存储会对访问的请求进行安全认证, 只有通过认证的请求, 才能访问云存储中的 数据 下面是认证的过程 : 1. 客户端构造访问云存储的请求 2. 通过 SecretKey 计算请求的签名 (Signature) 3. 将附带 AccessKey 和签名 (Signature) 信息的请求发送给京东云存储系统 4. 京东云存储通过请求中的 AccessKey 查找对应的 SecretKey 5. 京东云存储利用 SecretKey 重新计算请求的签名 (Signature) 6. 若京东云存储计算的签名与客户端提供的签名相匹配, 则认证通过, 请求被接受, 否则京东云存储拒绝处理该请求 京东云存储通过基于 Hmac(Hash Message Authentication Code) 算法的自定义 HTTP 头 来进行认证操作 要认证一个请求, 客户端首先从请求中选取一些关键的元素组成一个字符 串 (String), 然后利用自己的 SecretKey 计算该字符串的 Hmac 值, 这个过程被称之为请求 签名 (signing the request), 计算得出的 Hmac 值被称之为签名 (signature), 之后, 用户将 该签名以请求参数的形式发送给京东云存储 带有认证信息的请求样例 : DELETE /ccd35eea-3c86-48f4-bd03-2acd5439d12f Date: Tue, 21 May :06:05 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:VREwI/vvZfgds1ueMjy6K0wfqjg=

10 4.1 构造认证请求 京东云存储 REST API 通过标准的 HTTP 头 Authorization 来传递认证信息, 下面是供 参考的 HTTP 认证头模板 : Authorization: jingdong AccessKey:Signature 下面是生成 Authorization 头的伪代码 : Authorization = "jingdong" + " " + AccessKey + ":" + Signature; Signature = Base64( HMAC-SHA1( YourSecretKey, UTF-8-Encoding-Of( StringToSign ) ) ); StringToSign = HTTP-Verb + "\n" + Content-MD5 + "\n" + Content-Type + "\n" + Date + "\n" + CanonicalizedHeaders + CanonicalizedResource; CanonicalizedResource = [ "/" + Bucket ] + <HTTP-Request-URI, from the protocol name up to the query string> + [ sub-resource, if present. For example "?acl", "?location", "?logging", or "?torrent"]; 注意 : 目前京东云存储不支持 CanonicalizedHeaders, 因此其以空字符串 ( ) 代替 当 Content-Type,Content-MD5 不存在时, 由空字符串代替 HMAC-SHA1 HMAC-SHA1 算法的详细信息可参看 RFC 2104( 标 准 该算法输入两个参数 :Key 和 Message, 并计算出一个结果 Digest 对于京东云存储 来说,Key 就是 SecretKey,Message 就是 UTF-8 编码的 StringToSign, 计算出的结果 Digest 经过 Base64 编码之后就是 Signature

11 构造 CanonicalizedResource CanonicalizedResource 代表了请求的目标资源, 构造过程如下 : 1. 以空字符串开头 ( ) 2. 加上 Bucket 的名称 3. 加上未解码 (un-decoded) 的 HTTP 请求 URI, 截止到查询字符串 (query string) 之 前 4. 若请求的资源类型是子资源 (sub-resource), 则加上子资源的名称 这些子资源包括 : lifecycle,location,logging,partnumber,policy,uploadid,uploads,versionid, versioning,versions,website 等 时间戳 每一个认证的请求都必须包含一个有效的时间戳,HTTP Header Date 或者 x-jd-date 客户端提供的时间戳和京东云存储服务器的本地时间相差不得超过 15 分钟, 否则服务器会 拒绝该请求, 且返回 RequestTimeTooSkewed 错误 通过这种方式可以有效防止请求重放, 盗链等恶意攻击 一些 HTTP Client 库并不提供显式设置 HTTP Header Date 的方式, 如果此时不能准确 的组合 StringToSign 中 Date 的值, 可以通过设置 Http Header x-jd-date 的方式来取代 HTTP Header Date, 其格式与 Date 相同, 必须为 RFC 2616 格式中的一种 ( 如果通过 x-jd-date 来代替 Date 提供时间戳, 则在构 造 StringToSign 时, 应忽略 Date 并以空字符串 ( ) 代替 例子 下面的例子使用表格中的 AccessKey 与 SercetKey 进行 HMAC-SHA1 计算

12 AccessKey 9c379f fad2959c4621cd6feVb797oH1 SercetKey 5e998dbbafb44ca783099afcdead40fa7A3Vf7Fh Put Bucket 请求 Request PUT /ab52b c03-906f-8b80e7e0c130 Date: Wed, 22 May :05:58 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:5IGUVXmvjWCJfkR DH7G+/gyIsf8= StringToSign PUT \n \n Wed, 22 May :05:58 GMT 906f-8b80e7e0c130 Del Bucket 请求 Request DELETE /ab52b c03-906f-8b80e7e0c130 Date: Wed, 22 May :05:58 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:vKCbKp/kKY/qKb4w NPqWywbh0qE= StringToSign DELETE \n \n Wed, 22 May :05:58 GMT /ab52b c03- /ab52b c03-906f-8b80e7e0c130 Put Object Request StringToSign

13 PUT /7d84df14-6e bd eacc5/24b1c9ba-c889-4a76-8edc-b d8fa7e417dc Content-MD5: 670f34c390bd3deb23c ad Content-Type: application/octet-stream Date: Wed, 22 May :37:02 GMT Authorization:jingdong 9c379f fad2959c4621cd6feVb797oH1:J6yRNUPxjixPsJusHu Hk0JNK1Lo= 4b1c9ba-c889-4a76-8e dc-bd8fa7e417dc Get Object Request StringToSign GET /7d84df14-6e bd eacc5/24b1c9ba-c889-4a76-8edc-b d8fa7e417dc Date: Wed, 22 May :37:02 GMT Authorization:jingdong 9c379f fad2959c4621cd6feVb797oH1:domGmvXwG2i3Vpri 9+J12zLnMtI= PUT 670f34c390bd3deb23c ad application/oc tet-stream Wed, 22 May :37:02 GMT /7d84df14-6e bd eacc5/2 GET \n \n Wed, 22 May :37:02 GMT /7d84df14-6e bd eacc5/2 4b1c9ba-c889-4a76-8e dc-bd8fa7e417dc 4.2 构造基于查询字符串的认证请求 概要 除了前面提到的认证方式之外, 京东云存储还提供了一种基于查询字串 (Query String)

14 的认证方式, 即通过查询字符串来指定 AccessKey,Signature 等信息来构造认证请求 这 样的好处是可以使第三方用户, 直接通过浏览器来访问你存储中未公开的数据 具体办法是, 通过预签名的方式, 生成一个带有认证信息的 URL, 并将它分发给第三 方用户 通常, 你需要为这个 URL 指定一个过期时间 下面是一个基于查询字符串的认证的 URI: fad2959c4621cd6feVb797oH1&Sigature=tzEQUA%2Bj%2BUHcEp%2FBUMKeMd 5bqGc%3D 基于查询字符串的认证请求不需要任何特殊的 HTTP Header, 它通过查询字符串来指 定认证信息 查询字符串参数样例值描述 AccessKey 9c379f fad2959c4621cd6feVb797oH1 你的 AccessKey Expires URL 的过期时 间, 为距离 UTC 时区 1970 年 1 月 1 日 0 时的秒数, 超过该 时间的请 Signature tzequa%2bj%2buhcep%2fbumkemd5bqgc%3d 求都会被拒绝 经过 URL-Encoding 编 码之

15 后的 Signature 构造基于查询字符串认证请求的签名与基于 HTTP Header 的传统方式有一些不同, 可 以参考下面的伪代码 : Signature = URL-Encode(Base64(HMAC-SHA1(UTF-8-Encoding-Of(YourSecretKey, StringToSign)))); StringToSign = HTTP-Verb + "\n" + Content-MD5 + "\n" + Content-Type + "\n" + Expires + "\n" + CanonicalizedAHeaders + CanonicalizedResource; 主要的不同有两点 : 1. 需要对计算出来的签名进行 URL-Encode 编码 2. 将 StringToSign 中的 Date 换成 Expires 例子 下面的例子使用表格中的 AccessKey 与 SercetKey 进行 HMAC-SHA1 计算 AccessKey 9c379f fad2959c4621cd6feVb797oH1 SercetKey 5e998dbbafb44ca783099afcdead40fa7A3Vf7Fh GET Object 请求 Request StringToSign GET /mybucket/public/index.html?expires= &accesskey=9c 379f fad2959c4621cd6feVb797oH1&Sigature=tzEQUA%2Bj %2BUHcEp%2FBUMKeMd5bqGc%3D GET \n \n

16 /mybucket/public/inde x.html

17 五 REST API 京东云存储服务提供开放的 REST 风格的 HTTP API, 其域名是 storage.jcloud.com, 用户可以通过该 API 来将自己的数据上传至京东云存储, 也可以通过 API 下载京东云存 储中的数据 京东云存储服务的域名 : storage.jcloud.com 5.1 错误响应 错误代码列表 错误码 Http 状态码描述 AccessDenied AccountProblem 403 Forbidden 403 Forbidden 访问被拒绝 帐号被冻结, 通常是流量超标 BadDigest 400 Bad Request 或者其他原因引起 提供的 Content-MD5 值与 BucketAccessDenied BucketAlreadyExists 403 Forbidden 409 Conflict 服务端计算的不匹配 没有权限访问目标 Bucket 要创建的 Bucket 已存在, Bucket 名称全局唯一, 请重 BucketNotEmpty EntityTooLarge IncompleteBody 409 Conflict 400 Bad Request 400 Bad Request 新选择要删除的 Bucket 不为空上传的数据大小超过了限制上传的数据大小小

18 InvalidBucketName 400 Bad Request 于 HTTP Header 中的 Content-Length 要创建的 Bucket 名称不合 KeyTooLong MissingContentLength NoSuchBucket NoSuchKey TooManyBuckets 400 Bad Request 411 Length Required 404 Not Found 404 Not Found 400 Bad Request 法 Object Key 长度过长缺少 HTTP Header Content-Length 请求的 Bucket 不存在请求的 Object 不存在要创建的 Bucket 数目超过 RequestTimeTooSkewed 403 Forbidden 了极限 请求的时间戳与服务器本地 时间差距过大, 被拒绝 InvalidPart 400 Bad Request Complete Multipart Upload 时,HTTP 请求中的 Part 在云 存储中找不到, 可能这些 Part 没有被上传 InvalidEntity 400 Bad Request HTTP 请求的 Entity 无效 InvalidPartNumber 400 Bad Request Complete Multipart Upload 时, HTTP 请求中的 Partnumber 在规定范围外

19 错误相应结构 在与 API 交互有错误发生时, 云存储服务端的响应 (Response) 包括 : 1. 相应的 HTTP 3xx,4xx 与 5xx 状态码 (HTTP Status) 2. XML 或 JSON 格式的消息体 下面是 XML 样例 <error> <code>accessdenied</code> <message>access Denied</message> <resource>/</resource> <requestid>99e64c ad-9049-d56eae83cb91</requestid> </error> 下面是 JSON 样例 { code : AccessDenied, message : Access Denied, resource : /mybucket/public/index.html, requestid : E06D-406F-81C4-E0 3FA635B831 } 服务端返回 JSON 或者 XML 取决于客户端 Http Request Header 的 Accept 的值, 如果希 望返回 XML, 请设置 Accept 的值为 :application/xml 否则默认返回 JSON 下面的表格中介绍了每一个元素 (Element) 的意义 : 名称 描述 code message RequestId Resource 错误代码错误消息的描述, 可以通过此信息来初步定位问题所在 标识请求的唯一 ID 包含了 Bucket 或 Object 的请求资源描述符

20 5.2 API 接口 通用请求头 下面的表格是访问京东云存储 API 的通用请求头 (HTTP Headers): 名称描述必须 Authorization Content-Length Content-Type Date Host 请求的验证信息消息体的长度,PUT 请求必要 资源的类型, 例如 :text/plain 请求的时间戳, 例如 :Mon, 23 Feb :14:57 GMT 值应该是 storage.jcloud.com,http/1.1 协议必要,HTTP/1.0 是部分否是部分 协议选填 通用响应头 下面的表格是京东云存储 API 的返回的通用响应头 (HTTP Headers) 名称 描述 Content-Length Connection Date 响应消息体长度 标识 HTTP Connection 的状态,Open 或者 Closed 云存储服务器响应本次请求的时间戳, 例如 Wed, 22 May :29:49 GMT ETag ETag 是云存储中 Object 的 Hash 值, 其仅反映 Object 的数据 内容, 而不包括元数据 (Metadata) 需要注意的是 ETag 不一定

21 是一个 MD5 值, 当 PUT Object 操作完成时, 服务端会为收到的 数据生成 MD5 摘要作为其 ETag 而对于 Multipart Upload 产 生的 Object, 其 ETag 并不是内容的 ContentMD5 x-jss-request-id 本次请求的唯一标识 若有错误发生时, 客户可将该 ID 告诉京东 云存储来帮助定位问题 x-powered-by 固定值为 JingdongStorageService, 表示该请求是由京东云存储完成 Bucket 相关接口 Get Service 描述 可以通过该操作来列出客户所有的 Bucket 信息 Requests: Syntax GET /HTTP/1.1 Date: date Authorization: signaturevalue Response: 返回的 header 见 5.2.2; 初始化成功, 返回的 Body 是 json 格式 详见 example Response elements: 名称 描述 Bucket Bucket 的名称 CreationDate Bucket 创建的时间戳 Example:

22 Request: GET / Date: Thu, 11 Jul :29:09 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:T9catk8sYiAlEwHHm2aRV5WRpnQ= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Response: 200 Server: nginx/1.2.7 Date: Thu, 11 Jul :32:30 GMT Content-Type: application/json;charset=utf-8 Content-Length: 1951 Connection: keep-alive {"Buckets":[{"Name":"jwt.jcloud.com.jssbuket","CreationDate":"Thu, 20 Jun :33:45 GMT","Location":"beijing"},{"Name":"jindong","CreationDate":"Thu, 20 Jun :22:45 GMT","Location":"beijing"},{"Name":"code.jd.com","CreationDate":"Tue, 25 Jun :25:45 GMT","Location":"beijing"},{"Name":"test866ad","CreationDate":"Tue, 25 Jun :38:08 GMT","Location":"beijing"},{"Name":"zxq-test-bucket","CreationDate":"Tue, 25 Jun :08:41 GMT","Location":"beijing"},{"Name":"storage-script","CreationDate":"Wed, 26 Jun :42:37 GMT","Location":"beijing"},{"Name":"boss.jd.com","CreationDate":"Tue, 25 Jun :49:44 GMT","Location":"beijing"},{"Name":"bucketname1","CreationDate":"Tue, 25 Jun :39:27 GMT","Location":"beijing"},{"Name":"bucketname2","CreationDate":"Tue, 25 Jun :43:35 GMT","Location":"beijing"},{"Name":"liningbo","CreationDate":"Tue, 25 Jun :48:57 GMT","Location":"beijing"},{"Name":"dengliang","CreationDate":"Thu, 27 Jun :00:24 GMT","Location":"beijing"},{"Name":"storage-pic-cast1","CreationDate":"Thu, 27 Jun :49:11 GMT","Location":"beijing"},{"Name":"cloudtest-apk","CreationDate":"Fri, 28 Jun :28:34 GMT","Location":"beijing"},{"Name":"sunyansd","CreationDate":"Mon, 01 Jul :06:20 GMT","Location":"beijing"},{"Name":"jxqstu3","CreationDate":"Fri, 05 Jul :13:16 GMT","Location":"beijing"},{"Name":"yangxuanjia.com.cn","CreationDate":"Fri, 05 Jul :08:30 GMT","Location":"beijing"},{"Name":"dengliangtest","CreationDate":"Tue, 02 Jul :47:45 GMT","Location":"beijing"},{"Name":"adf1","CreationDate":"Wed, 03 Jul :32:17 GMT","Location":"beijing"},{"Name":"bucketname21","CreationDate":"Thu, 04 Jul :44:33 GMT","Location":"beijing"},{"Name":"cloudtest-picture","CreationDate":"Sat, 06 Jul :38:57 GMT","Location":"beijing"},{"Name":"cloudtest-normal-log","CreationDate":"Sat, 06 Jul :38:58 GMT","Location":"beijing"}]}

23 Put Bucket 描述 该操作可以创建一个新的 Bucket Request: Syntax PUT /BucketName HTTP/1.1 Date: date Authorization: signaturevalue Response: 返回的 header 见 5.2.2; 返回 body 为空 Example: Request: PUT /testbucket Date: Thu, 11 Jul :57:38 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:wG7zP5ittOVhXEKemmEUK9tbVTg= Content-Length: 0 Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Response: 200 Server: nginx/1.2.7 Date: Thu, 11 Jul :00:59 GMT Content-Length: 0 Connection: keep-alive Delete Bucket

24 描述 删除 URI 所指定的 Bucket, 删除该 Bucket 之前, 必须确保该 Bucket 中没有任何数据 Request: Syntax DELETE /BucketName HTTP/1.1 Date: date Authorization: signaturevalue Response: 返回的 header 见 5.2.2; 返回的 Body 为空 Example: Request: DELETE /testbucket Date: Thu, 11 Jul :08:08 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:atST2N3UyucwTw/YSaknYMBy5A4= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Response: 204 Server: nginx/1.2.7 Date: Thu, 11 Jul :11:30 GMT Connection: keep-alive Get Bucket (List Objects) 描述 该操作可以获得指定 Bucket 中的 Object 信息列表, 请求时可以通过一些查询条件来限制返 回的结果 Request:

25 Syntax GET /BucketName HTTP/1.1 Date: date Authorization: signaturevalue Request element 名称描述必要 marker 返回以字典序排序的 Object 信息的起始标志, 结果中不包 含 marker, 通常与 max-keys 一起使用来实现分页 max-keys 返回 Object 信息的数量, 最大 为 1000, 若有更多符合查询条 件的 Object 信息没有被返回, 则响应中会包含 HasNext 为 true 元素, 同时可以设定 marker 为本次列表最后一个 Key, 来获取其他的本次操作 未返回的 Object 信息 默认为 1000 prefix delimiter 限制返回 Object 的 Key 的前缀 分组符, 用于分组返回的 Object 的 Key 当 prefix 未指定

26 时, 从 Object 的 Key 中提取第 一个字符到第一个 delimiter 之间的字符串放在 CommonPrefixes 中返回 若指 定了 prefix, 则提取 prefix 到第 一个 delimiter 之间的字符串 放在 CommonPrefixes 中返回 Response: 返回的 header 见 5.2.2; 初始化成功, 返回的 Body 是 json 格式 Response elements: 名称 Name Delimiter Prefix MaxKeys Marker NextMarker 描述 Bucket 的名称指定的 Delimiter 分组符指定的 Object Key 的前缀指定的 Object 的数量指定的 Object 的 Key 的起始标志列出下一个集合的 Marker, 只有当用户设置 了 delimiter 且 HasNext 为 true 时才会出现, 其值可能是当前 集合中最后一个 Key, 或是 CommonPrefixes 中最后一个 Prefix

27 若用户没有设置 delimiter, 且 HasNext 为 true 时, 可以直接将返回集合中的最后一个 Key 作为列出下一个结合的 Marker HasNext 标识返回的结果是否完整 (true or false), 若符合条件的 Object 信息数量超过了指定 的 MaxKeys, 则该值为 true, 且多余的结果 也不会被返回 Contents Key LastModified ETag 包含了一个 Object 信息的容器 Object 的 Key Object 的最后修改时间 Object 的 ETag 是一个 MD5 hash 值, 其只反映 Object 内容的变化, 而不是元数据 (Metadata) Size CommonPrefixes Object 的大小 用户指定了 Delimiter 时, 该元素才会出现 用于存放分组后 Object Key 前缀 Example: Request: GET /liningbo Date: Fri, 12 Jul :49:47 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:WMlS9FnrrOz9MiWGq3D9LLxjLl0= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1)

28 Response: 200 Server: nginx/1.2.7 Date: Fri, 12 Jul :53:09 GMT Content-Type: application/json;charset=utf-8 Content-Length: 492 Connection: keep-alive {"Name":"liningbo","Prefix":null,"Marker":null,"Delimiter":null,"MaxKeys":1000,"HasNext":fals e,"contents":[{"key":"hadoop1","lastmodified":"tue, 02 Jul :11:12 GMT","ETag":"fdec55af07620fd5ecad717167d79a8c","Size": },{"Key":"pid1","LastM odified":"fri, 12 Jul :51:49 GMT","ETag":"ea88976b9952e80b702b030489f94393","Size": },{"Key":"testObject"," LastModified":"Tue, 02 Jul :42:25 GMT","ETag":"d25ebb012cdbb28a3f309ea565c56cea","Size":82}],"CommonPrefixes":[]} Object 相关接口 Put Object 描述 该操作用来上传一个新的 Object 到指定的 Bucket 中, 数据的最大长度限制为 5GB 更 大的文件建议采取分块上传 该操作为原子操作, 即操作要么成功, 要么失败, 且不存在只更新部分数据的情况, 在 存在相当 key 的情况下, 目前不支持覆盖操作 客户端可以通过 HTTP 头 Content-MD5 进行端到端验证来保证上传数据的完整性 在 上传之前, 客户端自己计算出上传数据的 Content-MD5 值, 并将其与数据一起上传至云存 储 云存储接收到数据之后, 会重新计算收到数据的 Content-MD5 值, 并与客户端提供的 Content-MD5 进行比对, 只有在 Content-MD5 匹配的情况下, 才会将数据保存至云存储, 否则服务端会返回错误使上传操作失败 Request:

29 Syntax PUT /BucketName/ObjectName HTTP/1.1 Date: date Authorization: signaturevalue Response: 返回的 header 见 5.2.2; 初始化成功, 返回的 Body 为空 Example: Request: PUT /liningbo/pid1 Content-Type: application/octet-stream Content-MD5: ea88976b9952e80b702b030489f94393 Content-Disposition: attachment; filename="pidgin tar.bz2" Date: Fri, 12 Jul :20:16 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:YyqxZ9uR1HiRS5CMYN5Alf2vJZM= Content-Length: Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) 文件内容 Response: 200 Server: nginx/1.2.7 Date: Fri, 12 Jul :23:42 GMT Content-Length: 0 Connection: keep-alive Get Object 描述 获取指定的 Object 内容 Request:

30 Syntax GET /BucketName/ObjectName HTTP/1.1 Date: date Authorization: signaturevalue Range:bytes=byte_range Request header 见 节,Range 是指定获取的 Object 数据内容 更多的信息可以参看 : Response: 返回的 header 见 5.2.2; 初始化成功, 返回的 Body 是实际的对象内容 Example: Request: GET /liningbo/pid1 Date: Fri, 12 Jul :28:41 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:ud+zLHgqpaYmQzg6j7teZUTsLUg= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Response: 200 Server: nginx/1.2.7 Date: Fri, 12 Jul :32:03 GMT Content-Type: application/octet-stream Content-Length: Connection: keep-alive ETag: "ea88976b9952e80b702b030489f94393" Last-Modified: Fri, 12 Jul :22:39 GMT Content-Disposition: attachment; filename="pid1" Accept-Ranges: bytes 文件内容

31 Delete Object 描述 删除 URI 所指定的 Object Request: Syntax GET /BucketName/ObjectName HTTP/1.1 Date: date Authorization: signaturevalue Range:bytes=byte_range Response: 返回的 header 见 5.2.2; 初始化成功, 返回的 Body 为空 Example: Request: DELETE /liningbo/pid1 Date: Fri, 12 Jul :33:06 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:uDyHrsK2+9p5INuaQA1rKjwFjlY= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Response: 204 Server: nginx/1.2.7 Date: Fri, 12 Jul :36:28 GMT Connection: keep-alive

32 Multipart Upload 相关接口 Initiate Multipart Upload 描述 该操初始化一个新的 Multipart Upload, 成功后返回一个 UploadId 用户通过该 UploadId 来进行 Multipart Upload 相关的操作, 包括上传 Multipart Upload 所属的 Part, 合并所有 Part, 终止 Multipart Upload, 列出已上传的 Part 等 Requests: Syntax POST /BucketName/ObjectName?uploads HTTP/1.1 Date: date Authorization: signaturevalue Response: 返回的 header 见 5.2.2; 初始化成功, 返回的 Body 是 json 格式 Response element Name Bucket Key UploadId Description 桶名 Type: string 对象名 Type: String 本次分块上传的 ID Type: String Examples Sample Request POST /liningbo/testobject?uploads Date: Mon, 01 Jul :13:50 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:dY2ZqYyTiXOVQl4fZ4iaXW6UybA= Content-Length: 0 Connection: Keep-Alive

33 User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Sample Response 200 Server: nginx/1.2.7 Date: Mon, 01 Jul :16:47 GMT Content-Type: application/json;charset=utf-8 Content-Length: 86 Connection: close {"Bucket":"liningbo","Key":"testObject","UploadId":"1e34f32a9d1c40ccab504b3c39074dcc"} Upload Part 描述 该操作用来上传一个的 Part 到指定的 Multipart Upload 中 在上传 Part 之前, 必须先完成 Initiate Multipart Upload 操作, 操作完成后会得到标识符 Upload Id, 该标识符唯一标识一个 Multipart Upload 在上传 Part 时应指定其关联事件的 Upload Id Part Number 的范围在 之间,Part Number 唯一标识一个 Part 和其所在 Multipart Upload 中的位置 如果你 Upload Part 时, 用了同一个 Part Number, 服务端会直接返回上传成 功, 不会替换原来的 Part 建议分块大小不小于 5M 为了保证数据的传输的正确性, 服务端会在 Part 上传成功后返回实际存储的 Part 的 MD5 值, 放在响应的 header 的 ETag 字段中, 用于客户端校验 Requests: Syntax PUT /BucketName/ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1 Date: date Content-Length: Size Authorization: signaturevalue

34 Request elements 名称描述必要 Content-Length 要上传的数据内容长度, 长度 是 Content-MD5 范围在 0 到 5GB 之间 期待上传数据的 MD5 值, 其 否 内容为 Object 内容 ( 不包含 Headers) 的 16 进制编码的 128 位 MD5 摘要 Response: 返回的 header 见 5.2.2,ETag 是本次上传的 MD5 值,16 进制表示 ; 上传成功, 返回的 Body 为空 详见 example Examples Sample Request PUT /liningbo/testobject?partnumber=1&uploadid=1e34f32a9d1c40ccab504b3c39074dcc Date: Mon, 01 Jul :21:30 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:TyozaAoj0oqsbV0TvUjmtmkyKPk= Content-Length: 30 Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) 文件内容 Sample Response 200 Server: nginx/1.2.7 Date: Mon, 01 Jul :24:27 GMT

35 Content-Length: 0 Connection: close ETag: "a46857f0ecc21f0a06ea434b94d9cf1d" Complete Multipart Upload 描述 该操作用来完成 Multipart Upload, 合并其包含的所有 Part, 并在云存储中产生一个新的 Object 当用户初始化 Multipart Upload 并上传了所有相关的 Part 之后, 你可以通过该操作完 成整个 Multipart Upload 收到该请求后, 云存储根据每一个 Part Number 的顺序, 将已经上 传的所有的 Part 合并成一个 Object 你必须保证你提供了完整有效的 Part 列表 : 所有的 Part 按照 PartNumber 升序排列, 不能有无法识别的 Part, 不能有遗漏的 Part 目前, 客户端与 服务端在 http body 中以 json 格式交互 Requests: Syntax POST /BucketName/ObjectName?uploadId=UploadId HTTP/1.1 Date: Date Content-Length: Size Authorization: signaturevalue {"Part":[{"PartNumber":PartNumberValue,"ETag":"ETagValue"},{"PartNumber":PartNumberV alue,"etag":"etagvalue"}]} request element: Name Bucket Key ETag Description 桶名 Type: string 对象名 Type: String 整块文件的 MD5 值,16 进制表示 Type: String

36 Response: Response header 见 节,response body 是 json 字符串, 其中的 ETag 字段是合并后整个 文件的 MD5 值, 用 16 进制表示, 详见 example Example: Sample Request POST /liningbo/testobject?uploadid=1e34f32a9d1c40ccab504b3c39074dcc Date: Tue, 02 Jul :40:33 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:VTOKgwBVTB63XYfDC0WtbRBl6a0= Content-Length: 128 Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) {"Part":[{"PartNumber":1,"ETag":"a54357aff0632cce46d942af68356b38"},{"PartNumber":2,"ET ag":"0c78aef83f66abc1fa1e8477f296d394"}]} Sample Response 200 Server: nginx/1.2.7 Date: Tue, 02 Jul :43:30 GMT Content-Type: application/json;charset=utf-8 Transfer-Encoding: chunked Connection: close {"Bucket":"liningbo","Key":"testObject","ETag":"d25ebb012cdbb28a3f309ea565c56cea"} Abort Multipart Upload 描述 该操作用来终止一个 Multipart Upload 当一个 Multipart Upload 被终止后, 其 UploadId 也一同作废, 且该 Multipart Upload 中的所有 Part 所占用的存储空间都会被释放 Requests: Syntax DELETE /BucketName/ObjectName?uploadId=UploadId HTTP/1.1

37 Date: Date Authorization: signaturevalue Responses Response Headers 见 Response body: 空. Example: Sample Request DELETE /liningbo/myobject?uploadid=129a345df24d46ffb1c111cb6c375f80 Date: Tue, 02 Jul :45:20 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:EyXc7mzCkF5OGk7GM73IZnxgJ6M= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Sample Response 204 Server: nginx/1.2.7 Date: Tue, 02 Jul :48:16 GMT Connection: close List Parts 描述 该操作用来列出一个 Multipart Upload 中已经上传的 Part 该操作必须指定 UploadId, 返回的 Part 数量最大为 1000 你可以通过设置查询字符串 参数 max-parts 来限定返回 Part 的数量, 默认为 1000 若符合条件的结果超过 1000,Response 结构中的会包含 NextPartNumberMarker 元素以及值为 true 的 HasNext 元素 此时你可以通

38 过设置查询字符串参数 part-number-marker 为 NextPartNumberMarker 来列出下一个 Part 集合 Requests: Syntax GET /BucketName/ObjectName?uploadId=UploadId HTTP/1.1 Date: Date Authorization: signaturevalue Request elements 名称描述必要 uploadid max-parts Multipart Upload 的 Id 返回 Part 的数量 是 否 part-number-marker 返回 Part 的起始标志, 只有 否 PartNumber 大于该参数的 Part 才会被返回 Responses Response Headers 见 Response Body Json 格式的字符串, 详见 example Response Elements Name Bucket Key UploadId Description 桶名 Type: string 对象名, 即 Object 的 Key Type: String Multipart Upload 的 Id Type: String

39 PartNumberMarker NextPartNumberMarker 返回 Part 的起始标志 Type: Integer 当 HasNext 为 true 时, 返回的结果会包含该 值, 此时可以通过设置查询字符串参数 part-number-marker 为该值来列出下一个 Part 集合 Type: Integer MaxParts 返回 Part 的数量, 最大为 1000, 默认为 1000 Type: Integer HasNext 标识返回的结果是否完整 (true or false), 若符合条件的 Part 数目超过了指定的 MaxParts, 则该值为 True, 且多余的结果也不 会被返回 Type: bool Part PartNumber LastModified ETag Size 包含了一个 Part 信息的容器 Type: String Part 的标识 Type: Date Part 的上传时间 Type: Date Part 的 ETag Type: String Part 内容的长度 Type: Integer Example: Sample Request GET /liningbo/testobject?uploadid=1e34f32a9d1c40ccab504b3c39074dcc Date: Mon, 01 Jul :39:46 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:atYBHOsWYBSz0cpbMpUYsSmorYs= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1)

40 Sample Response 200 Server: nginx/1.2.7 Date: Mon, 01 Jul :42:42 GMT Content-Type: application/json;charset=utf-8 Content-Length: 407 Connection: close {"Bucket":"liningbo","Key":"testObject","UploadId":"1e34f32a9d1c40ccab504b3c39074dcc","Pa rtnumbermarker":0,"nextpartnumbermarker":null,"maxparts":1000,"hasnext":false,"part":[{"p artnumber":1,"lastmodified":"mon, 01 Jul :24:27 GMT","ETag":"a46857f0ecc21f0a06ea434b94d9cf1d","Size":30},{"PartNumber":2,"LastModifie d":"mon, 01 Jul :25:43 GMT","ETag":"55032b1ba8bc84b c8a48ea031","Size":52}]} List Multipart Uploads 描述 该操作可以列出还未完成的 Multipart Upload, 请求时可以通过一些查询条件来限制返 回的结果 该操作最多返回 1000 个 Multipart Upload 你也可以通过设置查询字符串参数 max-uploads 来限制返回 Multipart Upload 的数量, 如果符合查询条件的结果超过 1000 个, 则返回 Response 的结构中 HasNext 元素值为 true, 此时可以通过设置查询字符串参数 key-marker 和 upload-id-marker 来获取更多的 Multipart Upload 返回的结果按照 Key 和 UploadId 的字典序排序, 如果你对同一个 Key 初始化了多个 Multipart Upload, 则其结果先按照 Key 排序, 再按照 UploadId 排序 Requests: Syntax GET /BucketName?uploads HTTP/1.1 Date: Date Authorization: signaturevalue Request elements:

41 名称描述必要 key-marker 与 upload-id-marker 一起使用, 用来设置返回 Multipart Upload 否 的起始 Key 如果 upload-id-marker 没有指定, 则只有 Multipart Upload 的 key 的字典序大于 key-marker 时才会被返回 如果指定了 upload-id-marker, 那么 key 等于 key-marker 的 Multipart Upload 也会被返回, 且在该条件下, 返回 Upload Id upload-id-marker 字典序大于 upload-id-marker 的 Multipart Upload 与 key-marker 一起使用, 若 key-marker 没有指定, 则忽略该参 否 数 若与 key-marker 同时指定, 那么 key 等于 key-marker 的 Multipart Upload 也会被返回, 且在该条件下, 返回 Upload Id max-uploads prefix delimiter 字典序大于 upload-id-marker 的 Multipart Upload 返回 Multipart Upload 信息的数量, 最大为 1000 限制返回 Multipart Upload 中 Object 的 Key 的前缀分组符, 用于分组返回的 Object 的 Key 当 prefix 未指定时, 从 否 否 否 Object 的 Key 中提取第一个字符到第一个 delimiter 之间的字符 串放在 CommonPrefixes 中返回 若指定了 prefix, 则提取 prefix 到第一个 delimiter 之间的字符串放在 CommonPrefixes 中返回, 具体使用请参看后面的例子 Responses Response Headers: 见 节

42 Response Body: Json 格式的字符串, 详见 example Response Elements Name Bucket Delimiter Prefix KeyMarker UploadIdMarker NextKeyMarker Description 桶名 Type: string 指定的 Delimiter 分组符 Type: String 指定的 Object Key 的前缀 Type: String 指定的 KeyMarker Type: String 指定的 UploadIdMarker. Type: String 当 HasNext 为 true 时, 利用该值和 NextUploadIdMarker 来列出下一个集合.Type: String NextUploadIdMarker 当 IsTruncated 为 true 时, 利用该值和 NextKeyMarker 来列出下一个集合.Type: String MaxUploads HasNext 指定的 Multipart Upload 的数量 Type: Integer 标识返回的结果是否完整 (true or false), 若符合条件的 Multipart Upload 数目超过了指 定的 MaxUploads, 则该值为 True, 且多余的 结果也不会被返回 Type: bool Upload 包含了一个 Multipart Upload 信息的容器 Type: Container

43 Key 某个分块上传关联的对象名称, 即 Object 的 Key.Type: Integer UploadId Initiated CommonPrefixes Multipart Upload 的 Id. Type: Integer multipart upload 初始化的时间 Type: Date 用户指定了 Delimiter 时, 该元素才会出现 用于存放分组后 Object Key 前缀 Type: Container Example: Sample Request GET /liningbo?uploads Date: Tue, 02 Jul :30:29 GMT Authorization: jingdong 9c379f fad2959c4621cd6feVb797oH1:uRQYWRPSAckYCyAwVWd4hK+BW1k= Connection: Keep-Alive User-Agent: JSS-SDK-JAVA/1.1.0 (Java 1.7.0_21; Vendor Oracle Corporation; Linux generic; HttpClient 4.2.1) Sample Response 200 Server: nginx/1.2.7 Date: Tue, 02 Jul :33:26 GMT Content-Type: application/json;charset=utf-8 Content-Length: 419 Connection: close {"Bucket":"liningbo","Delimiter":null,"Prefix":null,"KeyMarker":null,"UploadIdMarker":null,"N extkeymarker":null,"nextuploadidmarker":null,"maxuploads":2,"hasnext":false,"upload":[{" Key":"myObject","UploadId":"129a345df24d46ffb1c111cb6c375f80","Initiated":"Tue, 02 Jul :31:59 GMT"},{"Key":"testObject","UploadId":"1e34f32a9d1c40ccab504b3c39074dcc","Initiated":"Mo n, 01 Jul :16:47 GMT"}],"CommonPrefixes":[]}