对象存储

  • 上传策略

    最近更新时间:2017-09-07 17:40:00

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

    上传策略同时还参与请求验证,可以验证用户对某个资源的上传请求是否完整。

    格式

    {
    
        "scope":               "<Bucket                   string>",
        "isPrefixalScope":     "<IsPrefixalScope          int>",
        "deadline":            "<UnixTimestamp            uint32>",
        "insertOnly":          "<AllowFileUpdating        int>",
    
        "endUser":             "<EndUserId                string>",
    
        "returnUrl":           "<RedirectURL              string>",
        "returnBody":          "<ResponseBodyForAppClient string>",
    
        "callbackUrl":         "<RequestUrlForAppServer   string>",
        "callbackHost":        "<RequestHostForAppServer  string>",
        "callbackBody":        "<RequestBodyForAppServer  string>",
        "callbackBodyType":    "<RequestBodyTypeForAppServer  string>",
    
        "persistentOps":       "<persistentOpsCmds        string>",
        "persistentNotifyUrl": "<persistentNotifyUrl      string>",
        "persistentPipeline":  "<persistentPipeline       string>",
        "saveKey":             "<SaveKey                  string>",
        "fsizeMin":            "<FileSizeMin              int64>",
        "fsizeLimit":          "<FileSizeLimit            int64>",
    
        "detectMime":          "<AutoDetectMimeType       int>",
    
        "mimeLimit":           "<MimeLimit                string>",
        "fileType":           "<fileType                  int>"
    }
    
    字段名称 必填 说明
    scope 指定上传的目标资源空间 Bucket 和资源键 Key(key的长度最大为750字节)。有三种格式:
    ● <bucket>,表示允许用户上传文件到指定的 bucket。在这种格式下文件只能新增,若已存在同名资源上传则会失败。
    ● <bucket>:<key>,表示只允许用户上传指定 key 的文件。在这种格式下文件默认允许修改,若已存在同名资源则会被覆盖。如果只希望上传指定 key 的文件,并且不允许修改,那么可以将下面的 insertOnly 属性值设为 1。
    ● <bucket>:<keyPrefix>,表示只允许用户上传指定以 keyPrefix 为前缀的文件,当且仅当 isPrefixalScope 字段为 1 时生效,isPrefixalScope 为 1 时无法覆盖上传。
    isPrefixalScope 若为 1,表示允许用户上传以 scope 的 keyPrefix 为前缀的文件。
    deadline 上传凭证有效截止时间。
    Unix时间戳,单位为秒。该截止时间为上传完成后,在七牛空间生成文件的校验时间,而非上传的开始时间,一般建议设置为上传开始时间 + 3600s,用户可根据具体的业务场景对凭证截止时间进行调整。
    insertOnly 限定为新增语意。
    如果设置为非 0 值,则无论 scope 设置为什么形式,仅能以新增模式上传文件。
    endUser 唯一属主标识。
    特殊场景下非常有用,例如根据 App-Client 标识给图片或视频打水印。
    returnUrl Web 端文件上传成功后,浏览器执行 303 跳转的 URL。
    通常用于表单上传
    文件上传成功后会跳转到 <returnUrl>?upload_ret=<queryString>,<queryString>包含 returnBody 内容。如不设置 returnUrl,则直接将 returnBody 的内容返回给客户端。
    returnBody 上传成功后,自定义七牛云最终返回給上传端(在指定 returnUrl 时是携带在跳转路径参数中)的数据。
    支持魔法变量自定义变量。returnBody 要求是合法的 JSON 文本。例如 {"key": $(key), "hash": $(etag), "w": $(imageInfo.width), "h": $(imageInfo.height)}。
    callbackUrl 上传成功后,七牛云向业务服务器发送 POST 请求的 URL。
    必须是公网上可以正常进行 POST 请求并能响应 HTTP/1.1 200 OK 的有效 URL。另外,为了给客户端有一致的体验,我们要求 callbackUrl 返回包 Content-Type 为 "application/json",即返回的内容必须是合法的 JSON 文本。出于高可用的考虑,本字段允许设置多个 callbackUrl(用英文符号 ; 分隔),在前一个 callbackUrl 请求失败的时候会依次重试下一个 callbackUrl。一个典型例子是:http://<ip1>/callback;http://<ip2>/callback,并同时指定下面的 callbackHost 字段。在 callbackUrl 中使用 ip 的好处是减少了对 dns 解析的依赖,可改善回调的性能和稳定性。指定callbackUrl,必须指定callbackbody,且值不能为空
    callbackHost 上传成功后,七牛云向业务服务器发送回调通知时的 Host 值。与callbackUrl配合使用,仅当设置了 callbackUrl 时才有效。
    callbackBody 上传成功后,七牛云向业务服务器发送Content-Type: application/x-www-form-urlencoded 的 POST 请求。该字段 App-Server 可以通过直接读取请求的 query 来获得,支持魔法变量自定义变量callbackBody 要求是合法的 url query string。如:key=$(key)&hash=$(etag)&w=$(imageInfo.width)&h=$(imageInfo.height)
    callbackBodyType 上传成功后,七牛云向业务服务器发送回调通知callbackBodyContent-Type。默认为application/x-www-form-urlencoded,也可设置为application/json
    persistentOps 资源上传成功后触发执行的预转持久化处理指令列表。每个指令是一个 API 规格字符串,多个指令用;分隔。
    请参阅 persistenOps详解示例。同时添加persistentPipeline字段,使用专用队列处理,请参阅 persistentPipeline
    persistentNotifyUrl 接收持久化处理结果通知的 URL。
    必须是公网上可以正常进行 POST 请求并能响应HTTP/1.1 200 OK的有效 URL。该 URL 获取的内容和持久化处理状态查询(prefop)的处理结果一致。发送 body 格式是Content-Typeapplication/json的 POST 请求,需要按照读取流的形式读取请求的 body 才能获取。
    persistentPipeline 转码队列名。资源上传成功后,触发转码时指定独立的队列进行转码。为空则表示使用公用队列,处理速度比较慢。建议使用专用队列
    saveKey 自定义资源名。
    支持魔法变量自定义变量。这个字段仅当用户上传的时候没有主动指定 key 的时候起作用。
    fsizeMin 限定上传文件大小最小值,单位:字节(Byte)。设置为 k,即 k 及 k 以上的文件可以上传。
    fsizeLimit 限定上传文件大小最大值,单位:字节(Byte)。超过限制上传文件大小的最大值会被判为上传失败,返回 413 状态码。
    detectMime 开启MimeType侦测功能。
    设为非 0 值,则忽略上传端传递的文件 MimeType 信息,使用七牛服务器侦测内容后的判断结果。默认设为 0 值,如上传端指定了 MimeType 则直接使用该值,否则按如下顺序侦测 MimeType 值:
    1. 检查文件扩展名;
    2. 检查Key扩展名;
    3. 侦测内容。
    如不能侦测出正确的值,会默认使用 application/octet-stream
    mimeLimit 限定用户上传的文件类型。
    指定本字段值,七牛服务器会侦测文件内容以判断 MimeType,再用判断值跟指定值进行匹配,匹配成功则允许上传,匹配失败则返回 403 状态码。
    示例:
    image/*表示只允许上传图片类型
    image/jpeg;image/png表示只允许上传jpgpng类型的图片
    !application/json;text/plain表示禁止上传json文本和纯文本。注意最前面的感叹号!
    fileType 文件存储类型
    0 为普通存储(默认),1 为低频存储。

    persistentOps详解

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

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

    • 使用默认的存储空间和资源名

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

    • 使用指定的存储空间和资源名

      在数据处理命令后用管道符 | 拼接 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 不可混用。
    • 文件上传后的命名将遵循以下规则:
      • 源Bucket和目标Bucket必须在同一区域,即处理结果不能跨区域另存。
      • 客户端已指定Key,以Key命名。
      • 客户端未指定Key,上传策略中设置了saveKey,以saveKey的格式命名。
      • 客户端未指定Key,上传策略中未设置saveKey,以文件hash(etag)命名。

    示例

    persistentOpspersistentNotifyUrl字段

    上传一个视频资源,并在成功后触发两个预转处理(转成 mp4 资源和对原资源进行 HLS 切片):

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

    关于 avthumb 接口的详细信息请参阅 音视频转码 (avthumb)

    以上内容是否对您有帮助?
  • 提交工单