伯索开放平台
首页
API文档SDK文档伯索官网
首页
API文档SDK文档伯索官网
  1. 文件预解析
  • 产品介绍
    • SDK简介
    • SDK支持的业务场景
    • 产品特色
  • 产品功能
    • 实时课堂功能介绍
    • 微课功能介绍
    • 上传课件功能介绍
    • SDK后台功能介绍
  • 接入指引
    • SDK对接标准流程说明
    • 关键概念
  • SDK接入
    • 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 接入
      • 伯索云学堂跳转接入
    • 服务端接口与协议
      • 服务端接口与协议阅读顺序
      • 签名与鉴权
      • 签名示例
      • query 参数
      • 资料中心与文件 URL
      • 文档预解析
      • 历史课堂数据回调
      • 历史课堂转视频与下载
    • 接入基础(Electron & Web)
      • Web
        • Web 概述
        • Web 快速开始:URL 接入监课
        • Web 初始化与配置(监课)
        • Web API 参考(监课)
        • Web 事件与回调(监课)
        • Web 错误码(监课)
        • Web 常见问题(监课)
      • Electron
        • Electron 概述
        • Electron 快速开始
        • Electron 初始化与配置
        • Electron API 参考
        • Electron 事件与回调
        • Electron 错误码
        • Electron 常见问题
  • Open API
    • Open API 主要功能
    • Open API集成常用场景
    • 数据字典
    • 接入须知
      • 调用流程
      • 在线调试
      • 通用错误码
    • 用户管理
      • 添加用户
      • 修改密码
      • 删除用户
      • 更新用户
      • 用户精确查询
      • 查询多个用户
      • 用户访问Token
      • 验证用户Token有效期
      • 批量添加用户
      • 恢复删除的用户
      • 设置学生属性(是否跟随/是否加联/分配课程顾问)
      • 学生随机分配课程顾问(V2)
      • 根据ids,批量查询用户
    • 班级管理
      • 创建班级
      • 更新班级
      • 删除班级
      • 查询班级列表
      • 向班级中添加学生
      • 从班级中移除学生
      • 更换学生所在班级
      • 老师列表中查询机构分校学科
      • 根据班级获取获取班级详情和人员信息
      • 批量绑定老师到班级
    • 实时课堂管理
      • 创建实时课堂
      • 创建实时课堂(班)
      • 更新实时课堂
      • 更新实时课堂(班)
      • 删除实时课堂
      • 查询实时课堂列表
      • 更新实时课堂下听众用户
      • 获取实时课堂监控地址
      • 控制单个学员是否可以回看单次课
      • 获取单个课堂的回看地址
      • 删除单个历史课堂
      • 查询课堂下历史课堂信息
      • 获取课堂考勤数据
      • 获取历史课堂信息
      • 获取历史课堂观看数据
      • 获取课堂互动信息
      • 获取课堂列表(新)
      • 获取实时课堂旁听链接
      • 获取极速直播推流地址
      • 获取课堂下板书图片
      • 获取课堂中引用的课件列表
    • 学情数据
      • 获取学生课堂明细数据
      • 获取学生巩固明细数据
      • 获取学生测验明细数据
      • 获取学生辅导明细数据
      • 获取学生积分明细数据
      • 获取学生课程统计数据
      • 获取学生课程详情统计数据
    • 商城管理
      • 获取商品详情
      • 获取商品列表
      • 获取分校自定义商品栏目列表
      • 订单查询
      • 订单详情查询
    • 作业管理
      • 查询学生作业列表
      • 查询老师作业列表
    • 测验管理
      • 查询机构测评列表
      • 获取测评统计
      • 查询机构测验列表
      • 获取测验明细
    • 积分管理
      • 机构积分规则
      • 查下学生当前积分数
      • 查下机构每天的积分明细记录
    • 课程顾问
      • 新建课程顾问
      • 编辑课程顾问
      • 查询课程顾问
      • 停用/启用课程顾问
      • 更新课程顾问密码
    • 课程管理
      • 创建课程
      • 单次创建直播/实时课堂
      • 查询课程列表
      • 新增课程下发学生
      • 删除课程下发学生
      • 查询课程下发学生列表
      • 下发课程到班级
      • 移除课程班级绑定
      • 查询课程绑定班级IDs
      • 查询课程任务列表
      • 更新课程
      • 查询课程学生
      • 查询学生作业
      • 查询订单详情
    • 校区管理
      • 创建校区
      • 编辑校区
      • 关闭校区
    • 事件推送
      • 事件推送机制
      • 事件推送接入指南
    • 其他接口
      • 三方系统唤起客户端上课方案说明
      • 唤起客户端URL
  • 产品更新记录
    • Open API 更新日志
    • SDK 更新日志
  • 常见问题
    • PPT制作事项
    • 课件常见问题与解决方法
    • 网络相关问题
    • 声音相关问题
    • 网络测速
  • 推荐配置
    • 浏览器推荐
    • 常见软件推荐
    • 教育硬件推荐
  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 并写入解析记录。
创建任务使用的完整请求字段、签名规则和对象存储权限见《服务端接口与协议/05-文档预解析》的“创建解析任务”。

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 签发的全量协议见《服务端接口与协议/05-文档预解析》。

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-17 07:47:57
上一页
Web 资料中心接入
下一页
Harmony 文件预解析
Built with