录课视频对接方案

一、方案背景

ClassIn 教学过程中产生的课堂实录视频是学校教育信息化建设的核心数据资源。此类资源可以在ClassIn客户端和管理后台进行观看与基础管理。
同时为了支持学校对视频数据的自主管控、深度开发自有应用的需求，ClassIn也提供了API实现录课视频回传的方案。
如果仅仅是直播回放页面的对接，而非录课视频文件回传，可以参考大直播方案

本方案则聚焦通过标准化 API 对接，实现 ClassIn 录课视频向学校自有平台的安全、高效、可控同步，支撑学校对视频资源的全生命周期管理。

注：录课视频的生成需满足两个前提：① 课堂创建时已开启“录课”功能；② 教师正常出勤且系统完成自动录制流程。

二、方案适用场景及效果

ClassIn 录课视频、出勤等核心数据采用消息订阅+主动推送的机制回传至学校平台，需学校侧开发标准化接口接收推送数据。消息推送机制及开通流程参考：ClassIn 数据订阅官方文档。

以下重点针对场景2展开详细实施流程。

三、方案具体实施流程

Step 1：接口开发与规范适配

1.1 接口开发要求

需开发一个高可用的 HTTP 接口，用于接收 ClassIn 推送的三类消息，并完成数据校验、落库及响应返回：

• 测试类消息（Cmd：Test）：用于接口连通性验证；
• 录课视频地址消息（Cmd：record）：包含课节 ID、视频文件大小、下载地址、录制时长等核心信息；
• 出勤消息（Cmd：Attendance）：包含课节名称、开课时间、授课教师ID/姓名、课堂时长、学生出勤等基础信息。

1.2 核心规范（必须严格遵守）

• 响应要求：接收到消息后，需在 10 秒内返回标准化 JSON 响应（否则 ClassIn 会判定推送失败并重复推送），响应格式如下：

  {
    "error_info": {
      "errno": 1,  // 必须为 int 类型，字符串类型会触发 1003 格式错误
      "error": "程序正常执行"
    }
  }
  

• 数据校验：对接收到的消息进行签名验证（参考 ClassIn API 签名规则），防止数据篡改；校验消息体完整性，过滤无效/重复消息；
• 异常处理：接口需具备容错能力，如消息解析失败时记录日志并返回合法响应，避免阻塞消息队列；
• 日志留存：完整记录所有接收的消息内容、处理时间、处理结果，留存至少 3 个月，便于问题排查。

Step 2：消息订阅开通与配置

2.1 需提供的配置信息

向 ClassIn 技术对接群提交以下信息，申请开通消息订阅：

1. 接口地址（唯一）：需为公网可访问地址，建议配置 HTTPS 协议保障传输安全；
2. 订阅 Cmd 类型：明确申请开通“record”+“Attendance”；
3. 机构 SID：ClassIn 分配的唯一机构标识；
4. 告警邮箱：提供 1-3 个常用邮箱，用于接收推送失败、接口异常等告警通知（需及时处理，否则会阻塞消息队列）。

2.2 配置测试与验收

• ClassIn 侧会发送“Test”类型消息进行接口连通性测试，需确保接口返回上述标准响应；
• 测试通过后正式开通订阅，开通后可接收真实业务消息；
• 推送规则：失败消息每 10 秒重推一次，每小时发送一次邮箱告警，直至推送成功。

Step 3：视频数据管理与生命周期管控

3.1 数据存储与视频同步

1. 结构化存储：将“Attendance”消息的课节基础信息与“record”消息的视频信息通过课节 ID 关联，存入学校自有数据库，建议表结构包含：课节 ID、课节名称、授课教师、开课时间、视频下载地址、视频大小、录制时长、同步状态、下载时间等字段；
2. 视频下载及管理，由学校平台完成。

3.2 成本优化与资源管控（可选）

• 视频清理：确认学校侧已完成视频备份后，调用 ClassIn 接口删除其平台上的视频文件，降低学校存储成本；
• 操作预警：删除前需在系统中记录操作日志，并向管理员发送确认通知；删除后 ClassIn 客户端将无法查看该课堂回放，需提前告知师生；
• 保留策略：可配置“保留窗口期”（如备份完成后 7 天再删除），避免误操作导致数据丢失。

总结

1. 核心对接逻辑：通过订阅“record+Attendance”两类消息，完整获取视频文件信息与课节基础数据，解决无排课 API 对接场景下的信息缺失问题；
2. 关键合规要求：接口必须按标准返回 int 类型的 errno，且需在 10 秒内响应，否则会触发重复推送和告警；
3. 核心管控策略：视频同步后可按需删除 ClassIn 端文件降低成本，但需做好备份和操作预警，避免数据丢失。