智能多媒体服务

  • 智能多媒体服务 > API 文档 > 数据处理机制 >处理结果另存(saveas)

    处理结果另存(saveas)

    最近更新时间: 2024-12-02 15:33:20

    简介

    我们提供名为saveas 的数据处理接口,将处理结果作为资源保存到指定空间内,并赋以指定 Key。保存成功后,下一次可直接通过指定 Key 来访问该资源,以达到提升下载速度的效果。

    限制说明

    • 源Bucket和目标Bucket必须在同一区域,即 处理结果不能跨区域另存,例如华东Bucket内的文件经处理后结果无法另存到华北的Bucket。

    • 支持同步调用持久化(pfop)调用,两者调用方式有轻微的差异。大多数使用场景下,建议使用 持久化处理 来实现处理结果存储,避免使用同步操作的 saveas 接口,提升访问速度。

      • 注意:当持久化处理(pfop)调用,不用saveas接口时,系统会默认生成输出结果文件,输出空间默认跟随源文件,结果文件命名根据源文件hash和处理命令生成一个唯一标识的文件名。
    • urlsafe_base64_encode() 函数按照标准的RFC 4648实现,开发者可以参考github.com/qiniu上各 SDK 的样例代码。

    • 当持久化保存的 fop 耗时较长的时候,saveas 请求会返回 CDN 超时,但是只要保证发送的 saveas 请求合法,七牛服务器还是会对请求做正确处理。

    • 此处签名内容不包含 Scheme 部分,与 DownloadToken 签名不一样。

    • c# http 库发送请求的时候会把 | 转成 %7c,由于签名签的是 | ,导致报 400 错误。可以在发送请求的时候,把 url 中的 | 改为 %7c,或者签名的时候签 %7c。

    持久化调用

    接口规格

    saveas/<EncodedEntryURI>/deleteAfterDays/<deleteAfterDays>
    
    参数名称 必填 类型 说明
    <EncodedEntryURI> string EncodedEntryURI 格式组织的目标 Bucket 与 Key;其中bucket 必填,key 非必填。
    <deleteAfterDays> int 最小单位为天,数值 >= 1。表示从保存数据开始算起多少天之后自动从 bucket 删除文件。不设置表示资源不会被自动删除
    savePattern 自定义输出文件资源名,变量值都是 基于输入文件获取,需要经过 urlsafe_base64_encode
    支持文件名变量,包括:bucket、key、etag、fname、fsize、mimeType、endUser、ext、fprefix、keybase
    注意
    1. 和saveKey 互斥,不能共用;
    2. 和 <EncodedEntryURI> 指定 key 时一起存在时,优先使用 savePattern
    saveKey 自定义输出文件资源名,变量值都是 基于输出文件获取,需要经过 urlsafe_base64_encode
    可使用文件名变量,包括:etag, year, mon, day, hour, min, sec
    注意
    1. 和savePattern 互斥,不能共用;
    2. 仅当 <EncodedEntryURI>没有指定 key 时起作用,不能同时指定。

    持久化处理(pfop)调用中设置,直接在命令后跟 |saveas/SafeBase64(bucket:key)/deleteAfterDays/< deleteAfterDays > 即可。

    • 上传时自动触发,设置 persistentOps 字段:

      "persistentOps":"avthumb/mp3/ab/192k|saveas/dGVzdDoxLm1wMw==/deleteAfterDays/3"
      
    • 已有资源主动触发,设置fops字段:

      "fops":"avthumb/mp3/ab/192k|saveas/dGVzdDoxLm1wMw==/deleteAfterDays/3"
      

    表示处理后的数据名称为指定的 key 并且上传到指定的 bucket,在 3 天之后会从 bucket 自动删除。

    同步调用

    同步调用需要签名。

    接口规格

    saveas/<EncodedEntryURI>/sign/<Sign>/deleteAfterDays/<deleteAfterDays>
    
    参数名称 必填 类型 说明
    <EncodedEntryURI> string EncodedEntryURI 格式组织的目标 Bucket 与 Key
    <Sign> string 请求签名部分,算法见下方,在 pfop 操作中不用指定该参数
    <deleteAfterDays> int 多少天之后自动从 bucket 删除文件,从保存数据开始算起
    savePattern 自定义输出文件资源名,变量值都是 基于输入文件获取,需要经过 urlsafe_base64_encode
    支持文件名变量,包括:bucket、key、etag、fsize、mimeType、keybase
    注意
    1. 和saveKey 互斥,不能共用;
    2. 和 <EncodedEntryURI> 指定 key 时一起存在时,优先使用 savePattern
    saveKey 自定义输出文件资源名,变量值都是 基于输出文件获取,需要经过 urlsafe_base64_encode
    可使用文件名变量,包括:etag, year, mon, day, hour, min, sec
    注意
    1. 和savePattern 互斥,不能共用;
    2. 仅当 <EncodedEntryURI>没有指定 key 时起作用,不能同时指定。

    签名算法

    1.在下载 URL(不含 Scheme 部分,即去除 http : //)后附加 saveas 接口(不含签名部分):

    NewURL = URL + "|saveas/<EncodedEntryURI>"
    

    2.使用 SecretKey 对新的下载 URL 进行HMAC1-SHA1签名:

    Sign = hmac_sha1(SecretKey, NewURL)
    

    3.对签名进行URL安全的Base64编码:

    EncodedSign = urlsafe_base64_encode(Sign)
    

    4.在新的下载 URL 后拼接签名参数:

    FinalURL = NewURL + "/sign/<AccessKey>:<EncodedSign>"
    

    同步调用 saveas 算法示例,生成 saveas 请求的完整 Go 代码如下:

    func makeSaveasUrl(URL, accessKey string, secretKey []byte, saveBucket, saveKey string) string {
          encodedEntryURI := base64.URLEncoding.EncodeToString([]byte(saveBucket+":"+saveKey))
          URL += "|saveas/" + encodedEntryURI
          h := hmac.New(sha1.New, secretKey)
          // 签名内容不包括Scheme,仅含如下部分:
        // <Domain>/<Path>?<Query>
          u, _ := url.Parse(URL)
          io.WriteString(h, u.Host + u.RequestURI())
          d := h.Sum(nil)
          sign := accessKey + ":" + base64.URLEncoding.EncodeToString(d)
          return URL + "/sign/" + sign
    }
    

    文件名变量

    文件名变量是一组预先定义的变量,可以使用 $(变量名)${变量名} 形式求值。

    1. savePattern 参数,可用变量如下:

    变量名 变量说明 适用范围
    bucket 获得上传的目标空间名。 持久化调用
    同步调用
    key 获得文件保存在空间中的资源名。 持久化调用
    同步调用
    etag 文件上传成功后的 HTTPETag。若上传时未指定资源ID,Etag将作为资源ID使用。 持久化调用
    同步调用
    fsize 资源尺寸,单位为字节。 持久化调用
    同步调用
    mimeType 资源类型,例如JPG图片的资源类型为image/jpg 持久化调用
    同步调用
    keybase 获得空间资源名忽略后缀,即$(key) 忽略 $(ext) 。 持久化调用
    同步调用
    fname 上传的原始文件名。 持久化调用
    ●适用于上传策略中手动触发数据处理,persistentOps或persistentWorkflowTemplateID
    ●适用于对象存储控制台->文件管理,上传文件时指定工作流模板
    fprefix 获得上传原始文件名忽略后缀,即$(fname) 忽略 $(ext) 。 持久化调用
    ●适用于上传策略中手动触发数据处理,,persistentOps 或persistentWorkflowTemplateID 中
    ●适用于对象存储控制台->文件管理,上传文件时指定工作流模板
    ext 上传资源的后缀名,通过 $(fname) 的后缀或者自动检测的 mimeType 来获取。优先使用 $(fname) 的后缀 持久化调用
    ●适用于上传策略中手动触发数据处理,persistentOps 或persistentWorkflowTemplateID 中
    ●适用于对象存储控制台->文件管理,上传文件时指定工作流模板
    endUser 上传时指定的endUser字段,通常用于区分不同终端用户的请求。 持久化调用
    ●适用于上传策略中手动触发数据处理,persistentOps 或persistentWorkflowTemplateID 中
    ●适用于对象存储控制台->文件管理,上传文件时指定工作流模板

    2. saveKey 参数,可用变量如下:

    变量名 变量说明 适用范围
    etag 输出文件上传成功后的 HTTPETag。若上传时未指定资源ID,Etag将作为资源ID使用。 持久化调用
    同步调用
    year 输出文件上传时的年份。 持久化调用
    同步调用
    mon 输出文件上传时的月份。 持久化调用
    同步调用
    day 输出文件上传时的日期。 持久化调用
    同步调用
    hour 输出文件上传时的小时。 持久化调用
    同步调用
    min 输出文件上传时的分钟。 持久化调用
    同步调用
    sec 输出文件上传时的秒钟。 持久化调用
    同步调用

    求值示例

    输入文件上传原始文件名=demo.mp4

    输入文件空间资源名= file.mp4

    输出文件上传日期=2024.06.05 12:30:50

    输出文件etag=FukjnhlamMYsy-SvkpxsDzQBP0_9

    savePattern 填写如下文件名变量,输出结果文件会是:

    • savePattern=trancode${fname} ,结果文件=trancodedemo.mp4
    • savePattern=${keybase}.m3u8,结果文件=file.m3u8

    saveKey 填写如下文件名变量,输出结果文件会是:

    • saveKey=file${year}${.mon}${day}${hour}${min}.m3u8, 结果文件为=file202406051230.m3u8
    • saveKey=${etag}.m3u8, 结果文件为=FukjnhlamMYsy-SvkpxsDzQBP0_9.m3u8

    EncodedEntryURI 格式

    本格式用于在 URI中指定目标资源空间与目标资源名,格式如下:

    entry = '<Bucket>:<Key>'
    encodedEntryURI = urlsafe_base64_encode(entry)
    

    假设 entryqiniuphotos:gogopher.jpg ,则对应的 encodedEntryURIcWluaXVwaG90b3M6Z29nb3BoZXIuanBn=

    URL安全的Base64编码

    URL安全的Base64编码适用于以URL方式传递Base64编码结果的场景。该编码方式的基本过程是先将内容以Base64格式编码为字符串,然后检查该结果字符串,将字符串中的加号+换成中划线-,并且将斜杠/换成下划线_

    示例

    1.原资源是一个名为 resource/Ship.jpg 的图片:

    http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg
    

    2.将图片做缩略处理:

    http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200
    

    3.对上述云处理结果进行持久化保存:

    # 另存操作的目标空间与资源名
    entryURI = "qiniu-developer:Ship-thumb-200.jpg"
    #编码结果
    encodedEntryURI = "cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="
    #需要签名的部分
    signingStr = "78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="
    #签名结果
    sign = "bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g="
    

    4.最终得到的完整下载 URL:

    http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw==/sign/bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g=
    

    5.保存转码后资源可通过如下 URL 访问:

    http://78re52.com1.z0.glb.clouddn.com/Ship-thumb-200.jpg
    
    以上内容是否对您有帮助?
  • Qvm free helper
    Close