伯索开放平台
首页
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. 文件预解析

Electron 文件预解析接入

0. 版本说明#

项说明
SDK 版本@plasosdk/plaso-electron-sdk ≥ 1.3.18(预解析回调与 FILE_TYPE.ISPRINGPPT 自 1.3.8 起)
接入性质可选能力
适用文件PPT、PDF、Word、Excel 等需要分页/渲染的文件
客户端入口onGetPreParseFileNameFn
资料中心内选择并插入预解析文件的完整流程见《资料中心/Electron》的“预解析文件接入”。安装、主进程初始化和通用窗口参数见《接入基础(Electron & Web)/Electron》;课堂启动方式见《实时课堂/Electron》。本文保留服务端解析准备、对象字段与 URL 回调的独立详细说明,供已接入资料中心后实现解析服务时查阅。

接入前准备#

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

1. 服务端解析链路#

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

1.1 文件记录与状态#

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

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

2. Electron 端加载流程#

1.
宿主打开业务资料中心;资料中心只返回状态为 COMPLETED 的解析文件及其 fileId、类型、标题、页数。
2.
在 onClassWindowReadyFn 之后,宿主将 fileId 写入 FileDataObj.info,将 PDF、Word、Excel 的页数写入 totalPages,然后调用 insertObject。
3.
SDK 请求某个解析产物时调用 onGetPreParseFileNameFn(info, { suffix })。
4.
宿主从 info 提取 fileId,将 fileId + suffix 请求业务服务端。
5.
服务端校验权限和 suffix,签发对应解析产物的短时 URL。
6.
宿主以 Promise resolve 返回完整 URL;无权限、解析未完成、产物不存在或请求失败时 reject。
insertObject 适用于实时课堂、微课窗口,须在窗口就绪后调用。含预解析资源的历史课堂,回放页也必须实现播放器的 getPreParseFileName(课堂窗口中的 onGetPreParseFileNameFn 不会自动带到回放页),见 历史课堂回放/Electron。
服务端创建任务、回调和 URL 签发的全量协议见《服务端接口与协议/05-文档预解析》。

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

预解析文件必须使用业务侧的解析文件标识作为 info,不能把产物目录或 OSS 根路径暴露给客户端。Demo 使用以下结构:
["parsed", { "id": "parsed-file-001" }]
type必填字段SDK 可能请求的 suffix
FILE_TYPE.ISPRINGPPTinfo、title如 /index.html(1.3.8+)
FILE_TYPE.PDFinfo、title、totalPages/1.jpg、/info.json
FILE_TYPE.DOC、FILE_TYPE.XLSinfo、title、totalPages由解析产物决定
const { FILE_TYPE } = window.require('@plasosdk/plaso-electron-sdk');
PlasoElectronSdk.insertObject({
  type: FILE_TYPE.PDF,
  title: '课件.pdf',
  info: ['parsed', { id: 'parsed-file-001' }],
  totalPages: 12,
});
totalPages 是 Electron FileDataObj 的字段名;如果业务服务端使用相同字段名,赋值时写入 totalPages。须在 onClassWindowReadyFn 之后调用 insertObject。

3.1 预解析 PPT#

预解析 PPT 使用 FILE_TYPE.ISPRINGPPT。不需要设置 totalPages;SDK 会按需请求 PPT 的 HTML 入口等页面。
PlasoElectronSdk.insertObject({
  type: FILE_TYPE.ISPRINGPPT,
  title: '课件.pptx',
  info: ['parsed', { id: 'ppt-001' }],
});
典型时序如下。每次回调都应使用相同的解析文件 ID,向业务服务端换取当前 suffix 对应的短时 URL;每个 suffix 调用一次,同一文件会多次调用:

3.2 预解析 PDF、Word 和 Excel#

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

4. 客户端回调#

4.1 onGetPreParseFileNameFn 的触发时机与参数#

当预解析文件已通过 insertObject 插入课堂或微课窗口,SDK 需要加载某一页、HTML 页面或元数据时,会调用:
onGetPreParseFileNameFn: async (info: any, option: { suffix: string }) =>
  api.fetchParsedFileUrl(info, option.suffix),
参数来源与处理方式
infoinsertObject 时传入的原始文件标识。推荐使用 ["parsed", { "id": "解析文件 ID" }],从第二项的 id 取得业务解析文件 ID。
option.suffixSDK 请求的解析产物相对路径,例如 /index.html、/info.json、/1.jpg;可能包含图片处理查询参数。必须原样提交给服务端。每个 suffix 调用一次,同一文件会多次调用。
返回值成功时返回完整、可访问的短时 URL;所有失败场景均 reject。
该回调不是创建解析任务的入口,也不是客户端拼接 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 实现示例#

onGetPreParseFileNameFn: async (info: any, option: { suffix: string }) => {
  const fileId = info?.[1]?.id;
  const suffix = option?.suffix;
  if (!fileId || !suffix) {
    return Promise.reject(new Error('invalid info or suffix'));
  }
  try {
    return await api.fetchParsedFileUrl(info, suffix);
  } catch (err) {
    // 记录业务文件 ID、suffix、课堂 ID 后 reject,不要只打日志后让 Promise 挂起
    throw err;
  }
},
api.* 均为业务后端接口,非 SDK API。如果业务服务端返回空 URL、无权限、解析未完成、产物不存在或网络请求超时,也必须 reject,不能只记录日志后直接返回,否则 SDK 会持续等待资源。

4.3 回调约束#

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

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

Electron 文档未提供与 Android OPEN_FILE_MODE_WINDOW / OPEN_FILE_MODE_IMAGE 对应的打开模式配置。SDK 会按需请求解析页或页面资源,例如 /index.html、/1.jpg 和 /info.json。
常见 suffix 可能包含查询参数,例如 /1.jpg?x-oss-process=...。服务端应按协议解析和校验完整 suffix,不能简单把任意字符串拼到对象存储根路径。

6. 联调检查清单#

服务端解析任务状态可查询或通过回调落库。
解析任务创建成功后,taskId 已与业务 fileId 关联。
解析回调按 taskId 幂等处理,且只将 COMPLETED 文件展示到资料中心。
解析产物目录和页数已保存。
在 onClassWindowReadyFn 之后插入;插入对象包含正确的 info。
suffix 能完整到达服务端并完成白名单校验。
PDF/Word/Excel 的 totalPages 正确。
解析产物 URL 过期后能重新签发。
suffix 非法、文件无权限、产物不存在时均 reject,SDK 能结束等待。
含预解析资源的历史课堂,回放页已实现播放器的 getPreParseFileName。
修改于 2026-11-17 07:47:57
上一页
iOS 文件预解析接入
下一页
Android 历史课堂回放
Built with