1. 需求背景与适用场景
1.1 需求背景
Smartbi NLA 本身是提供了多种客户端供用户选择的。如果常用PC，我们有基于PC浏览器的AIWeb页面；如果常用手机，我们有基于手机的App或者使用手机浏览器访问的AIChatView页面；我们还提供了基于钉钉的使用页面。AIChat本身是提供了多种客户端供用户选择的。如果常用PC，我们有基于PC浏览器的AIWeb页面；如果常用手机，我们有基于手机的App或者使用手机浏览器访问的AIChatView页面；我们还提供了基于钉钉的使用页面。
但是，这些都是Smartbi NLA平台内置的使用页面，页面样式和操作方式是基于产品内置好的。如果用户想把自然语言查询集成到用户自己的APP里面，或者集成到用户其他的平台里面，我们内置的页面样式可能不太符合用户的要求，集成起来就不自然。AIChat平台内置的使用页面，页面样式和操作方式是基于产品内置好的。如果用户想把自然语言查询集成到用户自己的APP里面，或者集成到用户其他的平台里面，我们内置的页面样式可能不太符合用户的要求，集成起来就不自然。
为了让用户在使用Smartbi自然语言查询的时候，可以自定义前端页面，我们提供了基于Java语言实现的RestFul API接口。本文主要就是介绍如何使用Smartbi NLA的接口实现自己的前端页面。AIChat的接口实现自己的前端页面。
1.2 适用场景
使用Smartbi NLA 提供的API适合以下场景开发：AIChat 提供的API适合以下场景开发：
- 觉得Smartbi内置的对话界面不好看，可以使用Smartbi扩展包机制重新开发使用界面
- 需要将对话嵌入到集团内部APP中，可以定制Android/IOS原生界面，或者嵌入自定义H5页面
- 需要嵌入到其他的Web平台中，可以定制H5页面
- 需要嵌入其聊天工具中（如：钉钉、微信等），可以定制符合聊天工具要求的页面
- 其他使用场景，可以咨询Smartbi客服团队，获取支持
...
如果是Web页面，推荐使用Smartbi扩展包方式开发集成页面。这样可以避免跨域问题。如果需要在第三方应用中开发，需要做对所有API做服务端转发。
3. Smartbi接口调用说明
NLA接口是基于Smartbi标准远程接口实现的，Smartbi的远程接口，Smartbi接口的调用方法如下：AIChat接口是基于Smartbi标准远程接口实现的，Smartbi的远程接口，Smartbi接口的调用方法如下：
参数名 | 说明 | |
接口URL | ||
输入参数 | className | 服务类名 |
methodName | 服务方法名 | |
params | 方法参数，以数组形式传递 | |
返回值 | 返回JSON对象 | |
retCode | 返回码：0 - 正确 | |
result | 方法返回结果，不同方法返回不一样 | |
duration | 执行时间：毫秒 | |
...
【PostMan - 登录方法测试样例】
4. API说明
Smartbi NLA提供了比较丰富的二次开发API，本次Demo只使用了一部分。这个章节，重点介绍下本次Demo使用的API。AIChat提供了比较丰富的二次开发API，本次Demo只使用了一部分。这个章节，重点介绍下本次Demo使用的API。
以下介绍的接口，调用方法和调用URL是一样的，区别仅仅是参数不同，所以对每个API不会重复介绍调用方法，具体调用方法请参考：上一章节的 “Smartbi接口调用说明”
...
URL参数名 | URL参数值 | ||
输入参数 | className | UserService | |
methodName | clickLogin | ||
params | userName | 样例：["demo","demo"] | |
password | |||
返回值 | retCode | 0 | 非0表示错误 |
result | true | 非0时是错误信息 |
4.2
...
登录AIChat
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | loginIfSmartbiLogged | ||
params | [] | 样例：[] | |
返回值 | retCode | 0 | 非0表示错误 |
result | {\"token\":\"CE3CE70AC12B70052A507D4B560E5374\"} | NLA 的token信息，这个非常重要，后续NLA所有方法需要用到这个token；AIChat 的token信息，这个非常重要，后续AIChat所有方法需要用到这个token； 非0时是错误信息 |
备注：登陆NLA前需要登陆成功Smartbi（通过账户密码备注：登陆AIChat前需要登陆成功Smartbi（通过账户密码/单点/其他登陆方式）
4.3 查询数据模型清单、推荐问句
...
返回参数名 | 返回值说明 |
reCode | 接口调用是否成功；大于等于0 - 表示成功；负数为错误码 |
message | 错误描述，recode=0 时，该内容为空 |
token | 登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录 |
result | 调用接口的返回内容，登录接口的返回内容说明如下： "id": 数据模型themeID "name": 数据模型名称 "alias": 数据模型名称别名 "dimensions" NLA模型中所有维度 AIChat模型中所有维度 "measures" NLA模型中所有度量 AIChat模型中所有度量 "recommendQuestions" 推荐问句 ... 其他返回值可以忽略 |
...
返回值 | { "code": 0, "result": { "currentRows": "", "currentPage": "", "rowsPerPage": "", "portletType":"", "html":"", "nl2sql":"", "llm":"", ... }, "message": "", "token": "" } |
- 接口返回说明
第一层result的属性 | 属性含义 | 说明 |
retCode |
AIChat请求返回码 | 0表示成功，负数表示错误，整数是路由码 | |
message | 错误信息 | 负数才有值 |
result | JSON对象 | 不同的retCode，返回的内容不一样，详细内容见后续表格 |
| token | token信息 | 登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录 |
- query返回 result.code=0，仅列举主要的属性（正确查询）
...
返回值 | { "reCode": 0, "duration": "36" } |
- 接口调用成功后，会将点赞点踩相关信息写入NLA的数据库服务中对应表中：接口调用成功后，会将点赞点踩相关信息写入AIChat的数据库服务中对应表中：
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 |
...
4.10 清除对话历史（开启新对话）
Smartbi NLA 是可以启用“多轮对话”和“单轮对话”的，具体操作方法在对话式分析主页面中勾选，这里不详细描述。在启用多轮对话的时候，AIChat 是可以启用“多轮对话”和“单轮对话”的，具体操作方法在对话式分析主页面中勾选，这里不详细描述。在启用多轮对话的时候，
有时需要清空对话历史（也就是开启新的对话）。开启新对话需要使用该API实现。
...
返回参数名 | 返回值说明 |
retCode | 接口调用是否成功；0 - 表示成功；负数为错误码 |
5. 页面集成
SmartBi NLA提供三种页面集成的方式 AIChat提供三种页面集成的方式 。
5.1 页面集成方式一
名称 | 值 |
请求地址 | |
参数说明 | question：问句，可以选填 userName：用户名 password：密码 |
请求URL：http://smartbi-nlaAIChat-server:port/smartbi/vision/AIChatView2.html?userName=admin&password=admin
...
5.2 页面集成方式二
名称 | 值 |
请求地址 | |
参数说明 | userName：用户名 password： 密码 surl ：/smartbi/smartbix/#/sdk |
...
