表單上傳功能適用于文件內容可以在一次HTTP請求即可傳遞完成的場景。該功能非常適合于在瀏覽器中使用HTML表單上傳資源，或者在不需要處理復雜情況的客戶端開發中使用。
開發者只要組裝一個符合**HTML文件上傳表單**規范（參見[RFC1867](http://www.ietf.org/rfc/rfc1867.txt)）的HTTP請求，并以POST方式向域名`upload.qiniu.com`發起這個請求，即可將指定文件上傳到服務端。業務邏輯非常簡單明了。
## 使用方法
我們可以用如下的HTML表單來描述表單上傳的基本用法：
~~~
<form method="post" action="http://upload.qiniu.com/"
enctype="multipart/form-data">
<input name="key" type="hidden" value="<resource_key>">
<input name="x:<custom_name>" type="hidden" value="<custom_value>">
<input name="token" type="hidden" value="<upload_token>">
<input name="file" type="file" />
<input name="crc32" type="hidden" />
<input name="accept" type="hidden" />
</form>
~~~
HTML表單上傳的幾個關鍵參數說明如下：
| 名稱 | 類型 | 必填 | 說明 |
| --- | --- | --- | --- |
| token | string | 是 | 必須是一個符合相應規格的[上傳憑證](http://developer.qiniu.com/docs/v6/api/reference/security/upload-token.html)，否則會返回401表示權限認證失敗。 |
| file | file | 是 | 文件本身。 |
| key | string | 否 | 資源名，必須為UTF-8編碼。`注:`?如果在生成上傳憑證的[上傳策略](http://developer.qiniu.com/docs/v6/api/reference/security/put-policy.html)?中?`scope`指定為：`<bucket>:<key>`, 則該字段也必須指定。 |
| x: | string | 否 | [自定義變量](http://developer.qiniu.com/docs/v6/api/overview/up/response/vars.html#xvar)，必須以?`x:`?開頭命名，不限個數。里面的內容將在?`callbackBody`?參數中的?`$(x:custom_field_name)`?求值時使用。 |
| crc32 | string | 否 | 上傳內容的 CRC32 校驗碼。如填入，則七牛服務器會使用此值進行內容檢驗。 |
| accept | string | 否 | 當 HTTP 請求指定?`Accept`?頭部時，七牛會返回的?`Content-Type`?頭部的值。該值用于兼容低版本 IE 瀏覽器行為。低版本 IE 瀏覽器在 multiform 返回?`application/json`?的時候會表現為下載，返回`text/plain`?才會顯示返回內容。 |
上傳過程在一個HTTP請求和響應中完成，因此該過程將阻塞直到文件傳輸成功完成或失敗為止。如果文件較大，或者網絡環境較差，可能會導致HTTP連接超時而上傳失敗。若發生這種情況，開發者需要考慮換用更安全但也相對復雜的[分片上傳](http://developer.qiniu.com/docs/v6/api/overview/up/chunked-upload.html)功能。
提交以上這個HTML表單而生成的HTTP請求內容大致如下所示：
~~~
POST http://upload.qiniu.com/
Content-Type: multipart/form-data; boundary=<Boundary>
--<Boundary>
Content-Disposition: form-data; name="key"
<resource_key>
--<Boundary>
Content-Disposition: form-data; name="x:<custom_field_name>"
<custom_value>
--<Boundary>
Content-Disposition: form-data; name="token"
<upload_token>
--<Boundary>
Content-Disposition: form-data; name="file"; filename="[文件名]"
Content-Type: <MimeType>
[文件內容]
--<Boundary>--
~~~
在非網頁開發的場景中，開發者完全可以自行組裝這個HTML表單請求。考慮到各個平臺上的網絡庫都已經對HTML文件上傳表單有非常完整的支持，組裝這個請求的過程將會非常輕松。
## 后續動作
我們可以在生成上傳憑證時指定一系列的參數，以控制服務器在文件上傳完成后的后續動作。我們將在[上傳后續動作](http://developer.qiniu.com/docs/v6/api/overview/up/response/)中詳細描述各種參數的用法和作用。
另外如果需要，我們可以在表單參數中增加一系列的[魔法變量](http://developer.qiniu.com/docs/v6/api/overview/up/response/vars.html#magicvar)和[自定義變量](http://developer.qiniu.com/docs/v6/api/overview/up/response/vars.html#xvar)。上述表單例子中的``就是變量的使用方法示意。我們可以將其更換為一系列魔法變量或自定義變量。
變量將會在回調和自定義返回內容中起到極大的作用。具體用法請參見[回調](http://developer.qiniu.com/docs/v6/api/overview/up/response/callback.html)和[自定義返回內容](http://developer.qiniu.com/docs/v6/api/overview/up/response/response-body.html)對應的使用方法描述。
