七牛云存储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. 上传策略里面能够指定文件上传后，七牛服务器对其进行的一组数据处理操做