智能多媒体 API

  • 持久化数据处理

    最近更新时间:2018-07-02 15:26:51

    如果需要对已保存在空间中的资源进行云处理并将结果持久化,可以使用 pfop 接口。

    请求报文

    请求语法

    POST /pfop/ HTTP/1.1
    Host: api.qiniu.com  
    Content-Type: application/x-www-form-urlencoded  
    Authorization: QBox <AccessToken>  
    
    <PfopRequestParams>
    

    注意:要在 Authorization 头部的<AccessToken>前添加 QBox 和半角空格。

    头部信息

    头部名称 必填 说明
    Host 固定为 api.qiniu.com
    Content-Type 固定为 application/x-www-form-urlencoded
    Authorization 该参数应严格按照管理凭证格式进行填充,否则会返回 401 错误码。
    一个合法的 Authorization 值应类似于:QBox QNJi_bYJlmO5LeY08FfoNj9w_r7...

    访问权限

    管理凭证方式。

    请求参数

    请求参数以表单形式组织,作为请求内容提交,格式如下:

    bucket=<urlEncodedBucket>&key=<urlEncodedKey>&fops=<urlEncodedFops>&notifyURL=<urlEncodedPersistentNotifyUrl>&force=<Force>&pipeline=<Pipeline Name>
    
    参数名称 必填 需要URL编码: 说明
    bucket 资源空间
    key 源资源名
    fops 云处理操作列表,用 ; 分隔,如: avthumb/flv%7Csaveas/cWJ1Y2tldDpxa2V5 ,是将上传的视频文件转码成flv格式后存储为 qbucket:qkey ,其中 cWJ1Y2tldDpxa2V5qbucket:qkey 的URL安全的Base64编码结果。
    以上方式可以同时作用于多个数据处理命令,用;分隔,如:avthumb/mp4%7Csaveas/cWJ1Y2tldDpxa2V5;avthumb/flv%7Csaveas/cWJ1Y2tldDpxa2V5Mg== ,具体含义请参见persistentOps详解
    notifyURL 处理结果通知接收 URL,七牛将会向你设置的 URL 发起 Content-Type: application/json 的 POST 请求。请参考持久化处理结果通知
    force 强制执行数据处理。
    当服务端发现 fops 指定的数据处理结果已经存在,那就认为已经处理成功,避免重复处理浪费资源。加上本字段并设为 1,则可强制执行数据处理并覆盖原结果。
    pipeline 为空则表示使用公用队列,处理速度比较慢。建议指定私有队列,转码的时候使用独立的计算资源。

    响应报文

    响应语法

    HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: <PfopResponseContentLength>
    
    <PfopResponseContent>
    

    头部信息

    头部名称 必填 说明
    Content-Type 正常情况下该值将被设为 application/json,表示返回 JSON 格式的文本信息。

    响应内容

    • 如果请求成功,返回包含如下内容的 JSON 字符串(已格式化,便于阅读):
    {
        "persistentId": <persistentId string>
    }
    
    字段名称 必填 说明
    persistentId 持久化处理会话标识,可用于查询处理进度,请参考持久化处理状态查询
    • 如果请求失败,返回包含如下内容的 JSON 字符串(已格式化,便于阅读):
    {
        "error":  "<ErrMsg    string>"
    }
    

    响应状态码

    HTTP状态码 含义
    200 触发持久化处理成功
    400 请求报文格式错误
    401 管理凭证无效
    404 资源不存在
    599 服务端操作失败
    如遇此错误,请将完整错误信息(包括所有HTTP响应头部)提交工单 给我们。

    故障排除

    301跳转问题

    如果遇到类似如下 301 跳转现象,请检查 pfop 的 URL 最后是否少了一个斜杠符号 /,误写成 http://api.qiniu.com/pfop

    W, [2014-04-05T00:14:07.748721 #686]  WARN -- : 301 Moved Permanently => Qiniu::HTTP.post('http://api.qiniu.com/pfop')
    

    正确写法是 http://api.qiniu.com/pfop/

    持久化处理结果通知

    服务端按顺序完成所有指定的云处理操作后,会将处理结果状态提交到<persistentNotifyUrl>指向的网址。

    请求报文

    请求语法

    POST <persistentNotifyUri> HTTP/1.1
    Host:         <persistentNotifyDomain>
    Content-Type: application/json
    
    <JsonStatusDescription>
    

    头部信息

    头部名称 必填 说明
    Host 接收持久化处理结果状态的服务器域名
    Content-Type 固定为 application/json


    请求内容

    用户获得的持久化云处理结果状态是一个 JSON 字符串,内容范例如下:

    {
        "id": "16864pauo1vc9nhp12",
        "code": 0,
        "desc": "The fop was completed successfully",
        "inputKey": "sample.mp4",
        "inputBucket": "dutest",
        "items": [
            {
                "cmd": "avthumb/mp4/r/30/vb/256k/vcodec/libx264/ar/22061/ab/64k/acodec/libmp3lame",
                "code": 0,
                "desc": "The fop was completed successfully",
                "error": "",
                "hash": "FrPNF2qz66Bt14JMdgU8Ya7axZx-",
                "key": "v-PtT-DzpyCcqv6xNU25neTMkcc=/FjgJQXuH7OresQL4zgRqYG5bZ64x",
                "returnOld": 0
            },
            {
                "cmd": "avthumb/iphone_low",
                "code": 0,
                "desc": "The fop was completed successfully",
                "error": "",
                "hash": "FmZ5PbHMYD5uuP1-kHaLjKbrv-75",
                "key": "tZ-w8jHlQ0__PYJdiisskrK5h3k=/FjgJQXuH7OresQL4zgRqYG5bZ64x",
                "returnOld": 0
            },
            {
                "cmd": "avthumb/m3u8/noDomain/1/r/30/vb/256k/vcodec/libx264/ar/22071/ab/64k/acodec/libmp3lame",
                "code": 0,
                "desc": "The fop was completed successfully",
                "error": "",
                "hash": "Fi4gMX0SvKVvptxfvoiuDfFkCuEG",
                "key": "8ehryqviSaMIjkVQDGeDcKRZ6qc=/FjgJQXuH7OresQL4zgRqYG5bZ64x",
                "returnOld": 0
            },
            {
                "cmd": "avthumb/m3u8/noDomain/1/vb/440k",
                "code": 0,
                "desc": "The fop was completed successfully",
                "error": "",
                "hash": "FtuxnwAY9NVBxAZLcxNUuToR9y97",
                "key": "s2_PQlcIOz1uP6VVBXk5O9dXYLY=/FjgJQXuH7OresQL4zgRqYG5bZ64x",
                "returnOld": 0
            }
        ],
        pipeline: "0.default",
        reqid: "ffmpeg.3hMAAH3p5Gupb6oT"
    }
    
    字段名称 必填 说明
    id 持久化处理的进程 ID,即前文中的<persistentId>
    code 状态码 0:成功,1:等待处理,2:正在处理,3:处理失败,4:成功但通知失败。
    desc 与状态码相对应的详细描述。
    inputKey 处理源文件的文件名。
    inputBucket 处理源文件所在的空间名。
    items 云处理操作列表,包含每个云处理操作的状态信息。
    cmd 所执行的云处理操作命令 fopN。
    error 如果处理失败,该字段会给出失败的详细原因。
    hash 云处理结果保存在服务端的唯一 hash 标识。
    key 云处理结果的外链资源名 Key。
    returnOld 默认为 0。当用户执行 saveas 时,如果未加 force 且指定的 bucket:key 存在,则返回 1,告诉用户返回的是旧数据。
    pipeline 云处理操作的处理队列,默认使用队列为共享队列 0.default。
    reqid 云处理请求的请求 id,主要用于七牛技术人员的问题排查。
    以上内容是否对您有帮助?
  • Close