开发手册

本文针对智能数据助理的开放接口,和接入过程中需要客户开发的本地服务接口进行说明

对话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 = "";//用户的acckeyId

    private static String ACCESSKEYSECRET = "";//用户的acckeySecret

    private static String QUERY = "新冠疫情确诊人数";//查询语句

    private static String ACCESSID = "";//机器人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"
        }
    }
}

简报推送第三方接口规范

截屏2020-12-10 03如上图,在简报的推送配置中,可以指定外部的服务接口。数据助理会调用该配置接口推送简报内容。接口规范如下:

1.目前只支持http(s)协议

即服务器地址为http服务地址,例如:http://127.0.0.1:8080/databot

2.Sercret

即密钥,随机生成数,由客户自主生成。如随机生成16位密钥,“8a5kRwgoxAGvTsZy“。此密钥用于在客户服务端接受到推送数据后,校验参数中的签名信息

3.提交方式与参数

POST提交,参数列表如下

参数名称

说明

示例

title

简报名称

每日数据简报

content

简报内容

# 2020-02-22 超级小蜜简报
## 一. 对话轮次概览
**对话轮次**: 1,234,567
## 二. 对话轮次TOPN分析
按照<fontcolor=#fa8c16>会员类型</font>进行topn分析:
1.<fontcolor=#909497>资深用户 : 1,000,840</font>
2.<fontcolor=#909497>超级会员 : 123,080</font>
3.<fontcolor=#909497>黑灰会员 : 123,043</font>
## 二. 对话轮次趋势!
[超级小蜜对话轮次趋势](https://databot-chart.oss-cn-zhangjiakou.aliyuncs.com/chart/demo.jpg)

user

推送人员

例如:12345

corpId

推送组织(阿里云主账户ID)

例如:12345

sign

推送签名,以MD5加密的方式,把前四个参数加上秘钥组合一起进行MD5加密,如示例

MD5(title=简报名称&content=简报内容&user=人员Id&corpId=主账户Id&sign=秘钥)

http(s)数据接入

参考“用户指南“中“企业本地数据接入“部分。其中包含了“Schema查询“,“维度查询“,“指标查询“三个接口。