伯索开放平台
首页API文档SDK文档
伯索官网
首页API文档SDK文档
伯索官网
  1. 文件预解析
  • SDK 接入总览
  • 实时课堂
    • Android 实时课堂接入
    • Harmony 实时课堂接入
    • iOS 实时课堂接入
    • Electron 实时课堂接入
    • Web 实时课堂监课接入
  • 极速课堂
    • Android 极速课堂接入
    • Harmony 极速课堂接入
    • iOS 极速课堂接入
    • Electron 极速课堂接入
  • 微课
    • Android 微课接入
    • Harmony 微课接入
    • iOS 微课接入
    • Electron 微课接入
  • 资料中心
    • Android 资料中心接入
    • Harmony 资料中心接入
    • iOS 资料中心接入
    • Electron 资料中心接入
    • Web 资料中心接入
  • 文件预解析
    • Android 文件预解析接入
    • Harmony 文件预解析
    • iOS 文件预解析接入
    • Electron 文件预解析接入
  • 历史课堂回放
    • Android 历史课堂回放
    • Harmony 历史课堂回放
    • iOS 历史课堂回放
    • Electron 历史课堂回放
    • 播放器
      • 播放器 SDK 概述
      • 播放器 SDK 快速开始
      • 播放器 SDK 初始化与配置
      • 播放器 SDK 历史课堂回放
      • 播放器 SDK 移动端 WebView 嵌入
      • 播放器 SDK API 参考
      • 播放器 SDK 事件
      • 播放器 SDK 错误码
      • 播放器 SDK 常见问题
  • 云学堂模块化SDK
    • 云学堂模块化 SDK 概述
    • 云学堂模块化 SDK · Android 接入
    • 云学堂模块化 SDK · iOS 接入
    • 云学堂模块化 SDK · Harmony 接入
    • 云学堂模块化 SDK · PC 接入
    • 伯索云学堂跳转接入
  • 接入基础(Electron & Web)
    • Web
      • Web 概述
      • Web 快速开始:URL 接入监课
      • Web 初始化与配置(监课)
      • Web API 参考(监课)
      • Web 事件与回调(监课)
      • Web 错误码(监课)
      • Web 常见问题(监课)
    • Electron
      • Electron 概述
      • Electron 快速开始
      • Electron 初始化与配置
      • Electron API 参考
      • Electron 事件与回调
      • Electron 错误码
      • Electron 常见问题
  • 服务端接口与协议
    • 服务端接口与协议阅读顺序
    • 签名与鉴权
    • 签名示例
    • query 参数
    • 资料中心与文件 URL
    • 文档预解析
    • 课堂进行中数据回调
    • 课堂结束数据回调
    • 历史课堂转视频与下载
  1. 文件预解析

Android 文件预解析接入

0. 版本说明#

项说明
SDK 版本1.68.110
接入性质可选能力
适用文件PPT、PDF、Word、Excel 等需要分页/渲染的文件
客户端入口IResourceProvider.getPreParseFileName
资料中心内选择并插入预解析文件的完整流程见《资料中心/Android》的“预解析文件接入”。本文保留服务端解析准备、对象字段与 URL 回调的独立详细说明,供已接入资料中心后实现解析服务时查阅。

接入前准备#

需要已有资料中心文件标识、服务端解析任务和解析产物 URL 签发接口。客户端必须能访问业务服务端,服务端必须保存解析状态、产物目录和页数。

1. 服务端解析链路#

预解析由业务文件服务、对象存储、伯索文档解析服务和 Android SDK 协同完成。Android 不直接调用解析服务,也不直接访问解析产物目录。

1.1 文件记录与状态#

业务服务端应为每个原始文件保存一条解析记录,并以业务文件 ID 作为资料中心和 Android info 中的稳定标识。
字段用途
fileId业务文件 ID;资料中心返回并写入 Android info。
sourcePath原始文件在对象存储中的路径;创建解析任务时使用。
taskId伯索解析任务 ID;用于关联异步回调。
status至少区分 PENDING、COMPLETED、FAILED。
targetPath解析产物目录;只保存在服务端,不能下发给客户端。
totalPagesPDF、Word、Excel 等解析页数;资料中心返回后写入 Android 的 totalsPages。
fileType原始文件和解析资源类型;用于映射 Android UpimeObject.type。

1.2 创建解析任务#

1.
业务服务端接收原始 PPT、PDF、Word 或 Excel,并保存到业务对象存储。
2.
服务端创建解析记录,状态设为 PENDING。
3.
服务端调用伯索文档解析接口:
POST https://www.plaso.cn/dataentry/document/parser
请求至少包含 appId、sourcePath、taskType、callbackUrl、validBegin、validTime 和 signature。taskType 分别为:PPT 4、Word/Excel 5、PDF 8。
4.
服务端从成功响应中取得 taskId 并写入解析记录。
创建任务使用的完整请求字段、签名规则和对象存储权限见《服务端接口与协议/文档预解析》的“创建解析任务”。

1.3 接收解析完成回调#

伯索解析服务会调用创建任务时传入的 callbackUrl。业务服务端应按 taskId 幂等处理回调:
回调字段处理要求
taskStatus=100将记录更新为 COMPLETED,保存 targetPath 和 convertPages。
taskStatus=101将记录更新为 FAILED,保存可定位的失败原因。
重复回调不重复创建文件记录、资源目录或后续任务。
回调失败重试接收端应能接受重复投递;解析服务的重试规则见服务端协议。
资料中心只应展示 COMPLETED 的预解析文件。解析中或失败的文件应显示处理状态,不能作为可插入的预解析资源返回。

1.4 为 SDK 签发解析产物 URL#

业务服务端需要提供一个业务接口,接收 Android 上传的 fileId + suffix 并返回短时 URL。接口名称由业务方定义,处理逻辑必须满足:
1.
根据 fileId 查询解析记录,并验证当前用户对该文件有访问权限。
2.
确认记录状态为 COMPLETED,且存在 targetPath。
3.
对 suffix 做规范化和白名单校验;拒绝 ..、反斜杠、绝对路径、完整 URL 及不属于该解析任务的资源。
4.
仅在服务端将已校验的 suffix 与 targetPath 组合,生成短时签名 URL。
5.
返回完整 URL;失败时返回明确业务错误,由 Android 回调 onFilePath(null)。
suffix 可能是 /1.jpg、/index.html、/ispring.html、/info.json,也可能包含允许的图片处理查询参数。不得将 targetPath、OSS 长期凭证或对象存储拼接规则下发给客户端。

2. Android 端加载流程#

1.
Android 打开业务资料中心;资料中心只返回状态为 COMPLETED 的解析文件及其 fileId、类型、标题、页数。
2.
Android 将 fileId 写入 UpimeObject.info,将 PDF、Word、Excel 的页数写入 totalsPages,然后调用 UpimeBoard.insertObject。
3.
SDK 请求某个解析产物时调用 getPreParseFileName(info, suffix, callback)。
4.
Android 从 info 提取 fileId,将 fileId + suffix 请求业务服务端。
5.
服务端校验权限和 suffix,签发对应解析产物的短时 URL。
6.
Android 通过 callback.onFilePath(url) 返回 URL;无权限、解析未完成、产物不存在或请求失败时返回 callback.onFilePath(null)。
服务端创建任务、回调和 URL 签发的全量协议见《服务端接口与协议/文档预解析》。

3. 预解析文件对象与插入#

预解析文件必须使用业务侧的解析文件标识作为 info,不能把产物目录或 OSS 根路径暴露给客户端。Demo 使用以下结构:
["parsed", { "id": "parsed-file-001" }]
type必填字段SDK 可能请求的 suffix
UpimeObject.TYPE_I_SPRING_PPTinfo、title/index.html、/ispring.html
UpimeObject.TYPE_PDFinfo、title、totalsPages/1.jpg、/info.json
UpimeObject.TYPE_DOC、TYPE_XLSinfo、title、totalsPages由解析产物决定
totalsPages 是 Android UpimeObject 的字段名;如果业务服务端的字段名为 totalPages,在赋值时仍应写入 totalsPages。

3.1 预解析 PPT#

预解析 PPT 使用 UpimeObject.TYPE_I_SPRING_PPT。不需要设置 totalsPages;SDK 会按需请求 PPT 的 HTML 入口和运行页面。
典型时序如下。每次回调都应使用相同的解析文件 ID,向业务服务端换取当前 suffix 对应的短时 URL:

3.2 预解析 PDF、Word 和 Excel#

预解析 PDF、Word 和 Excel 分别使用 TYPE_PDF、TYPE_DOC、TYPE_XLS。必须将解析服务返回的页数写入 totalsPages,否则 SDK 无法正确构建分页资源。
SDK 会按页和元数据多次调用 getPreParseFileName,常见请求包括:
suffix用途
/1.jpg、/2.jpgPDF/文档解析页图片。
/info.json解析文件元数据。
/1.jpg?x-oss-process=...带图片处理参数的解析页;查询参数也属于 suffix 的一部分。
服务端应按已保存的 targetPath 定位解析产物;兼容原始文件路径推导的实现通常等价于从原文件 Object Key 构造 <ossKey>_i/<suffix>。无论采用哪种内部存储方式,Android 只能传递 fileId + suffix,不能传递或拼接对象存储路径。

4. 客户端回调#

4.1 getPreParseFileName 的触发时机与参数#

当预解析 UpimeObject 已插入课堂或微课,SDK 需要加载某一页、HTML 页面或元数据时,会调用:
参数来源与处理方式
info插入 UpimeObject 时传入的原始文件标识。推荐使用 ["parsed", { "id": "解析文件 ID" }],从第二项的 id 取得业务解析文件 ID。
suffixSDK 请求的解析产物相对路径,例如 /1.jpg、/index.html、/ispring.html、/info.json;可能包含图片处理查询参数。必须原样提交给服务端。
callback资源取址完成回调。成功时传入完整、可访问的短时 URL;所有失败场景均传入 null。一次请求只能完成一次回调。
该回调不是创建解析任务的入口,也不是客户端拼接 OSS 地址的位置。客户端只负责将 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;生产环境应按自身鉴权、存储和审计要求实现,不能直接信任客户端提交的路径。

4.2 实现示例#

如果业务服务端返回空 URL、无权限、解析未完成、产物不存在或网络请求超时,也必须执行 callback.onFilePath(null),不能只记录日志后直接返回,否则 SDK 会持续等待资源。

4.3 回调约束#

info 就是插入 UpimeObject 时传入的原始对象;服务端仅使用其中的业务文件 ID 鉴权;
suffix 是解析产物的相对路径或页面后缀。原样传给服务端,不要在客户端拼接 OSS URL;
服务端只允许白名单 suffix,并拒绝目录穿越、完整 URL 或非当前解析任务的资源;
URL 应带有效期;
每次回调只完成一次;
请求超时、无权限或解析失败时回调 null。

5. 窗口与图片打开模式#

使用 OPEN_FILE_MODE_WINDOW 时,SDK 会按需请求解析页或页面资源,例如 /1.jpg、/index.html 和 /info.json。使用 OPEN_FILE_MODE_IMAGE 时,Demo 对 PDF、Word、Excel 会先以 suffix == "?" 请求原始文档的短时 URL,下载到本地后再插入。
常见 suffix 可能包含查询参数,例如 /1.jpg?x-oss-process=...。服务端应按协议解析和校验完整 suffix,不能简单把任意字符串拼到对象存储根路径。

6. 联调检查清单#

服务端解析任务状态可查询或通过回调落库。
解析任务创建成功后,taskId 已与业务 fileId 关联。
解析回调按 taskId 幂等处理,且只将 COMPLETED 文件展示到资料中心。
解析产物目录和页数已保存。
Android 插入对象包含正确的 info。
suffix 能完整到达服务端。
PDF/Word/Excel 的 totalsPages 正确。
解析产物 URL 过期后能重新签发。
suffix 非法、文件无权限、产物不存在时均能快速失败。
修改于 2026-11-18 03:45:46
上一页
Web 资料中心接入
下一页
Harmony 文件预解析
Built with