七牛雲試用指南－單文件直傳（原理）

本篇介紹如何向七牛雲存儲上傳單個文件，限於篇幅，將分紅原理與實踐兩部分。

爲便於閱讀、編寫和執行程序，選定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 署名-非商業性使用-禁止演繹

容許自由轉載，請註明做者及出處。