持久化处理快速入门
简介
持久化数据处理(pfop) ,用于满足数据处理时间较长、计算量较大的场景。
- 开发者可使用该功能对音视频进行
异步转码
或超大图片
的处理,并将处理结果永久存储于空间中,从而大幅提升访问体验。 - 持久化数据处理功能还提供即时的处理状态通知和查询功能,因此开发者在开始执行后还能随时获取处理进度信息。
- 资源使用共享资源池,为所有客户提供按照高性价比的方式来处理数据。
在特殊请求量集中情况下,会有积压,如果用户有资源保障需要
, 可以联系我们, 付费购买保障力。
持久化数据处理(pfop) ,可以在以下两种场景触发,下面分别描述它们的详细用法。
触发场景 |
---|
对已存在空间中的资源,手动触发处理流程 |
在资源上传时,自动触发处理流程 |
上传时自动触发
开发者如果希望在上传文件过程中自动触发数据处理过程(即预转持久化),需要在构造上传凭证时在上传策略中设置 persistentType
、 persistentOps
、persistentNotifyUrl
、persistentPipeline
字段。
字段 | 类型 | 含义 |
---|---|---|
scope | string | 指定上传的目标资源空间 Bucket 和资源键 Key(最大为 750 字节)。有三种格式: ● <bucket> ,表示允许用户上传文件到指定的 bucket。在这种格式下文件只能 新增 (分片上传需要指定insertOnly为1才是新增,否则也为覆盖上传),若已存在同名资源(且文件内容/etag不一致),上传会失败;若已存在资源的内容/etag一致,则上传会返回成功。● <bucket>:<key> ,表示只允许用户上传指定 key 的文件。在这种格式下文件默认允许 修改 ,若已存在同名资源则会被 覆盖 。如果只希望上传指定 key 的文件,并且不允许修改,那么可以将下面的 insertOnly 属性值设为 1。● <bucket>:<keyPrefix> ,表示只允许用户上传指定以 keyPrefix 为前缀的文件,当且仅当 isPrefixalScope 字段为 1 时生效,isPrefixalScope 为 1 时无法覆盖上传。 |
persistentType | int | 任务类型。支持的取值如下: ● 0 :普通任务。● 1 :闲时任务;对于闲时任务的功能介绍、使用场景、定价,详见 闲时任务策略说明。说明:当前只有部分多媒体处理支持设置闲时任务,如下。 1. 普通转码(GPU转码不支持) 2. 锐智转码2.0(1.0不支持闲时,如需使用请升级到2.0) 3. 音视频拼接 4. 音视频分段 5. 视频截图:视频单帧缩略图、视频采样缩略图、视频雪碧截图 |
persistentOps | string | 资源上传成功后触发执行的处理命令列表。 以 ; 分隔,可以指定多个数据处理命令,如:avthumb/mp4|saveas/cWJ1Y2tldDpxa2V5;avthumb/flv|saveas/cWJ1Y2tldDpxa2V5Mg== ,是将上传的视频文件同时转码成mp4格式 和flv格式 后另存。具体含义见,上传策略 persistentOps详解。每一个数据处理命令都应遵循标准格式。 |
persistentNotifyUrl | string | 用户接收持久化处理结果通知的 URL。 设置 persistentOps 字段时,本字段必须同时设置。未来该设置项将改为可选,如未设置,则只能使用返回的 persistentId 主动查询处理进度。请参考持久化处理结果通知。 |
persistentPipeline | string | 队列名。 仅适用于【普通任务】指定, 【闲时任务】不能指定队列 。资源上传成功后,触发多媒体任务时指定独立的队列进行处理。为空则表示使用默认队列。处理速度比较慢。建议使用专用队列,与其他队列分别使用独立的计算资源。 |
用户使用指定了persistentType
、 persistentOps
、 persistentNotifyUrl
的上传凭证上传一个文件之后,服务端返回的响应内容中会包含此次异步处理的进程 ID即 persistentId
,该 ID 可用于获取处理的进度和结果。
针对用户上传策略的不同,返回的 persistentId 字段会出现在不同的位置:
- 未设置 returnUrl 或 callbackUrl,响应内容中直接带有 persistentId 字段。
- 设置了 returnUrl 但没有设置 returnBody,跳转过程附带的 upload_ret 参数解码后获得的结果中默认带有 persistentId 字段。
- 设置了 callbackUrl,但没有设置 callbackBody,和之前一样,这种情况下上传会失败。
- 设置了 returnUrl 或 callbackUrl,且根据需求自定义了相应的 returnBody 或 callbackBody,要 Body 中使用魔法变量 $(persistentId) 来得到。
示例
persistentType
、persistentOps
、persistentNotifyUrl
字段
上传一个视频资源,并在成功后触发两个闲时预转处理(转成 mp4 资源和对原资源进行 HLS 切片):
{
"scope": "qiniu-ts-demo",
"deadline": 1390528576,
"persistentType": "1"
"persistentOps": "avthumb/mp4;avthumb/m3u8/noDomain/1/segtime/15/vb/440k",
"persistentNotifyUrl": "http://fake.com/qiniu/notify"
}
对已有资源手动触发
如果需要对已存在于空间中的资源进行持久化数据处理(即触发持久化),可按以下方式使用我们的异步处理接口。处理完成后会向用户指定的notifyURL
发送处理结果,用户也可以根据persistentId
来主动查询。
请求报文
请求语法
POST /pfop/ HTTP/1.1
Host: api.qiniu.com
Content-Type: application/x-www-form-urlencoded
Authorization: Qiniu <AccessToken>
<PfopRequestParams>
注意:要在 Authorization 头部的<AccessToken>
前添加 Qiniu 和半角空格。
头部信息
头部名称 | 必填 | 说明 |
---|---|---|
Host | 是 | 固定为 api.qiniu.com |
Content-Type | 是 | 固定为 application/x-www-form-urlencoded |
Authorization | 是 | 该参数应严格按照管理凭证格式进行填充,否则会返回 401 错误码。 一个合法的 Authorization 值应类似于: Qiniu QNJi_bYJlmO5LeY08FfoNj9w_r7... |
访问权限
管理凭证方式。
请求参数
请求参数以表单形式组织,作为请求内容提交,格式如下:
bucket=<urlEncodedBucket>&key=<urlEncodedKey>&fops=<urlEncodedFops>¬ifyURL=<urlEncodedPersistentNotifyUrl>&force=<Force>&pipeline=<Pipeline Name>
参数名称 | 必填 | 类型 | 说明 |
---|---|---|---|
bucket | 是 | string | 资源空间 |
key | 是 | string | 源资源名 |
type | 否 | int | 任务类型。支持的取值如下: ● 0 :普通任务。● 1 :闲时任务;对于闲时任务的功能介绍、使用场景、定价,详见 闲时任务策略说明。说明:当前只有部分多媒体处理支持设置闲时任务,如下。 1. 普通转码(GPU转码不支持) 2. 锐智转码2.0(1.0不支持闲时,如需使用请升级到2.0) 3. 音视频拼接 4. 音视频分段 5. 视频截图:视频单帧缩略图、视频采样缩略图、视频雪碧截图 |
fops | 是 | string | 数据处理命令列表,以; 分隔,可以指定多个数据处理命令。如: avthumb/mp4|saveas/cWJ1Y2tldDpxa2V5;avthumb/flv|saveas/cWJ1Y2tldDpxa2V5Mg== ,是将上传的视频文件同时转码成mp4格式 和flv格式 后另存。可以使用管道 | 拼接saveas/<encodedEntryURI> ,指示七牛服务器使用EncodedEntryURI格式中指定的 Bucket 与 Key 来保存处理结果。如:avthumb/flv|saveas/cWJ1Y2tldDpxa2V5 ,是将上传的视频文件转码flv 格式后存储为qbucket:qkey ,其中cWJ1Y2tldDpxa2V5 是qbucket:qkey 的URL安全的Base64编码结果。 |
notifyURL | 否 | string | 处理结果通知接收 URL,七牛将会向你设置的 URL 发起 Content-Type: application/json 的 POST 请求。请参考持久化处理结果通知。 |
force | 否 | string | 强制执行数据处理。 当服务端发现 fops 指定的数据处理结果已经存在,那就认为已经处理成功,避免重复处理浪费资源。 force设为 1,则可强制执行数据处理并覆盖原结果。 |
pipeline | 否 | string | 队列名。 仅适用于【普通任务】指定, 【闲时任务】不能指定队列 。资源上传成功后,触发多媒体任务时指定独立的队列进行处理。为空则表示使用默认队列。处理速度比较慢。建议使用专用队列,与其他队列分别使用独立的计算资源。 |
响应报文
响应语法
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响应头部)提交工单 给我们。 |
示例
以Python Sdk为例,本例将空间名为bucket_name
中的图片key
缩略为长200宽200的图片,并且保存到目标Bucket_Name
,且文件名为 自定义文件key
。
注意:其他语言 Sdk 可在官方 Sdks 下载,可以通过查看 Sdk 使用指南中触发持久化
使用。
from qiniu import Auth, PersistentFop, build_op, op_save, urlsafe_base64_encode
#对已经上传到七牛的图片发起异步缩略操作
#access_key,secret_key在个人面板的密钥管理处获得,非个人账号密码
access_key = '...'
secret_key = '...'
q = Auth(access_key, secret_key)
#要缩略的文件所在的空间和文件名。
bucket_name = '...'
key = '...'
#pipeline是使用的队列名称,不设置代表不使用私有队列,使用公有队列。
pipeline = '...'
#任务类型,不设置或设置为0为普通任务,设置为1为闲时任务。
type = '...'
#要进行缩略的操作。
fops = 'imageMogr2/thumbnail/200x200!'
#可以对缩略后的文件进行使用saveas参数自定义命名,当然也可以不指定文件会默认命名并保存在当前空间
saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')
fops = fops+'|saveas/'+saveas_key
pfop = PersistentFop(q, bucket_name, pipeline)
ops = []
ops.append(fops)
ret, info = pfop.execute(key, ops, 1)
print(info)
assert ret['persistentId'] is not None
故障排除
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
字段,则该URL会收到主动的通知。服务端完成所有的数据处理后,会以
HTTP POST
的方式将处理状态发送给用户指定的通知URL。 -
开发者可以使用上传时返回的
persistentId
来随时查询数据处理的状态。查询的接口为:[GET] http://api.qiniu.com/status/get/prefop?id=<persistentId>