本文针对智能数据助理的开放接口,和接入过程中需要客户开发的本地服务接口进行说明
对话OpenAPI
1.SDK下载地址
maven仓库地址:https://oss.sonatype.org/content/repositories/releases/
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>databot20200330</artifactId>
<version>1.0.0</version>
</dependency>
2.地址参数
domain:databot.cn-shanghai.aliyuncs.com
region:cn-shanghai
product:databot
3.配置参数
accesskeyid:<阿里云用户acckeyid>
accesskeysecret:<阿里云用户acckeysecret>
4.请求参数
参数名 |
类型 |
必填 |
备注 |
---|---|---|---|
action |
String |
是 |
固定为:QueryDataBot |
protocol |
String |
是 |
默认为"HTTPS" |
method |
String |
是 |
默认为"POST" |
version |
String |
是 |
默认为"2020-03-30" |
authtype |
String |
是 |
默认为"ak" |
accessId |
String |
是 |
机器人对话api访问接入id,请从机器人工作台获取 |
query |
String |
是 |
查询语句 |
sessionId |
String |
否 |
标记一个session会话,多轮对话必填 |
context |
Map<String,Object> |
否 |
其他扩展参数 |
其中:
-
query:是用户输入的非结构化文本,是唯一的业务必填参数
-
sessionId:为可选参数,仅当多轮对话时需要
-
context可以包含其他业务自定义请求参数
-
map中的key也由调用方自定义或者双方约定
5.返回参数
根据机器人控制台配置返回时markdown、json格式:
markdown
字段名 |
类型 |
描述 |
code |
int |
是 |
msg |
string |
否 |
data |
string |
markdown返回结果 |
json数据格式
字段名 |
类型 |
描述 |
code |
int |
错误码 |
msg |
string |
错误信息 |
data |
ResponseContentDTO |
json数据结果 |
其中:ResponseContentDTO
字段名 |
类型 |
描述 |
备注 |
charts |
ChartOption |
图表数据 |
图表普通查询返回 |
extOptions |
List<ExtOption> |
智能推荐、推荐指标 |
图表普通查询返回 |
factorOption |
FactorOption |
分析结果 |
智能分析查询返回 |
ChartOption
字段名 |
类型 |
描述 |
data |
List<DataCell> |
趋势图数据 |
option |
string |
图表配置 |
DataCell
字段名 |
类型 |
描述 |
value |
string |
format之后的结果值 |
raw |
Object |
原始数据值 |
type |
string |
cell类型表头:ROW_HEADER数据:为空 |
properties |
Map<String, Object> |
表头:需要包含caption、formatString属性数据: 可为空 |
ExtOption
字段名 |
类型 |
描述 |
title |
string |
展示标题 |
type |
string |
展示类型 |
content |
string |
展示内容 |
FactorOption
字段名 |
类型 |
描述 |
reason |
Reason |
原因解析 |
conclusion |
Conclusion |
结论 |
Reason
字段名 |
类型 |
描述 |
content |
string |
原因描述 |
operation |
Operation |
下钻操作operation |
Conclusion
字段名 |
类型 |
描述 |
content |
string |
原因描述 |
Operation
字段名 |
类型 |
描述 |
echo |
string |
操作query |
show |
string |
展示信息 |
6.示例
查询请求模型DatabotRequest
package com.alibaba.iic.dbot.bfw.bizadapter.common;
import com.aliyun.databot20200330.models.QueryDatabotRequest;
import com.aliyun.tea.NameInMap;
import com.aliyun.tea.TeaModel;
public class DatabotRequest extends QueryDatabotRequest {
@NameInMap("AccessId")
public String accessId;
@NameInMap("Query")
public String query;
public static DatabotRequest build(java.util.Map<String, ?> map) throws Exception {
DatabotRequest self = new DatabotRequest();
return TeaModel.build(map, self);
}
public String getQuery() {
return query;
}
public DatabotRequest setQuery(String query) {
this.query = query;
return this;
}
public String getAccessId() {
return accessId;
}
public DatabotRequest setAccessId(String accessId) {
this.accessId = accessId;
return this;
}
}
客户端请求
package com.alibaba.iic.dbot.bfw.bizadapter.common;
import com.alibaba.fastjson.JSON;
import com.aliyun.databot20200330.Client;
import com.aliyun.tea.TeaModel;
import com.aliyun.tearpc.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
import java.util.HashMap;
import java.util.Map;
public class CloudClient {
private static String ACTION = "QueryDatabot";//固定字段
private static String PROTOCOL = "HTTPS";//固定字段
private static String METHOD = "POST";//固定字段
private static String AUTHTYPE = "AK";//固定字段
private static String VERSION = "2020-03-30";//固定字段
private static String ENDPOINT = "databot.cn-shanghai.aliyuncs.com";//固定字段
private static String REGIONID = "cn-shanghai";//固定字段
private static String SESSIONID = "1";//固定字段
private static String ACCESSKEYID = "LTAI4G4kj9NpA1Gtj44arZmo";//用户的acckeyId
private static String ACCESSKEYSECRET = "MtzY5wxXkM4ISM1C9ThAa9YN9dUdC4";//用户的acckeySecret
private static String QUERY = "新冠疫情确诊人数";//查询语句
private static String ACCESSID = "Cloud-68ba02e59a7aca903b4f80a0deb123c4-dataBotISV";//机器人uid
public static void main(String[] args) {
Config config = new Config();
config.setAccessKeyId(ACCESSKEYID);
config.setAccessKeySecret(ACCESSKEYSECRET);
config.setEndpoint(ENDPOINT);
config.setRegionId(REGIONID);
try {
Client client = new Client(config);
Map<String,Object> map = new HashMap<>();
DatabotRequest request = DatabotRequest.build(map);
request.setSessionId(SESSIONID);
request.setQuery(QUERY);
request.setAccessId(ACCESSID);
Map<String, ?> resultMap = client.doRequest(ACTION, PROTOCOL, METHOD, VERSION, AUTHTYPE, null, TeaModel.buildMap(request), new RuntimeOptions());
System.out.println(JSON.toJSONString(resultMap));
} catch (Exception e) {
e.printStackTrace();
}
}
}
响应(JSON格式):
{
"data":{
},
"type":"markdown",
"actions":[
],
"actionResult":{
"actions":[
],
"botToken":"20f07aaa5a1e7c6e268f4e25ac006278",
"chartOption":{
"data":[
[
{
"properties":{
"formatString":"#,###0",
"caption":"本店存量"
},
"raw":"本店存量",
"type":"COLUMN_HEADER",
"value":"本店存量"
}
],
[
{
"properties":{
"raw":338
},
"raw":338,
"type":"DATA_CELL",
"value":"338"
}
]
],
"option":{
"series":[
{
"param":{
},
"type":"table"
}
]
}
},
"chatUid":"0bc16d8016184739187045683d6e55",
"cubeResultType":"measure_detail",
"extraInfo":{
},
"lineType":"line_single",
"tenant":"tenant_bot_189",
"title":"数据列表",
"type":"CUBE",
"userInfoDto":{
"admin":false,
"bizDomainAdmin":false,
"edit":false,
"extra":{
"queryChannel":1
},
"id":"083603",
"imageUrl":"//work.alibaba-inc.com/photo/083603.80x80.jpg",
"name":"tenant_bot_189_083603",
"needAuth":false,
"tenant":"83603",
"tenantType":"tenant_bot_189",
"type":"BUC"
}
}
}
简报推送第三方接口规范
如上图,在简报的推送配置中,可以指定外部的服务接口。数据助理会调用该配置接口推送简报内容。接口规范如下:
1.目前只支持http(s)协议
即服务器地址为http服务地址,如http://www.xxx.com/databot
2.Sercret
即密钥,随机生成数,由客户自主生成。如随机生成16位密钥,“8a5kRwgoxAGvTsZy“。此密钥用于在客户服务端接受到推送数据后,校验参数中的签名信息
3.提交方式与参数
POST提交,参数列表如下
参数名称 |
说明 |
示例 |
title |
简报名称 |
每日数据简报 |
content |
简报内容 |
|
user |
推送人员 |
231451 |
corpId |
推送组织(阿里云主账户ID) |
324546345231 |
sign |
推送签名,以MD5加密的方式,把前四个参数加上秘钥组合一起进行MD5加密,如示例 |
MD5(title=简报名称&content=简报内容&user=人员Id&corpId=主账户Id&sign=秘钥) |
http(s)数据接入
参考“用户指南“中“企业本地数据接入“部分。其中包含了“Schema查询“,“维度查询“,“指标查询“三个接口。