上传策略（PutPolicy）

上传策略是资源上传时附带的一组配置设定。通过这组配置信息，七牛云存储可以了解用户上传的需求：它将上传什么资源，上传到哪个空间，上传结果是回调通知还是使用重定向跳转，是否需要设置反馈信息的内容，以及授权上传的截止时间等等。

上传策略同时还参与请求验证。实际上，上传凭证（UploadToken）就是上传策略的签名结果。通过对上传策略签名，可以验证用户对某个资源的上传请求是否完整。

• 格式
  • fetchKey上传模式
  • persistentOps详解
• 附注
• 示例
• 内部参考资源
• 外部参考资源

格式

{

    "scope":               "<Bucket                   string>",
    "deadline":             <UnixTimestamp            uint32>,
    "insertOnly":           <AllowFileUpdating        int>,

    "saveKey":             "<SaveKey                  string>",

    "endUser":             "<EndUserId                string>",

    "returnUrl":           "<RedirectURL              string>",
    "returnBody":          "<ResponseBodyForAppClient string>",

    "callbackUrl":         "<RequestUrlForAppServer   string>",
    "callbackHost":        "<RequestHostForAppServer  string>",
    "callbackBody":        "<RequestBodyForAppServer  string>",
    "callbackBodyType":    "<RequestBodyTypeForAppServer  string>",
    "callbackFetchKey":    <RequestKeyForApp         int>

    "persistentOps":       "<persistentOpsCmds        string>",
    "persistentNotifyUrl": "<persistentNotifyUrl      string>",
    "persistentPipeline":  "<persistentPipeline       string>",
    "fsizeMin":           <FileSizeMin            int64>,
    "fsizeLimit":           <FileSizeLimit            int64>,

    "detectMime":           <AutoDetectMimeType       int>,

    "mimeLimit":           "<MimeLimit                string>"
    "deleteAfterDays":     "<deleteAfterDays          int>"
}

fetchKey上传模式

上传策略中的callbackFetchKey是指，是否启用fetchKey上传模式，0为关闭，1为启用。 如果启用fetchKey上传模式，上传的key是由回调的结果指定的。如果回调成功，回调服务应对七牛云存储作出类似如下的响应：

{
    "key": <key>,
    "payload": <callback-json-object>
}

七牛云存储将上面的回调结果解析，<key>的字段作为资源的名称存入存储中。<payload>部分返回给客户端。

例如，回调服务对七牛云存储作出如下的响应：

{
    "key": "sunflowerc.jpg",
    "payload": {
        {"success":true,"name":"sunflowerc.jpg"}
    }
}

则七牛将资源的key作为sunflowerc.jpg存入云存储中，返回给客户端的内容为：

{"success":true,"name":"sunflowerc.jpg"} 

persistentOps详解

persistentOps字段用于指定预转数据处理命令和保存处理结果的存储空间与资源名。

为此字段指定非空值，则在成功上传一个文件后，会启动一个异步数据处理任务。 persistentId 字段，唯一标识此任务。 当 returnBody 中指定了 persistentId 魔法变量时，客户端收到的响应内容(returnBody)中会有 persistentId ；当没有指定 returnBody 时，默认也会返回 persistentId 。

1. 使用默认存储空间和资源名：

   当只指定了数据处理命令时，服务端会选择上传文件的Bucket作为数据处理结果的存储空间，Key由七牛服务器自动生成。

2. 使用指定存储空间和资源名：

   在数据处理命令后用管道符 | 拼接 saveas/<encodedEntryURI> 指令，指示七牛服务器使用 EncodedEntryURI 格式中指定的 Bucket 与 Key 来保存处理结果。
   例如avthumb/flv|saveas/cWJ1Y2tldDpxa2V5，是将上传的视频文件转码成flv格式后存储为qbucket:qkey，其中cWJ1Y2tldDpxa2V5是qbucket:qkey的URL安全的Base64编码结果。
   以上方式可以同时作用于多个数据处理命令，用“;”分隔，例如avthumb/mp4|saveas/cWJ1Y2tldDpxa2V5;avthumb/flv|saveas/cWJ1Y2tldDpxa2V5Mg==。

附注

• Key必须采用utf-8编码，使用非utf-8编码的资源名访问时会报错。
  
• callbackUrl与callbackBody配合使用。
• returnUrl与returnBody配合使用。
• callbackXXX与returnXXX不可混用。
• 文件上传后的命名将遵循以下规则：
  1. 客户端已指定Key，以Key命名；
  2. 客户端未指定Key，上传策略中设置了saveKey，以saveKey的格式命名；
  3. 客户端未指定Key，上传策略中未设置saveKey，以文件hash（etag）命名。

示例

persistentOps与persistentNotifyUrl字段

1. 上传一个视频资源，并在成功后触发两个预转处理（转成mp4资源和对原资源进行HLS切片）：

{
    "scope":                "qiniu-ts-demo",
    "deadline":             1390528576,
    "persistentOps":        "avthumb/mp4;avthumb/m3u8/segtime/15/vb/440k",
    "persistentNotifyUrl":  "http://fake.com/qiniu/notify"
}

内部参考资源

• 上传凭证
• 魔法变量
• 自定义变量
• EncodedEntryURI格式
• URL安全的Base64编码

外部参考资源

• Unix时间戳