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