七牛雲存儲Python SDK使用教程 - 上傳策略詳解

本教程旨在介紹如何使用七牛的Python SDK來快速地進行文件上傳，下載，處理，管理等工做。

前言

咱們在上面的兩節中瞭解到，客戶端上傳文件時，須要從業務服務器申請一個上傳憑證(Upload Token)，而這個上傳憑證是業務服務器根據上傳策略(PutPolicy)來生成的，而這個生成過程當中還必須使用到AccessKey和SecretKey。

咱們從上面的簡單示意圖中能夠看到：

1. 上傳客戶端向業務服務器申請一個上傳憑證(Upload Token)
2. 業務服務器返回一個上傳憑證給上傳客戶端
3. 上傳客戶端構建上傳請求，上傳文件到七牛雲存儲服務器
4. 七牛雲存儲服務器返回客戶端文件上傳的結果。

固然了，在咱們前面的例子以及後面的例子中，上傳客戶端和業務服務器是一個，可是從業務模型來說，第1步和第2步仍是分開的(好比在網頁端上傳或者移動APP端上傳中)。

上傳策略

咱們要研究七牛的上傳策略，必需要了解它的全部的支持的參數(一共也很少)。文檔:戳這裏。
不少人可能第一眼看上去，感受參數好多啊，頭就大了，其實否則，對付多的東西，最好的辦法就是分組，把參數按照功能不一樣進行分組。好比對於上傳策略咱們能夠分爲如下幾組：

基本參數

基本參數包括文件上傳後存儲的空間，文件的上傳模式(是否支持覆蓋上傳)，上傳憑證的過時時刻，業務服務器指定上傳文件的名字等。

參數名	說明
scope	上傳的空間bucket，或者是bucket:key(用於支持文件覆蓋上傳)。
deadline	上傳憑證的失效時刻的時間戳，通常sdk裏面會用參數expires來設置，就是deadline = now()+expires其中單位都是秒。
insertOnly	默認爲0，配合scope=bucket:key能夠支持覆蓋上傳，若是爲1，則表示強制上傳的語義是新建，遇到文件存在則返回file exists錯誤。
saveKey	業務服務器能夠利用這個參數來指定上傳文件在七牛雲存儲所保存的名字(僅在上傳客戶端沒有指定請求參數key的狀況下生效)。
endUser	能夠用來標註文件上傳端設備的信息，好比手機類型，系統類型什麼的。

自定義上傳回復

默認狀況下，七牛雲存儲返回給上傳客戶端的信息只包括了文件的hash和key，就像咱們前面看到過的那樣：

{"hash":"FoaI_ZzokcGpZA48PVJPFNJvLoNc","key":"FoaI_ZzokcGpZA48PVJPFNJvLoNc"}

那麼有沒有辦法，擴充這個單薄的返回信息呢？

答案固然是：有！

參數名	說明
returnBody	能夠用來自定義上傳的回覆內容，支持魔法變量和自定義變量(又稱爲擴展變量)，關於變量詳見文檔:戳這裏

上傳完成重定向

上傳客戶端在文件上傳完成以後，從七牛雲存儲服務器那裏獲取上傳結果的回覆。這個過程當中，沒有再涉及到業務服務器，可是若是我但願文件上傳以後，七牛服務器能不能告訴業務服務器一點信息呢？固然是能夠的，其中一種方法就是頁面重定向，頁面重定向固然得知道重定向的地址(returnUrl)了，另外重定向到新的地址攜帶的參數內容能夠經過returnBody來設置。

在文件上傳完成以後，七牛返回給上傳端303的狀態碼，而後上傳端能夠重定向到returnUrl所指定的地址，好比重定向到http://.../service/return_upload_service?upload_ret=eyJmbmFtZSI6InVwbG9hZF9kcmFmdC5wbmciLCJldGFnIjoiRnNOM0g4eS15NGxzcV9jZ2p0NEQ3a2E5cjVmUSIsImtleSI6IkZzTjNIOHkteTRsc3FfY2dqdDREN2thOXI1ZlEiLCJleFBhcmFtMSI6ImhlbGxvIiwiZXhQYXJhbTIiOiJxaW5pdSIsImV4UGFyYW0zIjoicWluaXUifQ==這樣的地址，而這裏的returnUrl設置爲http://.../service/return_upload_service，而重定向地址攜帶的參數upload_ret的內容則是由returnBody來指定的，看上去upload_ret好像是base64編碼吧，對的！是URL安全的Base64編碼(在七牛的應用中，所提到的base64編碼通常都是URL安全的Base64編碼)。對upload_ret作一下解碼就能獲得真正的內容。

參數名	說明
returnUrl	上傳端重定向的地址。
returnBody	上傳端重定向的時候，用來組織所攜帶的URL參數upload_ret的內容。

上傳完成回調
咱們上面看到了一種文件上傳完成以後七牛服務器和業務服務器交互的一種方式，是經過上傳端的重定向來實現的。固然這種方式有適用的場景。可是大多數狀況下，咱們都會用另一種方式來進行七牛服務器和業務服務器的交互，這種方式叫作回調(Callback)。回調是在文件上傳到七牛以後發生的，七牛會根據上傳策略裏面的參數callbackUrl指定的地址來發送一個POST請求，請求的內容則是由上傳策略裏面的callbackBody來指定的，另外還有一個callbackHost能夠用來指定某個回調的主機地址，好比ip地址，另外callbackBody的內容組織格式是由callbackBodyType來決定的。七牛服務器會根據callbackBodyType來設置發送給業務服務器的POST請求的Content-Type，目前支持application/x-www-form-urlencoded和application/json這兩種格式。

參數名	說明
callbackUrl	七牛服務器回調業務服務器的地址，必須是公網能夠訪問的地址，可以接受POST請求。
callbackBody	定義七牛服務器回調業務服務器時，POST請求的Body內容。
callbackBodyType	指定callbackBody的內容格式，支持url和json兩種格式。
callbackHost	指定具體的回調主機地址，能夠設置爲ip地址以節約DNS解析時間。

上傳完觸發持久化
咱們知道七牛支持不少圖片和音視頻處理的接口和指令，假設我但願從PC上傳一個圖片或者視頻，而後上傳完成立馬觸發七牛的文件處理指令將我上傳的文件處理爲支持不一樣平臺的文件，那麼我就可使用下面的三個參數。

參數	說明
persistentOps	數據處理指令集，之因此叫作指令集就是支持多個對原文件的處理指令，每一個指令用;鏈接起來。這裏的指令好比imageView2，avthumb，vframe等等。
persistentNotifyUrl	這個地址是用來接收七牛服務器數據處理結果的，其接收到的數據內容和利用接口prefop文檔查詢到的內容是如出一轍的格式。
persistentPipeline	指定數據處理所使用的隊列名稱，這個隊列能夠在七牛的後臺管理系統中建立。若是不指定，表示使用公用隊列，數據處理效率上可能低於指定的私有處理隊列。

文件上傳限制
咱們能夠在上傳策略裏面指定文件上傳的最大大小和容許的文件類型。

參數	說明
fsizeLimit	文件上傳的最大大小，單位爲字節(Byte)。
mimeLimit	文件上傳的類型，能夠經過容許的語義(image/jpeg;image/png，表示只容許jpeg和png格式圖片)或者不容許的語義(!application/json;text/plain，表示不容許json和純文本文件)來指定。

上傳策略和SDK

在最新版本的Python的SDK中(v7.0)，上傳策略的參數定義在auth.py裏面，以下：

_policy_fields = set([
    'callbackUrl',
    'callbackBody',
    'callbackHost',

    'returnUrl',
    'returnBody',

    'endUser',
    'saveKey',
    'insertOnly',

    'detectMime',
    'mimeLimit',
    'fsizeLimit',

    'persistentOps',
    'persistentNotifyUrl',
    'persistentPipeline',
])

咱們看一個小例子來演示，如何使用policy。

#有key上傳，限定上傳文件的大小和mimeType
def upload_with_key_and_fsizelimit_mimelimt():
    bucket = "if-pbl"
    key = "qiniu.jpg"
    filePath = "/Users/jemy/Documents/qiniu.jpg"
    auth = qiniu.Auth(accessKey, secretKey)
    policy = {
        "fsizeLimit": 1000,
        "mimeLimit": "image/png"
    }
    upToken = auth.upload_token(bucket, key=key, policy=policy)
    retData, respInfo = qiniu.put_file(upToken, key, filePath, progress_handler=progress)
    parseRet(retData, respInfo)

這個例子中，咱們使用了policy的兩個參數fsizeLimit和mimeLimit，表示咱們只容許上傳大小不大於1000字節的類型爲png的圖片。

更多的關於policy的其餘參數的例子咱們將在後面的章節中給出。用法類似，先體會一下。

小結

從上面介紹的內容咱們大體能夠得出如下的一些結論：

1. 上傳策略決定了文件存儲的空間
2. 上傳策略能夠設定生成的上傳憑證的有效期
3. 上傳策略支持文件同名覆蓋上傳
4. 上傳策略裏面能夠指定文件上傳後上傳端的重定向操做
5. 上傳策略裏面能夠指定文件上傳後七牛服務器和業務服務器的交互操做
6. 上傳策略裏面能夠指定文件上傳後，七牛服務器對其進行的一組數據處理操做