...
NLA接口是基于Smartbi标准远程接口实现的，Smartbi的远程接口，Smartbi接口的调用方法如下：
参数名 | 说明 | |
接口URL | ||
输入参数 | className | 服务类名 |
methodName | 服务方法名 | |
params | 方法参数，以数组形式传递 | |
返回值 | 返回JSON对象 | |
retCode | 返回码：0 - 正确 | |
result | 方法返回结果，不同方法返回不一样 | |
duration | 执行时间：毫秒 | |
【PostMan - 登录方法测试样例】
4. 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时是错误信息 |
4.3 执行查询
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | query | ||
params | question | 问句 | |
token | loginIfSmartbiLogged方法获取的token | ||
isMultiRound | 是否多轮，设置false | ||
datasetId | 数据集Id，为空则自动识别数据集 | ||
reportId | 报表Id，设置为空 | ||
uuid | 设置为空 | ||
userChoseThemeId | 交互式问答选择的Id，或者用户强制的模型Id；设置为空 | ||
isMobileCall | 是否手机请求，设置为false | ||
getPageBO | 是否需要仪表盘定义，设置为false | ||
返回值 | retCode | 0 | 非0表示错误 |
result | 见下表 |
- query方法的返回值比较复杂，下表会详细说明query的返回值。
第一层result的属性 | 属性含义 | 说明 |
code | NLA请求返回码 | 0表示成功，负数表示错误，整数是路由码 |
message | 错误信息 | 负数才有值 |
result | JSON对象 | 不同的code，返回的内容不一样，详细内容见后续表格 |
- query返回 result.code=0，仅列举需要的属性（正确查询）
第二层result属性 | 属性含义 | 说明 |
uuid | 本次查询uuid | 记录查询日志id |
rowsCount | 本次查询结果数据总行数 | 表格才生效 |
currentRows | 当前返回数据行数 | 表格才生效 |
currentPage | 当前页码 | 表格才生效 |
rowsPerPage | 每页行数 | 表格才生效 |
clientId | 本次查询id | 记录查询id，用于翻页时标记查询缓存 |
html | 返回结果 | ● 如果是图形，则返回ECharts定义 ● 如果是表格直接返回html |
portletType | 仪表盘组件类型（queryType=PageQuery才生效） | ● ECHARTS_BAR 图形：柱图 ● ECHARTS_LINE 图形：线图 ● ECHARTS_PIE 图形：饼图 ● TABLE_LIST 表格：清单表 ● TABLE_CROSS 表格：交叉表 |
queryType | 查询类型 | ● PageQuery（数据模型、业务主题出图时） ● InsightQuery（业务主题） ● CombinedQuery（业务主题） |
question | 本次查询的问题 | |
resultTips | 本次查询的条件 | where或者having条件 |
themeId | 本次查询的数据模型/业务主题id |
- query返回 result.code=50，仅列举需要的属性（选择不确定实体）
- 啊啊啊
第二层result属性 | 属性含义 | 说明 |
intentionType | 选择类型 | ● sim_table 选择不确定的数据集（数据模型、业务主题） ● fuzzy_entity 选择不确定的维度、指标、成员 |
interActionItems | 需要选择的内容 | 用于构造界面 |
intentionParams | 模型识别参数 | 需要原样返回给服务器 |
- 选择数据集样例（sim_table ）
{
"queryIntention": "sim_table",
"rhetoricalQuestionType": "sim_table",
"desc": "发现多个相似表，请从以下列表进行选择并确认。",
"fuzzyObjects": null,
"alternatives": [
[
"业务主题：主流热销私家车",
"数据模型：hcy热销车"
]
],
"alternativesRealValue": [
[
"THEME.demo2019.CSAC汽车销售分析",
"I8a8aa3ed017bc404c404760a017bc40bc0b90004"
]
],
"userSelected": null,
"otherParams": "{\"system_question\":\"发现多个相似表，请从以下列表进行选择并确认。\",\"id_list\":[[\"THEME.demo2019.CSAC汽车销售分析\",\"I8a8aa3ed017bc404c404760a017bc40bc0b90004\"]],\"fuzzy_entity_list\":[],\"option_list\":[[\"业务主题：主流热销私家车\",\"数据模型：hcy热销车\"]],\"theme_id\":\"\",\"question_ori\":\"去年长安各车型的销售量\"}"
},
...
该方法，最主要就是设置 interActionInput.userSelected
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | rhetoricalQuestionResultInput | ||
params | question | 问句 | |
datasetId | 数据集Id，query返回的themeId | ||
uuid | query返回的uuid | ||
isMultiQuery | 多否多轮查询，设置false | ||
multiMark | 多选标记，设置空 | ||
interActionInput | 在query方法返回的interActionItems属性基础上，添加了userSelected属性内容，填写了用户选择的内容的Id（在interActionItems属性中有提供） | ||
intentionParams | 把query返回的结果中的intentionParams属性原样传递回服务器 | ||
token | loginIfSmartbiLogged方法获取的token | ||
isMobileCall | 是否手机请求，设置为false | ||
getPageBO | 是否需要仪表盘定义，设置为false | ||
返回值 | retCode | 0 | 参考query方法 |
result | 参考query方法 |
4.5 选择不确定的模型
该方法，最主要就是设置 datasetId
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | AIChatRemoteService | |
methodName | manualChangeTheme | ||
params | token | loginIfSmartbiLogged方法获取的token | |
question | 问句 | ||
datasetId | 用户在界面上选择的模型Id | ||
uuid | query返回的uuid | ||
isMobileCall | 是否手机请求，设置为false | ||
getPageBO | 是否需要仪表盘定义，设置为false | ||
返回值 | retCode | 0 | 参考query方法 |
result | 参考query方法 |
4.6 退出登录
URL参数名 | URL参数值 | 说明 | |
输入参数 | className | UserService | |
methodName | logout | ||
params | [] | 样例：[] | |
返回值 | retCode | 0 | 非0表示错误 |
result |
5. Demo开发设计
本次教程，仅以Web开发作为示例，说明如何调用Smartbi NLA的二次开发API实现自定义对话界面的过程。Android应用和IOS应用基本调用API的方法是一致的，区别只是使用的开发平台不同。开发工程师需要在对应的开发平台上做调整。
...
@startuml
前端HTML -> JS_API: 调用前端接口
JS_API --> APIController: 调用服务端接口
APIController --> SmartbiAPI: 调用Java远程接口
SmartbiAPI --> Smartbi_Server: 调用Smartbi接口
@enduml
【接口调用时序】
6.2.1 主要代码文件说明
文件 | 说明 | |
后端Java代码 | SmartbiAPI.java | Smartbi api 接口 |
APIController.java | 演示程序，提供给前端的接口，实现内容与SmartbiAPI.java对应 | |
前端JS | api.js | 前端API接口，与APIController.java 对应 |
components/result-view.js | 查询结果展示路由组件 | |
components/query-tip.js | 查询条件展示组件 | |
components/select-entity.js | 选择实体展示组件 | |
components/result/chart-view.js | 图形显示组件 | |
components/result/table-view.js | 表格显示组件 | |
components/result/text-view.js | 文字显示组件 | |
components/result/select-view.js | 模糊实体选择组件 | |
前端HTML | index.html | 页面文件 |
6.3 登录
【登录部分】
<el-form :inline="true" :model="form1" class="demo-form-inline">
<el-form-item label="账号：">
<el-input v-model="form1.user" placeholder="账号"></el-input>
</el-form-item>
<el-form-item label="密码：">
<el-input v-model="form1.password" placeholder="密码" show-password></el-input>
</el-form-item>
<el-form-item label="Smartbi地址：">
<el-input v-model="form1.server" placeholder="Smartbi地址" style="width:350px"></el-input>
</el-form-item>
<el-form-item>
<el-button type="primary" @click="login" :disabled="loginOk">登录</el-button>
</el-form-item>
</el-form>
...
- rhetoricalQuestionResultInput接口中的 interactionItem 属性，主要是复制 query接口返回的 interActionItems 属性内容，其中需要补充设置 userSelected 属性。
- userSelected的内容来源于 query 接口返回的 alternativesRealValue 属性，只设置用户选定的序号内容即可。
