1.接口需求背景与适用场景

1.1 需求背景

Smartbi AIChat本身是提供了多种客户端供用户选择的。如果常用PC，我们有基于PC浏览器的AIWeb页面；如果常用手机，我们有基于手机的App或者使用手机浏览器访问的AIChatView页面；我们还提供了基于钉钉的使用页面。

但是，这些都是Smartbi AIChat平台内置的使用页面，页面样式和操作方式是基于产品内置好的。如果用户想把自然语言查询集成到用户自己的APP里面，或者集成到用户其他的平台里面，我们内置的页面样式可能不太符合用户的要求，集成起来就不自然。

为了让用户在使用Smartbi自然语言查询的时候，可以自定义前端页面，我们提供了基于Java语言实现的RestFul API接口。本文主要就是介绍如何使用Smartbi AIChat的接口实现自己的前端页面。

1.2 适用场景

使用Smartbi AIChat 提供的API适合以下场景开发：

觉得Smartbi内置的对话界面不好看，可以使用Smartbi扩展包机制重新开发使用界面
需要将对话嵌入到集团内部APP中，可以定制Android/IOS原生界面，或者嵌入自定义H5页面
需要嵌入到其他的Web平台中，可以定制H5页面
需要嵌入其聊天工具中（如：钉钉、微信等），可以定制符合聊天工具要求的页面
其他使用场景，可以咨询Smartbi客服团队，获取支持

2. 逻辑架构

【用户自定义对话界面-逻辑架构图】

说明：

用户自定义界面，可以脱离Smartbi，嵌入在第三方平台里面，包括：
- 第三方Web应用
- 第三方Android应用
- 第三方IOS应用

如果是Web页面，推荐使用Smartbi扩展包方式开发集成页面。这样可以避免跨域问题。如果需要在第三方应用中开发，需要做对所有API做服务端转发。

3. API说明

Smartbi AIChat二次开发，提供的是标准Restful API。只需要登录后，执行查询就可以了。所以，只需要2个API就可以完成需要的操作。

4.接口说明

4.1 登录AIChat

4.1.1 接口说明

名称	值
请求地址	http://smartbi-AIChat-server:port/aiweb/api/v1/login
请求方式	POST
请求参数	userName password smartbiServer casLoginUrl loginMethod

4.1.2 接口参数说明

	URL参数名	说明	是否必填
输入参数	userName	登录账号	必填
	password	登录密码	必填
	smartbiServer	Smartbi服务器地址；该AIChat服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Smartbi服务器	选填
	casLoginUrl	如果Smartbi是使用CAS登录方式，则需要填入该值；该AIChat服务器第一次登录Smartbi，必填；以后选填；不填则使用之前已经登录过的Cas认证服务器	选填
	loginMethod	使用的登录方法；枚举值 login loginWithCas 普通登录使用login；如果是Cas登录则使用loginWithCas 默认情况下都可以不填	选填
返回值	{ "code": 0, "result": { "userId": "", "userName": "", "userAlias": "", "isAdmin": }, "message": "", "token": "" }

4.1.3 接口返回值说明

返回参数名	返回值说明
code	接口调用是否成功；0 - 表示成功；负数为错误码
message	错误描述，code=0 时，该内容为空
token	登录方法特有内容，这个非常重要，后续接口需要传递该值以验证登录
result	调用接口的返回内容，登录接口的返回内容说明如下： "userId": "", Smartbi中的用户Id "userName": "", Smartbi中的用户名 "userAlias": "", Smartbi中的用户中文名 "isAdmin": 在Smartbi中是否是管理员

4.1.4 调用示例（PostMan调用截图）

4.2 查询接口（异步）

	名称	描述	默认值
接口路径	http://host:port/aiweb/api/v3/conv/query
接口说明	V3版本查询方法 -- 异步方法 -- SSE请求
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
	datasetId	数据模型Id
	question	用户问题
	queryType	查询类型： analysis（分析模式） expert（专家模式）	建议使用：analysis
	id	本次对话id 从外部传入才能做点赞点踩
	need_inquiry	本次查询是否需要使用反问功能	default(true)
返回内容	返回SSE对象，前端处理 SSE返回报文样例： {"role": "SimpleQuery", "response_status": "generating code", "response_message": " \"", "execution_result": "", "send_to": "Unknown", "response_type": "python"} ... SSE 接口会返回很多条这样的报文；具体原理请自行查询百度。请手工拼接返回报文 "response_message" 和 "execution_result" 部分内容；response_type 表示当前这条报文的返回内容是啥。

服务端调用可参照以下示例代码（可展开源码阅读）：

JAVA示例代码

    	String server = "http://域名:端口/smartbi";
    	String user = "user";
    	String password = "password";

    	ObjectMapper mapper = new ObjectMapper();
    	Map<String, String> cookies = new HashMap<>();
    	HttpRequest request = HttpRequest.get(server + "/vision/openresource.jsp?resid=I402882c701552f492f49736e01552f4df2c50013&user=" + user + "&password=" + password);
    	try (HttpResponse response = request.execute()) {
	    	for (HttpCookie cookie : response.getCookies()) {
	    		cookies.put(cookie.getName(), cookie.getValue());
	    	}
    	}
    	request = HttpRequest.post(server + "/vision/aichat/proxy/api/v1/login")
    			.cookie(toCookie(cookies))
    			.form("userName", user)
    			.form("smartbiServer", server)
    			.form("loginMethod", "login")
    			.form("cookie", toCookie(cookies));
    	String token = null;
    	try (HttpResponse response = request.execute()) {
	    	for (HttpCookie cookie : response.getCookies()) {
	    		cookies.put(cookie.getName(), cookie.getValue());
	    	}
	    	JsonNode tree = mapper.readTree(response.body());
			token = tree.get("token").asText();
    	}
    	Thread.sleep(5000); // 旧版本由于存在问题，需要 sleep。 新版本后不需要
    	request = HttpRequest.post(server + "/vision/aichat/proxy/api/v3/conv/query")
    			.cookie(toCookie(cookies))
    			.header("token", token)
    			.form("datasetId", "Iff808081018354c854c8f0fa018354cbde880001")
    			.form("convId", "70c69b66-7af7-45fc-b51c-b486ceba1a43")
    			.form("question", "车均价 ")
    			.form("queryType", "analysis")
    			.form("id", "285fce7d-14e2-4a63-ab33-cf9abf09c41f")
    			.form("pageSize", "10000")
    			.form("showRows", "1000")
    			.form("need_inquiry", "false")
    			.form("onlyQueryChart", "false")
    			.form("autoRecommendedChart", "false");    	
		try (HttpResponse response = request.execute()) {
			System.out.println(response.body());
		}

4.3 查询接口（同步）

	名称	描述	默认值
接口路径	http://host:port/aiweb/api/v3/conv/query_sync
接口说明	V3版本查询方法 -- 同步方法
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
	datasetId	数据模型Id
	question	用户问题
	queryType	查询类型： query（查询模式） analysis（分析模式） expert（专家模式）	建议使用：analysis
	id	本次对话id 从外部传入才能做点赞点踩
	need_inquiry	本次查询是否需要使用反问功能	default(true)
返回内容	返回查询结果（JSON），前端处理 { "code": 0, "result": "[\"[{\\\"年月\\\":\\\"2019-01\\\",\\\"销量\\\":132912,\\\"销量环比增长率\\\":\\\"-6.06%\\\",\\\"_销量占比\\\":\\\"8.8272%\\\"},...]", "message": null } code=0，表示返回正确（result是返回结果）；否则message就是错误提示。

4.4 中断查询

	名称	描述	默认值
接口路径	http://host:port/aiweb/api/v3/conv/stop_stream
接口说明	异步query方法情况下，中断当前查询
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：方法执行返回结果 -- 服务端无返回则为空 }

4.5 新建查询对话

	名称	描述	默认值
接口路径	http://host:port/aiweb/api/v3/conv/new
接口说明	新建查询对话
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：方法执行返回结果 -- 服务端无返回则为空 }

4.6 关闭查询对话

	名称	描述	默认值
接口路径	http://host:port/aiweb/api/v3/conv/close
接口说明	关闭查询对话 -- 结束本次多轮对话
header	token	登录key，使用login方法获取；login方法请参考：
接口参数	convId	会话Id
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：方法执行返回结果 -- 服务端无返回则为空 }

4.7 获取本次对话推荐数据模型

	名称	描述	默认值
接口路径	http://host:port/aiweb/api/v3/conv/recommend_dataset
接口说明	获取本次对话推荐数据模型
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
	question	用户提问
	datasetId	当前数据模型id
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：获取推荐的数据模型列表 }

4.8 获取本次对话的详细查询步骤和内容

	名称	描述	默认值
接口路径	http://host:port/aiweb/#/testTool?answerid=${id} GET请求示例： http://10.10.35.110:9070/aiweb/#/testTool2?answerid=01fc76d5-7ec4-4fad-8216-d4b829ac740c
接口说明	获取本次对话的详细查询步骤和内容这个基本是前端接口，需要前端js辅助解析的，所以无法直接提供给第三方调用
接口参数	id	本次对话Id
返回内容	查询步骤说明html页面

4.9 获取当前用户可以使用的数据模型列表

名称	描述	默认值
接口路径	http://host:port/aiweb/proxy/aibus/get_using_themes
接口说明	获取当前用户可以使用的数据模型列表
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：[{ "id": 数据模型themeID "name": 数据模型名称 "title": 数据模型名称别名 "desc"：数据模型概览 "type": 数据类型 "recommendQuestion": 推荐问句 "lastBuildTime": 最近构建时间 }]}

4.10 获取当前用户会话历史

名称	描述	默认值
接口路径	http://host:port/aiweb/proxy/admin/v3/db/conv/get_list_by_user
接口说明	获取当前用户可以使用的数据模型列表
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	userName	当前用户名
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：[{ _id: 对话Id （convId）, name: 对话名称, endTime: 对话结束时间（时间戳 – long） }]}

4.11 打开对话历史

名称	描述	默认值
接口路径	http://host:port/aiweb/proxy/admin/v3/db/conv/get_by_convid
接口说明	获取当前用户可以使用的数据模型列表
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result：[{ id: 消息Id convId：会话Id, name: 对话名称, answer：消息返回报文 – 主要是解析这个内容 beginTime：消息开始时间 endTime: 消息结束时间（时间戳 – long） ... }]}

4.12 删除对话历史

名称	描述	默认值
接口路径	http://host:port/aiweb/proxy/admin/v3/db/conv/remove_by_convid
接口说明	获取当前用户可以使用的数据模型列表
header	token	登录key，使用login方法获取；login方法请参考：登录AIChat
接口参数	convId	会话Id
返回内容	{ code: 错误码（0 - 表示正确） message：错误描述 result："" }

5.界面集成

	名称	描述	默认值
URL路径	/smartbi/vision/AIChatV3.html GET请求示例： http://10.10.35.110:9070/smartbi/vision/AIChatV3.html
集成说明	本地址为bi里面的地址，必须登录bi后再使用。可以跳过登录步骤，直接打开v3的界面
参数	无

关注我们

服务支持

页面树结构

Smartbi NLA V3 接口说明文档