简介

持久化数据处理(pfop) ，用于满足数据处理时间较长、计算量较大的场景。

• 开发者可使用该功能对音视频进行 异步转码 或 超大图片 的处理，并将处理结果永久存储于空间中，从而大幅提升访问体验。
• 持久化数据处理功能还提供即时的处理状态通知和查询功能，因此开发者在开始执行后还能随时获取处理进度信息。
• 资源使用共享资源池,为所有客户提供按照高性价比的方式来处理数据。
• 在特殊请求量集中情况下,会有积压,如果用户有资源保障需要, 可以联系我们, 付费购买保障力。

持久化数据处理(pfop) ，可以在以下两种场景触发，下面分别描述它们的详细用法。

上传时自动触发

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

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

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

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

示例

persistentOps与persistentNotifyUrl字段

上传一个视频资源，并在成功后触发两个预转处理（转成 mp4 资源和对原资源进行 HLS 切片）：

{
    "scope":                "qiniu-ts-demo",
    "deadline":             1390528576,
    "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 和半角空格。

头部信息

访问权限

管理凭证方式。

请求参数

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

bucket=<urlEncodedBucket>&key=<urlEncodedKey>&fops=<urlEncodedFops>&notifyURL=<urlEncodedPersistentNotifyUrl>&force=<Force>&pipeline=<Pipeline Name>

响应报文

响应语法

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

<PfopResponseContent>

头部信息

响应内容

• 如果请求成功，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

{
    "persistentId": <persistentId string>
}

• 如果请求失败，返回包含如下内容的 JSON 字符串（已格式化，便于阅读）：

{
    "error":  "<ErrMsg    string>"
}

响应状态码

示例

以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 = '...'

#要进行缩略的操作。
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>  
  

  ​