智能多媒体 API

  • 持久化处理使用说明

    最近更新时间:2017-09-13 10:02:24

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

    持久化数据处理(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,并设置上传策略中的persistentOp字段为这两个命令:avthumb/mp3/aq/6/ar/16000avthumb/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'
            }  
        ]  
    }
    
    以上内容是否对您有帮助?
  • Close