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 NLAAIChat 提供的API适合以下场景开发：
- 觉得Smartbi内置的对话界面不好看，可以使用Smartbi扩展包机制重新开发使用界面
- 需要将对话嵌入到集团内部APP中，可以定制Android/IOS原生界面，或者嵌入自定义H5页面
- 需要嵌入到其他的Web平台中，可以定制H5页面
- 需要嵌入其聊天工具中（如：钉钉、微信等），可以定制符合聊天工具要求的页面
- 其他使用场景，可以咨询Smartbi客服团队，获取支持
...
如果是Web页面，推荐使用Smartbi扩展包方式开发集成页面。这样可以避免跨域问题。如果需要在第三方应用中开发，需要做对所有API做服务端转发。
3. API说明
Smartbi NLA二次开发，提供的是标准Restful AIChat二次开发，提供的是标准Restful API。只需要登录后，执行查询就可以了。所以，只需要2个API就可以完成需要的操作。
3.1
...
登录AIChat
...
通过账号密码登陆AIChat
3.1.1 接口说明
名称 | 值 |
请求地址 | |
请求方式 | POST |
请求参数 | userName password smartbiServer casLoginUrl loginMethod |
...
URL参数名 | 说明 | 是否必填 | |
输入参数 | userName | 登录账号 | 必填 |
password | 登录密码 | 必填 | |
smartbiServer | Smartbi服务器地址；该NLA服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Smartbi服务器Smartbi服务器地址；该AIChat服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Smartbi服务器 | 选填 | |
casLoginUrl | 如果Smartbi是使用CAS登录方式，则需要填入该值；该NLA服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Cas认证服务器如果Smartbi是使用CAS登录方式，则需要填入该值；该AIChat服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Cas认证服务器 | 选填 | |
loginMethod | 使用的登录方法；枚举值 login loginWithCas 普通登录使用login；如果是Cas登录则使用loginWithCas 默认情况下都可以不填 | 选填 | |
返回值 | { "code": 0, "result": { "userId": "", "userName": "", "userAlias": "", "isAdmin": }, "message": "", "token": "" } | ||
...
3.2.1 接口说明
名称 | 值 |
请求地址 | http://smartbi-nlaaichat-server:port/aiweb/integration/api/v1/get_using_theme |
请求方式 | POST |
请求参数 | token |
...
3.2.2 接口参数说明
URL参数名 | 说明 | 是否必填 | |
输入参数 | token | 登陆NLA两种方式返回获得的token登陆AIChat返回获得的token | 必填 |
返回值 | { "code": 0, "result": [ { "id": "I8a80818c0191262b262b26b0019126c8d71a****", "name": "****NLA-绩效考核-20240806", "title": "****NLA-绩效考核-20240806", "desc": "**证券NLA-绩效考核-20240806包含了年月、年、指标名称、指标口径、指标大类、指标负责人、指标细类、分支机构考核类别、所属考核组织类型、分支机构分组等字段", "type": "augmentedDataset", "recommendQuestion": [ "每年指标名称排名", "每年得分", "近5年指标名称得分", "排名按年份排序，线图显示", "排名的合计" ], "lastBuildTime": "2024/08/09 16:11:00" } ], "message": null, "token": "717261E64AEC5D904AA2410D127BFB27" } | ||
...
3.3.1 接口说明
名称 | 值 |
请求地址 | http://smartbi-nlaAIChat-server:port/aiweb/integration/api/v1/get_theme_tree |
请求方式 | POST |
请求参数 | token themeId type |
...
3.3.2 接口参数说明
URL参数名 | 说明 | 是否必填 | |
输入参数 | token | 登陆NLA两种方式返回获得的token登陆AIChat两种方式返回获得的token | 必填 |
themeId | 数据模型ID | 必填 | |
type | 传入参数值：augmentedDataset | 必填 | |
返回值 | { "code": 0, "result": [ { "id": "MEASURE", "parentId": null, "path": "/度量", "value": "MEASURE", "label": "度量", "dataType": "MEASURE_FOLDER", "fieldType": null, "timeLevel": null, "hasChild": "true", "defaultCheck": "false", "children": [ ] } ] }, { "id": "DIMENSION", "parentId": null, "path": "/维度", "value": "DIMENSION", "label": "维度", "dataType": "DIMENSION_FOLDER", "fieldType": null, "timeLevel": null, "hasChild": "true", "defaultCheck": "false", "children": [ ] } ] } ], "message": null, "token": "A381D523DD9C96754C2F40BA6365542F" } | ||
...
