嵌入式对接

SQLBot 支持通过【小助手嵌入】和【网页嵌入】的方式将智能问数能力嵌入到外部系统页面中。

其中【小助手嵌入】包含【基础应用】和【高级应用】两种模式，每种模式都支持「浮窗嵌入」和「全屏嵌入」两种呈现方式。

嵌入式 Demo 地址：https://github.com/dataease/sqlbot-embedded-demo

三类方式的区别主要按照权限划分，请对照选择合适的嵌入方式：

类别	权限	数据源	场景
基础应用	游客/员工	SQLBot	数据源
高级应用	宿主权限	宿主数据源(api 接口)	有权限要求，有自己的权限体系
页面嵌入	SQLBot 权限	SQLBot 数据源	有权限要求，无自己的权限体系

1 新建应用¶

1.1 小助手嵌入¶

1.1.1 基础应用¶

使用 admin 账号登录 SQLBot，切到系统设置菜单-嵌入式管理，新建对应的应用。

填写名称、描述、以及跨域设置

选择对应的工作空间并设置数据源权限小助手-基础应用有“游客/员工”简单权限模式，游客只能访问“公共”数据源

1.1.1 高级应用¶

高级应用在新建环节和基础应用的区别就是数据源，通过 API 接口的方式获取。

AES 加密：当开启 AES 加密时，宿主系统提供的 API 接口需对相关字段进行 AES 加密处理。
接口认证
- 在常见场景下，宿主 API 接口通常具备认证机制（如 Token、Cookie 等）。
- 这些认证凭证一般由前端页面存储，用户在 SQLBot 中填写接口凭证后，SQLBot 会在宿主页面上按需读取凭证并调用 API 接口，但不会存储任何凭证信息。
- 凭证的读取发生在每次“问数”时，SQLBot 根据获取到的凭证调用宿主系统的 API 接口。
httpOnly Cookie 场景：对于基于 httpOnly Cookie 的认证方式，由于 SQLBot 无法直接读取此类 Cookie，可以在数据源接口中额外定义一个认证凭证以实现访问。

注意：目标凭证字段（非必填）支持 JS 表达式，可灵活处理凭证值。

Demo 系统示例：

以下分别说明接口凭证各字段的含义：

源系统凭证：

类型：localStorage
凭证名称：sqlbot-embedded-token
含义：从 localStorage 中读取 key 为 sqlbot-embedded-token 的值。
示例代码：

var source_val = localStorage.getItem('sqlbot-embedded-token')

目标凭证

值： Bearer ${JSON.parse(JSON.parse(source_val).v)}。
含义：基于上一步获取的 source_val 进行解析并拼接成最终凭证。
示例代码：

source_val = `Bearer ${JSON.parse(JSON.parse(source_val).v)}`

目标凭证位置

位置：header
名称：sqlbot-embedded-token
含义：将拼接好的凭证放在请求头中，以 sqlbot-embedded-token 作为 Header 名称调用 API。

1.2 页面嵌入¶

填写名称、跨域设置：

记录 APP ID 以及 APP Secret，后面编码环节用得到。

2 宿主系统实现¶

下载 Demo 代码 https://github.com/dataease/sqlbot-embedded-demo

配置数据库信息：

在 frontend 目录执行

npm install;npm run build

在 backend 目录执行

npm install;npm run dev

访问 http://localhost:3000，如下图即运行正常

根据 SQLBot 中填写的信息填写系统设置表单，保存。当前是游客模式，登录后是 online 模式。

代码层面基础应用和高级应用嵌入方式基本没有区别。

2.1 浮窗模式¶

参考 assistan/float.vue 文件

把 sqlbot 提供的嵌入 js 加载到宿主系统。

如果是高级应用，必须登录才可以，因为要从页面获取凭证信息.

注意：

online 参数用来区别是否是游客；
userFlag 参数用来区分问数记录归属，userFlag 是大于 1 的数字；加载 js 资源最好判断一下是否已经加载过。

如接入成功，访问小助手浮窗宿主页面，右下角会出现浮动图标，如下图：

2.2 全屏模式¶

参考 assistant/full.vue 文件

如果是高级应用，必须登录才可以，因为要从页面获取凭证信息

接入成功页面如下

2.3 页面嵌入¶

参考 embedded/index.vue 文件

核心代码与全屏接入一样，只是调用 mounted 方法参数有区别。这里的 token 请在后端生成，避免泄漏 app secret。token 生成的逻辑是把 appId 和 account 作为 payload，appSecret 作为 secret。

接入成功页面如下

问数需要先选择数据源，与 SQLBot 页面一致

2.4 高级应用 API 接口¶

接口基本信息

项目	描述
接口名称	获取数据源信息
接口地址	自定义(例如：/datasource)
请求方法	GET
Content-Type	application/json
权限要求	根据宿主系统

响应

成功响应 http 200

响应体

名称	类型	示例值	描述
code	Integer	200	状态码，200 或者 0 成功
data	Array[ds]	[{...}, ...]	数据源信息
ds.name	String	demo-ds	名称，require
ds.type	String	pg	类型，require
ds.host	String	localhost	require
ds.port	Integer	5432	require
ds.dataBase	String	sqlbot_demo	require
ds.user	String	root	require
ds.password	String	xxxx	require
ds.schema	String	public
ds.comment	String	sqlbot-test-ds	描述，require
ds.tables	Array[table]	[{...},{...},...]	require
table.name	String	categories	require
table.sql	String		sql 优先级高于 table.name
table.comment	String	商品品类表	表描述，requre
table.fields	Array[field]	[{...},{...},...]	require
field.name	String	category_name	require
field.comment	String	品类名称	require
field.type	String	TEXT	跟随具体数据库的字段类型 require

响应示例：

{
    "code": 200,
    "data": [
        {
            "name": "数据源 1",
            "type": "mysql",
            "host": "192.168.1.1",
            "port": 3306,
            "user": "user",
            "password": "password",
            "dataBase": "sqlbot_demo",
            "schema": "schema",
            "comment": "数据源1备注信息",
            "tables": [
                // 无权限规则的数据表
                {
                    "name": "数据表 1",
                    "comment": "数据表 1 备注信息",
                    "fields": [
                        {
                            "name": "age",
                            "type": "bigint",
                            "comment": "字段 1备注信息"
                        },
                        {
                            "name": "gender",
                            "type": "text",
                            "comment": "字段 2备注信息"
                        }
                    ]
                },
                // 有权限限制的数据表，通过 sql 字段来限制
                {
                    "name": "数据表 2",
                    "comment": "数据表 2 备注信息",
                    "sql": "select name, gender, class, score from student where class = 1 and score > 80",
                    "fields": [
                        {
                            "name": "name",
                            "type": "TEXT",
                            "comment": "姓名"
                        },
                        {
                            "name": "class",
                            "type": "int",
                            "comment": "字段 3备注信息"
                        },
                        {
                            "name": "score",
                            "type": "int",
                            "comment": "字段 4备注信息"
                        }
                    ]
                }
            ]
        }
    ]
}

api 接口可以考虑预留参数 dsId 以及 tableId，以限定数据源和表进行问数。在多数据源场景下，对提升执行速度以及准确率都有明显效果。

问数之前，SQLBot 会在宿主页面获取凭证信息调用 API，可以利用 param 类型的凭证作为参数，但是要保证实时更新页面中的凭证。比如设置一个限定数据源 ID 的参数。

前端代码执行 localStorage.setItem(‘dsId’, xxx)

使用问数功能时，SQLBot 会获取存储在 localStorage 中的 dsId 拼接到 API 接口地址中 http://localhost:3000/api/datasource?dsId=xxx

如此，我想精确到某个表进行问数时，只需要在宿主页面前端执行

localStorage.setItem(‘dsId’, xxx);localStorage.setItem(‘tableId’, xxx)