本篇介绍如何向七牛云存储上传单个文件，限于篇幅，将分成原理与实践两部分。
为便于阅读、编写和执行程序，选定Ruby 2.1.0作为服务端实践编程语言，视场景需要穿插其它编程工具（如HTML）的对应实现。为防止Ruby语法对理解程序逻辑产生不良影响，会尽量将代码组织成伪码形式。
■ 接口形式
七牛云选择HTTP协议作为基准接口形式，以便实现跨越互联网的远程调用，减少防火墙、中间路由器带来的意外影响。在此基准之上，根据不同的功能实现，会选择不同的数据组织格式。本篇及后续文章均假定读者已经熟悉HTTP协议。
通常，对于一个HTTP请求报文，有如下三个点需要注意：
- URI与QueryString部分，用于指定功能名称与相关参数；
- Header部分，用于指定必要的非功能参数；
- Body部分，用于组织上传数据或其它信息。
相应的，对于一个HTTP响应报文，也有如下三个点需要注意：
- 响应状态码，指明服务器的执行结果状态；
- Header部分，包含有影响缓存、资源元信息等必要的设定值；
- Body部分，对于查询类请求将返回以JSON格式组织的状态和信息数据，对于下载类请求将返回实际数据。
■ /upload接口
本接口实现直观的单文件直传功能。为达到最大程度的普适性，使用multipart/from-data格式组织上传数据。
一个上传请求报文至少需要包含如下两项信息：
- 上传授权凭证（UploadToken）；
- 文件内容（FileContent）与原始文件名（FileName）。
下面是可用的、最小且完整的上传请求报文模板：
POST / HTTP/1.1
Host: up.qiniu.com
Content-Type: multipart/form-data; boundary=<Boundary>
Content-Length: <MultipartContentLength>
--<Boundary>
Content-Disposition: form-data; name="token"
<UploadToken>
--<Boundary>
Content-Disposition: form-data; name="file"; filename="<FileName>"
<FileContent>
--<Boundary>--
■ 上传授权凭证
本质上，上传并不需要授权，无非是把一团数据发送给服务器。但对于用户而言，任何知晓上传原理的第三方都可能滥用该功能，向服务器提交垃圾数据，或是伪造/篡改数据，侵占存储空间，导致业务风险。因此七牛云使用上传授权凭证（称为UploadToken）来控制谁在什么时刻之前向哪个存储空间上传文件，避免业务风险。
一个有效的上传授权凭证由三部分组成：
<AccessKey>:<EncodedSign>:<EncodedPutPolicy>
其中，
-
<AccessKey>用于指明谁在发起上传（即开发者账号）； -
<EncodedSign>是UrlSafe-Base64编码的上传策略的加密签名，防止信息被伪造或篡改。签名算法将在实践篇中解释； -
<EncodedPutPolicy>是经过UrlSafe-Base64编码的上传策略信息，用于指明上传截止时刻与目标存储空间。
■ 上传策略
上传策略是以JSON格式组织的数据对象，用于指定上传请求的各项参数。一个最小的完整示例如下：
{
"scope": "qiniu-ts-demo",
"deadline": 1388506200
}
其中，
-
scope字段指明目标存储空间的名字； -
deadline字段指明上传授权有效期的截止时间，是一个UNIX时间戳，单位为秒，示例值对应的时刻为"2014-01-01 00:10:00"（在Linux上可以执行date -d"2014-01-01 00:00:00 10 minutes" +"%s"得到该值）。
还可以在上传策略中指定某些可以影响上传行为的微调参数，后续文章会进行细节解释，此处不再展开。
■ 咱们行进到哪儿了？
至此，读者应该清楚了解向七牛云存储上传一个文件需要准备哪些必需信息。下一篇文章将进行编程实践。
七牛云存储 © 2014 署名-非商业性使用-禁止演绎
允许自由转载，请注明作者及出处。
