智能多媒体 API

  • 处理机制

    最近更新时间:2017-12-01 14:17:12

    数据处理机制

    七牛云存储内建了一个非常高效易用的数据处理框架。数据处理框架可以对存储在七牛云上的文件执行一系列符合规范的数据处理操作。

    开发者可以在访问资源时制定执行一个或多个数据处理指令,以直接获取经过处理后的结果。

    比较典型的一个场景是图片查看。客户端可以上传一张高精度的图片,然后在查看图片的时候根据屏幕规格生成一张大小适宜的缩略图。

    例如:生成一张480x320大小的缩略图。这样既可以明显降低网络流量,而且可以提高图片显示速度,还能降低移动设备的内存占用。

    图例

    https://odum9helk.qnssl.com/resource/gogopher.jpg

    链接

    针对该原图生成一张480x320大小的缩略图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageView2/2/w/320/h/480

    链接

    我们还可以定义图片样式例如叫iphone,以缩短URL并提高可读性

    https://odum9helk.qnssl.com/resource/gogopher.jpg-iphone

    链接

    一个常规的数据处理操作包含一个操作指令和若干操作参数,如下所示:

    <fop>/<param1_value>/<param2_name>/<param2_value>/...
    

    数据处理框架对于资源类型没有限制,但是特定的数据处理操作则会有各自适合的处理对象,例如对非图片类型的资源类型上应用缩略图操作可能会返回错误的结果。

    数据处理操作的触发有以下几种机会和方式:

    • 访问资源时。如上面的例子所示范的,只需要在资源URL后加上具体数据操作指令和参数即可。
    • 资源上传时。上传时可在上传策略中设置persistentOps字段,在资源上传完成后七牛云存储会以异步的方式执行数据处理操作,并持久化存储数据处理结果。支持查询数据处理操作的进度。
    • 对已有资源手动触发处理流程。与上传时的数据处理支持相同,这个过程也为异步且可查询操作进度。具体请参考这里

    管道

    规格

    七牛云存储的数据处理功能规格如下:

    [GET] url?<fop>
    

    即基于文件的URL通过问号传参来实现数据处理,<fop>表示数据处理指令及其所需要的参数,是File Operation的缩写,表示文件处理。

    那么,将一个资源经由多个 <fop> 链式处理,各 <fop> 之间用|分割,我们称之为管道(pipeline)。

    管道操作的规格如下:

    [GET] url?<fop1>|<fop2>|<fop3>|<fopN>
    

    url 获取可以参考下载机制

    示例

    将一个原图缩略,然后在缩略图上打上另外一个图片作为水印:

    原图

    https://odum9helk.qnssl.com/resource/gogopher.jpg 链接

    基于原图生成缩略图

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageView/2/h/200

    链接

    在生成的缩略图之上打水印

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageView/2/h/200|watermark/1/image/aHR0cHM6Ly9vZHVtOWhlbGsucW5zc2wuY29tL3Fpbml1LWxvZ28ucG5n

    链接

    样式

    如果觉得 url?<fop1>|<fop2>|<fop3>|<fopN> 这样的形式够冗长,还可以为这些串行的 <fop> 集合定义一个友好别名。如此一来,就可以用友好URL风格进行访问。

    我们先来熟悉七牛qrsctl工具的两个命令行:

    // 定义 url 和数据处理之间的分隔符为 separator 
    qrsctl separator <bucket> <separator>
    
    // 定义数据处理的别名为 aliasName
    qrsctl style <bucket> <aliasName> <fop>
    

    例如:

    // 定义 url 和数据处理之间的分隔符为 "-"
    qrsctl separator <bucket> "-"
    
    // 定义该数据处理样式名为 "iphone" 
    qrsctl style <bucket> "iphone" "imageView/2/h/200|watermark/1/image/aHR0cHM6Ly9vZHVtOWhlbGsucW5zc2wuY29tL3Fpbml1LWxvZ28ucG5n"
    

    那么,以下两个 URL 则等价:

    原始URL:

    https://odum9helk.qnssl.com/resource/gogopher.jpg?imageView/2/h/200|watermark/1/image/aHR0cHM6Ly9vZHVtOWhlbGsucW5zc2wuY29tL3Fpbml1LWxvZ28ucG5n

    友好风格URL:

    https://odum9helk.qnssl.com/resource/gogopher.jpg-iphone

    持久化数据处理

    常规的访问数据处理机制很适合像图片缩略图之类的访问,但无法应用于数据处理过程较长的资源,例如花费时间超过一分钟的音频转码,更不用说可能处理时间超过一小时的视频转码。

    持久化数据处理(pfop)机制用于满足这种处理时间较长的场景。开发者可使用该功能对音视、视频进行异步转码,并将转码结果永久存储于空间中,从而大幅提升访问体验。持久化数据处理功能还提供即时的处理状态通知和查询功能,因此开发者在开始执行音频、视频转码后还能随时获取转码进度信息。

    持久化数据处理功能可以在以下两种场景触发:

    • 在资源上传资源到七牛的过程中,自动触发处理流程。
    • 针对已存在七牛云中的资源,手动触发处理流程。

    下面分别描述这两种触发的详细用法。

    上传后自动触发

    开发者如果希望在上传文件过程中自动触发数据处理过程,需要在构造上传凭证时在上传策略中设置 persistentOps 和 persistentNotifyUrl 两个字段。

    字段 类型 含义
    persistentOps string 需要进行的数据处理命令,可以指定多个命令,以 ; 分隔,具体含义见persistentOps详解。每一个数据处理命令都应遵循标准格式。
    persistentNotifyUrl string 用户接收视频处理结果的接口 URL。设置 persistentOps 字段时,本字段必须同时设置。未来该设置项将改为可选,如未设置,则只能使用返回的 persistentId 主动查询处理进度。

    用户使用指定了 persistentOps 和 persistentNotifyUrl 的上传凭证上传一个文件之后,服务端返回的响应内容中会包含此次异步处理的进程 ID即 persistentId,该 ID 可用于获取处理的进度和结果。

    针对用户上传策略的不同,返回的 persistentId 字段会出现在不同的位置:

    • 设置 returnUrl 或 callbackUrl,响应内容中直接带有 persistentId 字段。
    • 设置了 returnUrl 但没有设置 returnBody,跳转过程附带的 upload_ret 参数解码后获得的结果中默认带有 persistentId 字段。
    • 设置了 callbackUrl,但没有设置 callbackBody,和之前一样,这种情况下上传会失败。
    • 设置了 returnUrl 或 callbackUrl,且根据需求自定义了相应的 returnBody 或 callbackBody,要 Body 中使用魔法变量 $(persistentId) 来得到。

    对已有资源手动触发

    如果需要对已存在于七牛云中的资源进行持久化数据处理,可按以下方式使用我们的异步处理接口:

    POST /pfop/ HTTP/1.1
    Host: api.qiniu.com  
    Content-Type: application/x-www-form-urlencoded  
    Authorization: QBox <AccessToken>  
    
    bucket=<urlEncodedBucket>&key=<urlEncodedKey>&fops=<urlEncodedFops>&notifyURL=<urlEncodedPersistentNotifyUrl>&force=<Force>
    

    其中AccessToken的生成算法可参见管理凭证

    正常情况下获得的返回:

    HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: <length>
    
    {"persistentId": <persistentId>}
    

    处理完成后会向用户指定的notifyURL发送处理结果,用户也可以根据persistentId来主动查询。详情可以参考状态通知和查询

    状态通知和查询

    处理过程的状态可通过以下两种方式获取:

    • 上传时设定persistentNotifyUrl字段,则该URL会收到主动的通知

      服务端完成所有的数据处理后,会以HTTP POST 的方式将处理状态发送给用户指定的通知URL。

    • 随时手动发起一个查询请求

      开发者可以使用上传时返回的persistentId来随时查询数据处理的状态。查询的接口为:

    [GET] http://api.qiniu.com/status/get/prefop?id=<persistentId>
    

    用户获得的数据处理状态是一个JSON字符串,内容格式如下:

    {
        "id": "<persistentId>",
        "code": <overall_result>,
        "desc": "<overall_result_description>",
        "items": [
            ...
            {
                "cmd": "<fop_cmd>",
                "code": <result>,
                "desc": "<result_description>",
                "error": "<error_description>",
                "hash": "<result_hash>",
                "key": "<result_key>"
            }
            ...
        ]
    }
    

    状态内容中每个字段的详细含义如下:

    字段 类型 含义
    id string 数据处理的进程ID,即前文中的persistentId
    code int 状态码,0 表示成功,1 表示等待处理,2 表示正在处理,3 表示处理失败,4 表示回调失败。
    desc string 状态码对应的详细描述。
    items JSON数组。包含每个数据处理操作的进度信息。
    cmd string 对应一个特定的数据处理命令。
    error string 如果处理失败,这个字段会给出详细的失败原因。
    hash string 数据处理结果的哈希值。
    key string 数据处理结果的唯一资源ID。数据处理结果可通过http://<domain>/<key>访问。

    示例

    上传一个音频文件persistent.mp3,并设置上传策略中的persistentOps字段为这两个命令:

    • avthumb/mp3/aq/6/ar/16000
    • avthumb/mp3/ar/44100/ab/32k

    通知接口或主动查询收到的处理状态内容将如下所示:

    {  
        'code': 0,  
        'id': '168739cd2fn1g76f13',   
        'desc': 'The fop was completed successfully',  
        'items': [  
            {
                'code': 0, 
                'hash': 'FvvxM7gMI6WfiuXlBgKbkzU67Tpa', 
                'cmd': 'avthumb/mp3/ar/44100/ab/32k', 
                'key': 'sFhZ4dSjB1zvL3De1UBX2qZ_VR0=/lgxucMCQso_KOW_YDM-_KVIeX6o5', 
                'error': '', 
                'desc': 'The fop was completed successfully'
            },   
            {
                'code': 0, 
                'hash': 'FpSzDMYJtP_UY_6EMIyaBe4awXp3', 
                'cmd': 'avthumb/mp3/aq/6/ar/16000', 
                'key': '1G8-OWwP3jPLvi7O3qOf7yCl4YI=/lgxucMCQso_KOW_YDM-_KVIeX6o5', 
                'error': '', 
                'desc': 'The fop was completed successfully'
            }  
        ]  
    }
    

    访问链接:

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