| 项 | 说明 |
|---|---|
| SDK 版本 | 1.68.110 |
| 接入性质 | 可选能力 |
| 适用文件 | PPT、PDF、Word、Excel 等需要分页/渲染的文件 |
| 客户端入口 | upimeVC(_:getPreParseFileName:suffix:result:) |
info 中的稳定标识。| 字段 | 用途 |
|---|---|
fileId | 业务文件 ID;资料中心返回并写入 iOS info。 |
sourcePath | 原始文件在对象存储中的路径;创建解析任务时使用。 |
taskId | 伯索解析任务 ID;用于关联异步回调。 |
status | 至少区分 PENDING、COMPLETED、FAILED。 |
targetPath | 解析产物目录;只保存在服务端,不能下发给客户端。 |
totalPages | PDF、Word、Excel 等解析页数;资料中心返回后写入 iOS 的 pages。 |
fileType | 原始文件和解析资源类型;用于映射 UpimeFileType。 |
PENDING。POST https://www.plaso.cn/dataentry/document/parserappId、sourcePath、taskType、callbackUrl、validBegin、validTime 和 signature。taskType 分别为:PPT 4、Word/Excel 5、PDF 8。taskId 并写入解析记录。callbackUrl。业务服务端应按 taskId 幂等处理回调:| 回调字段 | 处理要求 |
|---|---|
taskStatus=100 | 将记录更新为 COMPLETED,保存 targetPath 和 convertPages。 |
taskStatus=101 | 将记录更新为 FAILED,保存可定位的失败原因。 |
| 重复回调 | 不重复创建文件记录、资源目录或后续任务。 |
| 回调失败重试 | 接收端应能接受重复投递;解析服务的重试规则见服务端协议。 |
COMPLETED 的预解析文件。解析中或失败的文件应显示处理状态,不能作为可插入的预解析资源返回。fileId + suffix 并返回短时 URL。接口名称由业务方定义,处理逻辑必须满足:fileId 查询解析记录,并验证当前用户对该文件有访问权限。COMPLETED,且存在 targetPath。suffix 做规范化和白名单校验;拒绝 ..、反斜杠、绝对路径、完整 URL 及不属于该解析任务的资源。suffix 与 targetPath 组合,生成短时签名 URL。suffix 可能是 /1.jpg、/index.html、/ispring.html、/info.json,也可能包含允许的图片处理查询参数。不得将 targetPath、OSS 长期凭证或对象存储拼接规则下发给客户端。COMPLETED 的解析文件及其 fileId、类型、标题、页数。fileId 写入 UpimeFile.info,将 PDF、Word、Excel 的页数写入 pages,然后调用 insertFile。getPreParseFileName。info 提取 fileId,将 fileId + suffix 请求业务服务端。result(url) 返回 URL;无权限、解析未完成、产物不存在或请求失败时返回 result("")。info,不能把产物目录或 OSS 根路径暴露给客户端。Demo 使用以下结构:["parsed", { "id": "parsed-file-001" }]type | 必填字段 | SDK 可能请求的 suffix |
|---|---|---|
.ISPRING_PPT | info、title | /index.html、/ispring.html |
.PDF | info、title、pages | /1.jpg、/info.json |
.WORD、.EXCEL | info、title、pages | 由解析产物决定 |
pages 是 iOS UpimeFile 的字段名;如果业务服务端的字段名为 totalPages,在赋值时仍应写入 pages。.ISPRING_PPT。不需要设置 pages;SDK 会按需请求 PPT 的 HTML 入口和运行页面。suffix 对应的短时 URL:.PDF、.WORD、.EXCEL。必须将解析服务返回的页数写入 pages,否则 SDK 无法正确构建分页资源。getPreParseFileName,常见请求包括:suffix | 用途 |
|---|---|
/1.jpg、/2.jpg | PDF/文档解析页图片。 |
/info.json | 解析文件元数据。 |
/1.jpg?x-oss-process=... | 带图片处理参数的解析页;查询参数也属于 suffix 的一部分。 |
targetPath 定位解析产物;兼容原始文件路径推导的实现通常等价于从原文件 Object Key 构造 <ossKey>_i/<suffix>。无论采用哪种内部存储方式,iOS 只能传递 fileId + suffix,不能传递或拼接对象存储路径。getPreParseFileName 的触发时机与参数UpimeFile 已插入课堂或微课,SDK 需要加载某一页、HTML 页面或元数据时,会调用:| 参数 | 来源与处理方式 |
|---|---|
info | 插入 UpimeFile 时传入的原始文件标识。推荐使用 ["parsed", { "id": "解析文件 ID" }],从第二项的 id 取得业务解析文件 ID。 |
suffix | SDK 请求的解析产物相对路径,例如 /1.jpg、/index.html、/ispring.html、/info.json;可能包含图片处理查询参数。必须原样提交给服务端。 |
result | 资源取址完成回调。成功时传入完整、可访问的短时 URL;所有失败场景均传入空字符串。一次请求只能完成一次回调。 |
info + suffix 转给业务服务端;服务端根据解析文件 ID 校验权限、校验 suffix、定位产物并签发 URL。suffix 做 URL 编码;特别是 /、? 以及图片处理查询参数必须完整保留。服务端解码、校验后再生成短时 URL;如果使用阿里云 OSS,签发方式应与当前存储配置匹配,兼容实现通常使用 OSS V1 签名。GET /api/files/{fileId}/parsed-url?suffix=<url-encoded-suffix>fileId + suffix 对应的短时 URL。服 务端参考实现可见 DocParseDemo;生产环境应按自身鉴权、存储和审计要求实现,不能直接信任客户端提交的路径。result(""),不能只记录日志后直接返回,否则 SDK 会持续等待资源。info 就是插入 UpimeFile 时传入的原始对象;服务端仅使用其中的业务文件 ID 鉴权;suffix 是解析产物的相对路径或页面后缀。原样传给服务端,不要在客户端拼接 OSS URL;.window 时,SDK 会按需请求解析页或页面资源,例如 /1.jpg、/index.html 和 /info.json。使用 .picture 时,Demo 对 PDF、Word、Excel 会先以 suffix == "?" 请求原始文档的短时 URL,下载到本地后再插入。suffix 可能包含查询参数,例如 /1.jpg?x-oss-process=...。服务端应按协议解析和校验完整 suffix,不能简单把任意字符串拼到对象存储根路径。taskId 已与业务 fileId 关联。taskId 幂等处理,且只将 COMPLETED 文件展示到资料中心。info。suffix 能完整到达服务端。pages 正确。