预解析服务架构与接入（服务端部署 → 客户端使用）

本文面向需要接入文档解析接口能力的后端与客户端团队，说明从服务端如何实现与对接预解析服务，到客户端/前端如何调用使用。

架构总览

组件说明：

文件服务端（需要自行实现，可参考https://github.com/PlasoOpenPlatform/DocParseDemo）

上传原文件到对象存储（OSS）

调用“文档解析服务”创建解析任务

接收解析服务回调，更新任务状态

按“解析产物目录 + suffix”生成短时签名URL并返回

对象存储（OSS）

存放原文件与解析文件；由文件服务端签发短时URL

客户端

触发上传、轮询状态、获取解析文件列表

接入客户端SDK

实现SDK回调函数 getPreParseFileName(info, suffix, callback)

文档解析服务

伯索云提供相关解析接口文档解析接口

端到端流程：

客户端上传文件 → 文件服务端入库并上云存储；

文件服务端调用解析服务创建任务，记录 taskId；

解析完成后回调到文件服务端 → 标记文件状态为 completed，并记录解析产物目录 targetPath；

客户端按需请求文件签名，携带 suffix（如 /1.jpg、/index.html），文件服务端拼接并签发短时 URL 返回；

客户端用签名URL加载图片/HTML/JSON 等解析结果。

文件服务端参考

https://github.com/PlasoOpenPlatform/DocParseDemo
实现要点，实际以自有后端为准：

文件上传和任务创建 (/api/files/upload)

接收前端上传的文件。

将文件上传到您自己的阿里云OSS Bucket中，得到文件ossKey。

调用文档解析服务的 POST /parser 接口，请求中传入上一步得到的sourcePath (oss://<your-bucket>/<ossKey>) 和用于接收结果的callbackUrl。

在本地保存文件信息（包含sourcePath）和返回的taskId。

回调处理 (/api/callback/document)

创建一个公网可访问的接口，用于接收文档解析服务的异步回调。

回调请求的Body中会包含任务id、任务状态taskStatus和转换页数convertPages。

根据id找到对应的文件记录，将convertPages等信息保存下来，同时将文件状态更新为completed或failed。

获取解析文件 (/api/files/:fileId/parsed-url)

为前端提供一个接口，用于获取最终解析产物（如图片）的访问地址。

此接口接收fileId和具体的文件名suffix（例如 1.jpg）作为参数。

根据 fileId 从存储中查询到原始的 sourcePath。

从 sourcePath (oss://<bucket>/<ossKey>) 中提取 ossKey。

构造解析产物的完整 Object Key：<ossKey>_i/<suffix>。

使用ali-oss的signatureUrl方法为该 Object Key 生成一个带签名的、有时间限制的公开访问URL，并返回给前端。

解析文件信息（导出板书使用） (/api/files/parsedInfo)

为导出板书提供解析后的信息。包括解析后的路径，stsToken

参数透传客户端插入的info信息，服务端根据info找到对应文件

stsInfo获取参考

客户端接入参考

本节给出客户端（Android/iOS/PC前端）接入要点与详细用法，以Android端为例，包含预解析 PPT/PDF 的 UpimeObject 规范、回调契约与调用时序。若你的场景同时包含“非预解析”资源，请参考getExtFileName 的说明。
iOS端请参考资料中心章节
PC端请参考资料中心
Android端详细参考资料中心

5.1 Android/SDK 回调约定

getPreParseFileName（预解析资源使用）

方法签名（Kotlin）：fun getPreParseFileName(info: Any?, suffix: String?, callback: IResourceCallback?)

语义：基于预解析文件标识（info）与页面后缀（suffix）计算资源URL（含签名），成功回调 callback.onFilePath(realUrl)，失败回调 callback.onFilePath(null)（建议主线程）。

实施要点：

从 info 中提取解析目录 id（推荐：List 结构，包含键 id，例如 ["parsed", {"id":"777777..."}]）。

对 suffix 进行 URL 编码后，请求后端接口：GET /api/files/{id}/parsed-url?suffix=...

将返回结果中的 url 透传给 SDK：callback.onFilePath(url)。

getExtFileName（非预解析资源使用）

方法签名（Kotlin）：fun getExtFileName(info: Any?, callback: IResourceCallback?)

语义：基于插入时的 info 计算资源直链（含签名），成功回调 callback.onFilePath(realUrl)；失败回调 callback.onFilePath(null)。

提示：suffix 用于参与地址拼接与签名，若包含查询参数（如图片处理），请整体进行 URL 编码后再传入服务端签名。

5.2 预解析 PPT（iSpring）用法

创建 UpimeObject 并插入：

SDK 会回调 getPreParseFileName，接入方实现：

调用时序（示意）：

详细实现逻辑可参考demo

5.3 预解析 PDF 用法

创建 UpimeObject 并插入：

SDK 会回调 getPreParseFileName，接入方实现：

调用时序（示意）：

详细实现逻辑可参考demo

常见 suffix 参考：

PPT（iSpring）：/index.html、/ispring.html

PDF：/1.jpg、/2.jpg、/info.json、/1.jpg?x-oss-process=...

建议：
suffix 含有 “/”、“?” 等时统一进行 URL 编码；
回调尽量在主线程内返回结果，异常场景及时回调 null，避免 SDK 阻塞。

SDK预解析服务接入说明

预解析服务架构与接入（服务端部署 → 客户端使用）#

架构总览#

文件服务端参考#

客户端接入参考#

5.1 Android/SDK 回调约定#

5.2 预解析 PPT（iSpring）用法#