1. 需求背景与适用场景
1.1 需求背景
Smartbi NLA 本身是提供了多种客户端供用户选择的。如果常用PC，我们有基于PC浏览器的AIWeb页面；如果常用手机，我们有基于手机的App或者使用手机浏览器访问的AIChatView页面；我们还提供了基于钉钉的使用页面。
...
为了让用户在使用Smartbi自然语言查询的时候，可以自定义前端页面，我们提供了基于Java语言实现的RestFul API接口。本文主要就是介绍如何使用Smartbi NLA的接口实现自己的前端页面。
1.2 适用场景
使用Smartbi NLA 提供的API适合以下场景开发：
- 觉得Smartbi内置的对话界面不好看，可以使用Smartbi扩展包机制重新开发使用界面
- 需要将对话嵌入到集团内部APP中，可以定制Android/IOS原生界面，或者嵌入自定义H5页面
- 需要嵌入到其他的Web平台中，可以定制H5页面
- 需要嵌入其聊天工具中（如：钉钉、微信等），可以定制符合聊天工具要求的页面
- 其他使用场景，可以咨询Smartbi客服团队，获取支持
2. 逻辑架构
【用户自定义对话界面-逻辑架构图】
说明：
- 用户自定义界面，可以脱离Smartbi，嵌入在第三方平台里面，包括：
- 第三方Web应用
- 第三方Android应用
- 第三方IOS应用
...
如果是Web页面，推荐使用Smartbi扩展包方式开发集成页面。这样可以避免跨域问题。如果需要在第三方应用中开发，需要做对所有API做服务端转发。
3. Smartbi接口调用说明
NLA接口是基于Smartbi标准远程接口实现的，Smartbi的远程接口，Smartbi接口的调用方法如下：
参数名 | 说明 | |
接口URL | ||
输入参数 | className | 服务类名 |
methodName | 服务方法名 | |
params | 方法参数，以数组形式传递 | |
返回值 | 返回JSON对象 | |
retCode | 返回码：0 - 正确 | |
result | 方法返回结果，不同方法返回不一样 | |
duration | 执行时间：毫秒 | |
【PostMan - 登录方法测试样例】
4. API说明
Smartbi NLA提供了比较丰富的二次开发API，本次Demo只使用了一部分。这个章节，重点介绍下本次Demo使用的API。
以下介绍的接口，调用方法和调用URL是一样的，区别仅仅是参数不同，所以对每个API不会重复介绍调用方法，具体调用方法请参考：上一章节的 “Smartbi接口调用说明”
4.1 登录Smartbi
URL参数名 | URL参数值 | ||
输入参数 | className | UserService | |
methodName | clickLogin | ||
params | userName | 样例：["demo","demo"] | |
password | |||
返回值 | retCode | 0 | 非0表示错误 |
result | true | 非0时是错误信息 |
4.2 登录NLA
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | loginIfSmartbiLogged | ||
params | [] | 样例：[] | |
返回值 | retCode | 0 | 非0表示错误 |
result | {\"token\":\"CE3CE70AC12B70052A507D4B560E5374\"} | NLA 的token信息，这个非常重要，后续NLA所有方法需要用到这个token； 非0时是错误信息 |
备注：登陆NLA前需要登陆成功Smartbi（通过账户密码/单点/其他登陆方式）
4.3 查询数据模型清单、推荐问句
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | getBuildThemes | ||
params | |||
token | loginIfSmartbiLogged方法获取的token | ||
返回值 | retCode | 0 | 参考query方法 |
result | 参考query方法 |
...
返回参数名 | 返回值说明 |
retCode | 接口调用是否成功；大于等于0 - 表示成功；负数为错误码 |
result | 调用接口的返回内容，登录接口的返回内容说明如下： "id": 数据模型themeID "name": 数据模型名称 "title": 数据模型名称别名 "desc"： 数据模型概览 "type": 数据类型 "recommendQuestion": 推荐问句 "lastBuildTime": 最近构建时间 ... 其他返回值可以忽略 |
4.4 维度指标树、推荐问句
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | getDataSetInfoSummary | ||
params | token | loginIfSmartbiLogged方法获取的token | |
sourceId | 用户在界面上选择的数据模型themeId | ||
返回值 | retCode | 0 | 参考query方法 |
result | 参考query方法 |
...
返回参数名 | 返回值说明 |
reCode | 接口调用是否成功；大于等于0 - 表示成功；负数为错误码 |
message | 错误描述，recode=0 时，该内容为空 |
token | 登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录 |
result | 调用接口的返回内容，登录接口的返回内容说明如下： "id": 数据模型themeID "name": 数据模型名称 "alias": 数据模型名称别名 "dimensions" NLA模型中所有维度 "measures" NLA模型中所有度量 "recommendQuestions" 推荐问句 ... 其他返回值可以忽略 |
4.5 执行查询
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | query | ||
params | txt | 问句 | |
token | loginIfSmartbiLogged方法获取的token | ||
| isMultiQuery | 查询类型，该参数为空，则由AIBus判断是否多轮 | ||
themeId | 数据模型id，可为空，有推荐 | ||
reportId | 报表Id，设置为空 | ||
uuid | 设置为空 | ||
userChoseThemeId | 用户选择的模型id 用于锁定模型查询，设置为空 | ||
isMobileCall | 是否手机请求，设置为false | ||
getPageBO | 是否需要仪表盘定义，设置为false | ||
| subTable | 子表 | ||
| llmReviseQuestionWithUserGuide | 合并问句 | ||
| returnPrompt | 是否返回提示词，字符串：true，false | ||
| returnJSON | 是否返回json数据 | ||
返回值 | retCode | 0 | 非0表示错误 |
result | 见下表 |
...
中文名 | PortletType / chartType |
汇总表 | TABLE_LIST |
清单表 | TABLE_DETAIL_LIST |
交叉表 | TABLE_CROSS |
柱图 | ECHARTS_BAR |
横条图 | ECHARTS_BAR__HORIZONTAL |
线图 | ECHARTS_LINE |
饼图 | ECHARTS_PIE |
圆环图 | ECHARTS_PIE__DONUT |
散点图 | ECHARTS_SCATTER |
泡泡图 | ECHARTS_SCATTER__BUBBLE |
4.6 点赞点踩
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | feedBack | ||
params | token | loginIfSmartbiLogged方法获取的token | |
| uuid | query接口查询的问句返回的uuid唯一标识 | ||
| tag | 1-为正确，0-为错误 | ||
feedbackText | 人工输入，反馈内容 | ||
返回值 | retCode | 0 | 非0表示错误 |
result |
...
- 接口调用成功后，会将点赞点踩相关信息写入NLA的数据库服务中对应表中：
4.7 切换图形
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | queryWithNl2sql | ||
params | token | loginIfSmartbiLogged方法获取的token | |
| nl2sql | query接口返回的n2lsql值， 注：需要将value值中转义符\去除，并且注意json格式 ("{'key':'value'}"注意单引号与双引号的使用） | ||
| sourceId | 数据模型ID | ||
chartType | 图形类型， 举例：ECHARTS_BAR | ||
返回值 | retCode | 0 | 非0表示错误 |
result |
...
返回参数名 | 返回值说明 |
retCode | 接口调用是否成功；大于等于0 - 表示成功；负数为错误码 |
message | 错误描述，code=0 时，该内容为空 |
token | 登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录 |
result | 调用接口的返回内容，登录接口的返回内容说明如下： "html": 切换后的图表的html "portletType": 切换后的图标的类型 ... 其他返回值可以忽略 |
4.8 查询结果设置输出行数
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | setRowsPerPage | ||
params | clientId | 用户的查询问句的clientId（可以从执行查询接口获取） | |
| pageSize | 设置每页输出大小 | ||
| queryType | 用户的查询问句的queryType（可以从执行查询接口获取) | ||
dataSource | 数据来源，通常固定为smartbiproxy | ||
| token | loginIfSmartbiLogged方法获取的token | ||
返回值 | retCode | 0 | 非0表示错误 |
result |
...
返回参数名 | 返回值说明 |
retCode | 接口调用是否成功；0 - 表示成功；负数为错误码 |
message | 错误描述，code=0 时，该内容为空 |
token | 登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录 |
result | 调用接口的返回内容 |
4.9 查询结果分页
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | queryWithPage | ||
params | token | loginIfSmartbiLogged方法获取的token | |
| clientId | 用户的查询问句的clientId（可以从执行查询接口获取） | ||
| page | 设置翻页，第几页 | ||
dataSource | 数据来源，通常固定为smartbiproxy | ||
| queryType | 用户的查询问句的queryType（可以从执行查询接口获取) | ||
返回值 | retCode | 0 | 非0表示错误 |
result |
...
返回参数名 | 返回值说明 |
retCode | 接口调用是否成功；0 - 表示成功；负数为错误码 |
token | 登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录 |
result | 调用接口的返回内容，登录接口的返回内容说明如下： "currentRows": 当前页行数 "currentPage": 当前页码 "rowsPerPage": 每页行数 "portletType"： 显示类型（表格、图形等） "html": 如果是表格，为html，如果是图形为Echarts Options ... |
4.10 清除对话历史（开启新对话）
Smartbi NLA 是可以启用“多轮对话”和“单轮对话”的，具体操作方法在对话式分析主页面中勾选，这里不详细描述。在启用多轮对话的时候，
...
返回参数名 | 返回值说明 |
retCode | 接口调用是否成功；0 - 表示成功；负数为错误码 |
5. 页面集成
SmartBi NLA提供三种页面集成的方式 。
5.1 页面集成方式一
名称 | 值 |
请求地址 | |
参数说明 | question：问句，可以选填 userName：用户名 password：密码 |
请求URL：http://smartbi-nla-server:port/smartbi/vision/AIChatView2.html?userName=admin&password=admin
5.2 页面集成方式二
名称 | 值 |
请求地址 | |
参数说明 | userName：用户名 password： 密码 surl ：/smartbi/smartbix/#/sdk |
5.3 页面集成方式三
嵌入式集成（iframe嵌入需注意可能会有跨域问题）
...
