七牛云试用指南－单文件直传（原理）

本篇介绍如何向七牛云存储上传单个文件，限于篇幅，将分成原理与实践两部分。

为便于阅读、编写和执行程序，选定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" 得到该值）。

还可以在上传策略中指定某些可以影响上传行为的微调参数，后续文章会进行细节解释，此处不再展开。