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

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

为便于阅读、编写和执行程序，选定Ruby 2.1.0做为服务端实践编程语言，视场景须要穿插其它编程工具（如HTML）的对应实现。为防止Ruby语法对理解程序逻辑产生不良影响，会尽可能将代码组织成伪码形式。

■ 接口形式

七牛云选择HTTP协议做为基准接口形式，以便实现跨越互联网的远程调用，减小防火墙、中间路由器带来的意外影响。在此基准之上，根据不一样的功能实现，会选择不一样的数据组织格式。本篇及后续文章均假定读者已经熟悉HTTP协议。

一般，对于一个HTTP请求报文，有以下三个点须要注意：

1. URI与QueryString部分，用于指定功能名称与相关参数；
2. Header部分，用于指定必要的非功能参数；
3. Body部分，用于组织上传数据或其它信息。

相应的，对于一个HTTP响应报文，也有以下三个点须要注意：

1. 响应状态码，指明服务器的执行结果状态；
2. Header部分，包含有影响缓存、资源元信息等必要的设定值；
3. 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>

其中，

1. <AccessKey>用于指明谁在发起上传（即开发者帐号）；
2. <EncodedSign>是UrlSafe-Base64编码的上传策略的加密签名，防止信息被伪造或篡改。签名算法将在实践篇中解释；
3. <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 署名-非商业性使用-禁止演绎

容许自由转载，请注明做者及出处。