跳到主要内容

画布连接参数

更新时间 2024/12/02 01:54:56

重要声明
为了提供更好的画布集成体验，我们推出了更轻量级的 Token 接入画布模式，详情请参考文档。 后续我们也会计划逐步淘汰本文描述的画布连接参数接入模式。

什么是画布连接参数 ?​

画布 Web SDK 需要连接至英飞服务端来进行画布数据的同步与存储，在这个过程中，画布参数发挥了重要的作用。 画布连接参数的本质是一个类似 Url search params 格式的字符串。该字符串内包括了诸如应用 ID，用户信息、签名等重要信息。 画布连接参数提供了以下功能：

  • 基于加密签名机制，通过校验画布连接参数本身，来判断校验画布使用合法性。校验不通过则无法正常使用画布能力。
  • 提供 appId、recordId（画布 uuid）、画布长链接有效时长等画布链接相关信息
  • 提供用户 ID、用户类型、用户名称等画布使用者信息
  • 操作历史、画布版本等画布功能信息

画布连接参数推荐由开发者自己的服务器生成，因为这样可以避免直接将 appSecret 基于网络进行传输。开发者自己的服务端应自行妥善存储 appSecret 数据，并基于 appSecret 生成签名，这样英飞服务端就能仅依靠签名机制验证画布使用者的访问合法性。而为了减少画布连接参数本身暴露造成的风险，连接参数的有效时长应尽可能短一些，这样即便泄漏，也无法持续产生危害。

画布连接参数生成方式​

画布连接参数列表​

参数名称
参数类型
required
参数解释
appId
string
是
应用 ID, 通过控制台中注册应用后获取
recordId
string
是
画布 ID，用以定位唯一的画布记录
loginName
string
是
画布使用者 userId，由开发者侧确定，在同一画布内允许使用相同 loginName 登入，但是会被视为是同一个用户
ownerLoginName
string
是
画布侧预留字段，与 loginName 保持一致即可
crypto
number
是
画布长链接加密模式，当前仅支持一种，固定写 1 即可
validBegin
number
是
画布连接参数有效时间起点，单位为秒 (JS 示例: Date.now()/1000)
validTime
number
是
画布连接参数有效时长，单位为秒；注：英飞服务端判断有效时长的方法为检测英飞服务器系统时间是否落在 [validBegin, validBegin + validTime] 区间
opDays
number
否
操作记录有效时间，单位为：天；操作记录：用户对于白板内元素的增删改行为记录，由服务端自行统计。如果不给入值，则默认会关闭操作历史功能, 并清空在当前 recordId 白板内全部的操作历史记录。
versionDays
number
否
历史版本有效时间，单位为：天。历史版本：某一时刻下白板内全部内容的快照。快照可由用户主动生成，或者在全部用户退出白板时由系统自动生成。如果不给入值，则默认会关闭历史版本功能，并清空在当前 recordId 白板内全部的历史版本记录数据。
signature
string
是
基于上述字段的加密签名值，签名计算方法请参考下文签名生成方式

计算签名与画布连接参数方式​

画布连接参数的签名与 Restful API 签名的生成方式基本一致，首先将上述表格中的各参数（除 signature 外）以 参数名称=参数值 形式用 & 拼接成字符串，再通过 HMAC-sha1 签名并以 Hex 格式输出，即可得到签名值。

Node 环境下 JS 示例：

// 存储于服务端的 appSecret
const signKey = "APP_SECRET";
// 包含全部必要画布连接参数的对象
const params = { appId: 'testId', ... };
// 将参数名与参数值拼接，并连接成 Url Search Params 字符串
const content = Object.keys(params).sort().map(key => `${key}=${params[key]}`).join('&');
// 使用分配的应用秘钥来加密生成签名
const signature = crypto.createHmac('sha1', signKey).update(content).digest('hex').toUpperCase();

const enrichedParams = { ...params, signature };
// 生成画布连接参数
const queryString = Object.keys(enrichedParams).sort().map(key => `${key}=${encodeURIComponent(params[key])}`)

画布连接参数示例：

appId=test&crypto=1&loginName=user_1&ownerLoginName=user_1&recordId=test_id&signature=signature_value&validBegin=1698390089&validTime=10800

快速集成画布连接参数生成能力​

为方便 Node 服务端开发者快捷生成画布连接参数，我们提供了可以基于 npm 引入的工具库：

  • 安装依赖：
npm i @plaso-infi/whiteboard-ext-tools
  • 使用工具函数
// @plaso-infi/whiteboard-ext-tools 库自带 d.ts 类型声明
import { getInfiWebsdkQuery, type WebsdkQueryParams } from "@plaso-infi/whiteboard-ext-tools";

// WebsdkQueryParams 会对画布连接参数做类型检查
const queryParams: WebsdkQueryParams = {...};
// 获取完整画布连接参数
const queryString = getInfiWebsdkQuery(queryParams);

使用画布连接参数​

如果您已经基于上文说明完成了画布链接参数的生成，您可以将参数通过网络下发给您的前端应用，再经由您的前端应用将画布链接参数注入英飞画布 Web SDK 并完成 SDK 的初始化动作。 鉴于画布连接参数具有时效性，且用户在前端可能会长时间使用画布，我们建议您在前端集成时，可以通过 HTTP 请求的方式，确保随时可以获取到最新的、有效的画布连接参数，例如：

const getQueryString = () => {
  // 从您的服务端获取到最新且有效的画布连接参数
  return fetch('...').then(...);
}

const initPromise = await InfiWebSdk.getSdkInstance({
  /** 画布会在尝试重连服务器时，获取最新的画布连接参数，确保能够正常与英飞画布云服务进行通信 */
  getQueryString,
  ...
});