白板服务端集成

普通 EduSDK 课堂的白板凭证由后台进课流程下发。本页用于业务后端直接管理白板服务：共享房间 Token、录制、截图和文件转码。

配置独立白板客户端

以下为 Node.js，其他语言使用对应的 whiteboardClient 入口：

import { Eduskit } from '@eduskit/server-sdk';

const sdk = new Eduskit({
  whiteboardClient: {
    baseUrl: process.env.WB_SERVER_URL,
    appId: process.env.WB_APP_ID,
    appKey: process.env.WB_APP_KEY,
    appSecret: process.env.WB_APP_SECRET,
  },
});

上述环境变量均必填。WB_SERVER_URL 为白板 server-api 地址，本地开发为 http://localhost:3012。使用白板应用自己的凭据。

常规方法

Method	HTTP
auth.issueRoomToken	LOCAL HS256 (eduskit-room)
recordings.start	POST /v1/rooms/recording/start
recordings.stop	POST /v1/rooms/recording/stop
recordings.list	GET /v1/rooms/recordings
recordings.get	GET /v1/recordings
recordings.registerMediaAsset	POST /v1/recordings/media-assets
recordings.deleteMediaAsset	DELETE /v1/recordings/media-assets
recordings.enqueueVideoExport	POST /v1/recordings/video-exports
recordings.getVideoExport	GET /v1/recordings/video-exports
captures.create	POST /v1/rooms/captures
captures.list	GET /v1/rooms/captures
files.convert	POST /v1/files/convert
files.getConvertJob	GET /v1/files/convert

录制和转码

下面的 roomId 必须是业务有权管理的实际白板房间。开始和停止录制应分别绑定到业务动作，示例展示它们的调用顺序：

const recording = await sdk.whiteboardClient.recordings.start(roomId, {
  externalRef: 'lesson-001',
});
// 在业务决定停止录制时执行后续调用。
await sdk.whiteboardClient.recordings.stop(roomId, {
  recordingId: recording.recordingId,
});
const exportJob = await sdk.whiteboardClient.recordings.enqueueVideoExport(recording.recordingId, {
  profile: 'hd',
});
const exportStatus = await sdk.whiteboardClient.recordings.getVideoExport(exportJob.jobId);
const convertJob = await sdk.whiteboardClient.files.convert({
  sourceUrl: 'https://example.com/lesson.pptx',
  fileName: 'lesson.pptx',
});
const conversion = await sdk.whiteboardClient.files.getConvertJob(convertJob.jobId);

视频生成需另行提交导出任务。导出和转码均为异步任务，通过状态查询或相应回调获取结果。转码至少提供 sourceUrl 或 objectKey，URL 需指向服务可访问的文件。

房间与私有作品 API

Node.js 0.1.5 及五种语言的源码构建提供以下接口，接入时需配置对应白板服务、业务授权和对象存储。attachCourseware 绑定房间课件，其余方法管理私有房间与作品。教学小黑板暂未开放。

Method	HTTP
rooms.provisionPrivateRoom	POST /v1/rooms/private
rooms.changePrivateRoomGrant	POST /v1/rooms/private/grants
rooms.getPrivateRoomAccess	POST /v1/rooms/private/access/query
rooms.issuePrivateRoomToken	POST /v1/rooms/private/token
rooms.sealPrivateRoom	POST /v1/rooms/private/seal
rooms.createFrozenSnapshot	POST /v1/rooms/private/snapshots
rooms.initializePrivateWorkspace	POST /v1/rooms/private/initializations
rooms.getPrivateWorkspaceInitialization	POST /v1/rooms/private/initializations/query
rooms.getFrozenSnapshot	POST /v1/rooms/private/snapshots/query
rooms.getFrozenSnapshotDownload	POST /v1/rooms/private/snapshots/download
rooms.attachCourseware	POST /v1/rooms/coursewares
rooms.schedulePrivateRoomWrites	POST /v1/rooms/private/write-window

私有房间工作流：初始化工作版本 → 查询到 ready → 设置授权和写入时间窗 → 由服务器签发私有 Token → 封写 → 创建固定作品 → 查询到 ready 后取得下载链接。

sourceSnapshotId 必须显式传入：空文档用 null（Python None，Go nil），复制作品时传已有作品 ID。授权变化使用 requestId 和 expectedGeneration，重试同一请求必须保持参数一致。generation、expectedGeneration、frozenSeq、sizeBytes 保持十进制字符串。

opensAt / closesAt 是 UTC ISO 毫秒字符串，区间不可延长或重开。只有授权而没有写入时间窗时仍不可写。私有 Token 的 generation 由服务端读取，业务方不能自行指定。固定作品下载 URL 有效期为 60 秒，不应保存为长期资源地址。