其他分享
首页 > 其他分享> > DataSong大数据智能管理平台 用户手册-开发部分

DataSong大数据智能管理平台 用户手册-开发部分

作者：互联网

3 接口使用说明

3.1 数据定义接口（DDL）

3.1.1 创建数据库

3.1.1.1 创建数据库

服务接口http://127.0.0.1:8080/datasong/settingService/{dbName}
操作符PUT
参数说明dbName逻辑数据库名
返回值CreateDBResponse返回操作响应结构体，包含创建数据库操作执行结果的状态码
说明创建一个名称为dbName的数据库，这里数据库是一个逻辑概念，可以对应sql数据库中的一个物理库也可以对应nosql中一个逻辑数据库。

3.1.1.2 示例代码

引入DataSongClient驱动包，实现如下：

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
boolean result = dataSongClient.createDB(dbName);
System.out.println(result);

注意：dbName只能包含字母或数字且不能以数字开头

3.1.2 创建数据表

3.1.2.1 接口说明

服务接口http://127.0.0.1:8080/datasong/settingService/{dbName}/{tableName}
操作符PUT
参数说明dbName逻辑数据库名
tablaName逻辑表名
返回值CreateTableResponse返回操作响应结构体，包含创建数据表操作执行结果的状态码
说明在数据库dbName中创建一个sql数据表或者nosql数据表。

3.1.2.2 示例代码

引入DataSongClient驱动包，实现如下：

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);

dataSongClient.setDatabaseName(dbName);//注意需要指定数据库

boolean result = dataSongClient.createTable(Student.class);
System.out.println(result);

注意1：首次使用dataSongClient实例，需要制定操作的数据库，指定一次即可。
注意2：表的创建可以直接通过class自动完成，Student定义如下:

@DSStoreType(StoreType.Fulltext)//指定表的存储类型，如fulltext、sql等
@DSTableName(value = "student")//指定数据库名字，可不指定，默认会自动用类名
public class Student extends DataSongBean {
    @DSFulltextIndexType(FulltextIndexType.None)//设置仅存储，不索引，即不可作为条件检索，节约存储空间
    private String classid;

    @DSFulltextIndexType(FulltextIndexType.None)
    private Date createtime;

@DSFulltextIndexType(FulltextIndexType.Whitespace)//设置空格分词
    private String interest;

    @DSFulltextIndexType (FulltextIndexType.IK)  //设置中文分词
    private String name;

    private int age;//不设置，默认可检索

    @DSFulltextIndexType(FulltextIndexType.None)
    private Date birth;
}

1）DataSongBean中内置了内部唯一标识_id，即DataSong所有表都会有一个内置的唯一id。
2）DataSong的所有注解都是“DS”开头，分为类级别和属性级别，如下图所示：
在这里插入图片描述

不同的存储类型（DSStoreType）应该对应不同的索引类型（DSFulltextIndexType、DSGraphIndexType、DSMemIndexType、DSNoSqlIndexType、DSSqlIndexType）。其他的属性级别注解不用区分存储类型。

3.1.3 删除数据表

3.1.3.1 接口说明

服务接口http://127.0.0.1:8080/datasong/settingService/{dbName}/{tableName}
操作符DELETE
参数说明dbName逻辑数据库名
tablaName逻辑表名
返回值DeleteTableResponse返回操作响应结构体，包含删除数据表操作执行结果的状态码
说明删除一个指定的数据表。

3.1.3.2 示例代码

引入DataSongClient驱动包，实现如下：

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);

dataSongClient.setDatabaseName(dbName);//注意需要指定数据库

boolean result = dataSongClient.deleteTable(Student.class);
System.out.println(result);

注意：此删除为物理删除，一经删除，不能恢复。

3.1.4 删除数据库

3.1.4.1 接口说明

服务接口http://127.0.0.1:8080/datasong/settingService/{dbName}
操作符DELETE
参数说明dbName逻辑数据库名
返回值DeleteDBResponse返回操作响应结构体，包含删除数据库操作执行结果的状态码
说明删除一个指定的数据库，同时删除数据库中所包含的数据表。

3.1.4.2 示例代码

引入DataSongClient驱动包，实现如下：

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);

boolean result = dataSongClient.deleteDB(dbName);

System.out.println(result);

注意：此删除为物理删除，一经删除，不能恢复。

3.2 数据操作接口（DML）

3.2.1 数据查询接口

3.2.1.1 接口说明

服务接口http://127.0.0.1:8080/datasong/data/v2/{dbName}/{tableName}
操作符POST
参数说明dbName逻辑数据库名
tablaName逻辑表名
requestbody {“search”: {“NAME”: “bool”,“must”: [{“column”: “satelliteTime”,“NAME”: “range”,“from”: “from_time”,“to”:“to_time”}, {“column”: “channel”,“NAME”: “term”,“value”: channel_id}]},“sort”: {“satelliteTime”: “ASC”},“columns”: [“satelliteTime”, value_id],“size”: 10000,“statistic”: {“NAME”: “metric”, “column”: value_id}}
返回值DeleteTableResponse {“status”:200,“info”:“search data ok”,“tookInMillis”: 30,“total”: 425327,“items”: “[{“satelliteTime”:“2019-01-01 00:08:28.634”,”_id":“2_1_20190101000828”,“M001CG044”:0.0,“status”:0},{“satelliteTime”:“2019-01-01 00:16:31.635”,"_id":“2_1_20190101001631”,“M001CG044”:3.0,“status”:0},…],“statistic”: [{“key”: “metric”, “value”: {“sum_of_squares”: 1497218.0, “min”: 0.0, “avg”: 1.508034994251482, “max”: 3.0, “variance”: 1.2459878879242219, “count”: 425327, “std_deviation”: 1.116238275604372, “sum”: 641408.0}, “children”: None}]}
说明参数说明中：dbName与tablaName为可变参数，对应于具体的型号名称以及遥测包名称；requestbody为JSON格式的查询请求参数对象具体内容，其中标红对象为可选查询内容。其中channel_id字段描述的是遥测量来源的通道名称；value_id：代表所要查询的遥测量的具体名称；statistic:对象描述是否进行基本的数据统计分析，其中value_id字段描述所统计分析的遥测量具体名称。返回值中：Items：描述的是查询得到的返回结果，_id为对应的数据id；statistic：描述的查询遥测量结果的的统计字段信息。

内部查询体系如下：
在这里插入图片描述

3.2.1.2 示例代码

（1） 查询条件构建
精确匹配条件:

//写法1.1
TermSearchCondition term = new TermSearchCondition();
        term.setValue(new int[]{ 6, 7});
        term.setColumn("age");



//写法1.2
TermSearchCondition ageTermSearchCondition  = ConditionBuilder.termCondition("age",  7);




//写法2.1
TermSearchCondition interestTermSearchCondition  = ConditionBuilder.termCondition("interest", new String[]{"跳高","篮球"});



//写法2.2
TermSearchCondition interestTermSearchCondition  = ConditionBuilder.termCondition("interest", "跳高 篮球");//对查询条件也会自动分词

范围查询条件

//写法1
RangeSearchCondition rangeSearchCondition = new RangeSearchCondition();
      rangeSearchCondition.setFrom("2021-02-07 18:25:04");
//    rangeSearchCondition.setTo("2021-02-07 18:25:05.6");//可以只设置一边的限制
      rangeSearchCondition.setColumn("createtime");


     
//写法2
RangeSearchCondition   createtimeRangeSearchCondition = ConditionBuilder.rangeCondition("createtime","2021-03-06 8:25", "2021-03-06 18:25:05.6");

Bool查询条件

BoolSearchCondition boolSearchCondition = new BoolSearchCondition();
      boolSearchCondition.must(rangeSearchCondition);//.must(ageTermSearchCondition).must(createtimeRangeSearchCondition);

（2） 统计条件构建
说明：统计满足查询条件的数据集中数据的分布情况。基础的单值统计不能多级级联，分组统计支持多级级联，可以类比SQL查询。统计结果是以table的形式返回，同样可以类比SQL查询。所有统计需要设置一个别名Alias，同一个查询中的多个条件，别名不能重复。

均值统计

//写法1
AvgStatisticCondition avgStatisticCondition = new AvgStatisticCondition();
avgStatisticCondition.setAlias("avg");
avgStatisticCondition.setColumn("age");
//写法2
AvgStatisticCondition c1 = ConditionBuilder.avgStatisticCondition("age", "平均值统计");

求和统计

//写法1
SumStatisticCondition sumStatisticCondition = new SumStatisticCondition();
sumStatisticCondition.setAlias("sum");
sumStatisticCondition.setColumn("age");

//写法2
SumStatisticCondition c2 = ConditionBuilder.sumStatisticCondition("age", "求和统计");

计数统计

CountStatisticCondition c4 = ConditionBuilder.countStatisticCondition("age", "count统计");

按日期区间分组统计——支持设置下一级

//对createtime列，按天分组统计
DateRangeStatisticCondition dateRangeStatisticCondition = ConditionBuilder.dateRangeStatisticCondition("createtime", "time_statistic", DateInterval.Day);

//日期区间可以设置下一级统计
dateRangeStatisticCondition.addChild(c4);
dateRangeStatisticCondition.addChild(c5);

按类型分组统计——支持设置下一级

//对interest列，分组统计
TermStatisticCondition termStatisticCondition = ConditionBuilder.termStatisticCondition

      termStatisticCondition.setColumn("interest");
      termStatisticCondition.setAlias("alias");
      termStatisticCondition.addChild(c4);
      termStatisticCondition.addChild(sumStatisticCondition);

（3） 查询

SearchDataRequest searchDataRequest = new SearchDataRequest();

//设置查询条件
searchDataRequest.setSearch(boolSearchCondition);
//添加统计条件，允许并行设置多个统计条件，索引采用add方式
      searchDataRequest.addStatistic(c3);

//设置分页
      searchDataRequest.setStart(0);
      searchDataRequest.size(5);

      //设置排序
      searchDataRequest.sort("birth", SortOrder.ASC);
      searchDataRequest.sort("createtime", SortOrder.DESC);

      //设置需要取的列
searchDataRequest.setColumns(new String[] {"interest"});//不设置默认返回所有列

      DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip, port);
      dataSongClient.setDatabaseName(dbName);

        DataSongSearchResult response = dataSongClient.getDataService().searchData(Student.class ,searchDataRequest);//设置实体类，会自动进行翻转

//命中总条数
      System.out.println("符合条件的总条数："+response.getTotal());
      
//解析查询结果（如果有）
for(int i = 0 ; i <response.getItems().size(); i++) {
         System.out.println(DataSongJsonUtils.toJson(response.getItems().get(i)));
      }

//解析统计结果（如果有）
//返回结构封装成了与jdbc协议中ResultSet一样的结构（即表格结构）
for(int index = 0 ;  index < response.getStatistics().size() ; index++){
   DataSongResultSet resultSet = (DataSongResultSet) response.getStatistics().get(index);

//表头解析，即用户自定义别名
   ResultSetMetaData rsmd = resultSet.getMetaData();
   for (int i = 1; i <= rsmd.getColumnCount(); i++) {
      System.out.print(rsmd.getColumnName(i)+"\t\t");
   }
   System.out.println();

//结构解析
   while(resultSet.next()){
      for(int i=1;i<=rsmd.getColumnCount();i++){
         System.out.print(resultSet.getObject(i));
         System.out.print("\t\t");
      }

      System.out.println();
   }
}

3.2.1 数据插入与修改

3.2.1.1 接口说明

服务接口http://127.0.0.1:8080/datasong/dataService/{dbName}/{tableName}
操作符PUT
参数说明dbName逻辑数据库名
tablaName逻辑表名
requestbody数据实体
返回值PutDataResponse返回操作响应结构体，包含插入或修改操作执行结果的状态码。
说明DataSong数据存储中间件为所有数据记录分配了一个全局唯一的id号。如果用户提交的数据包含id则会自动覆盖掉系统中id号相同的数据，否则，系统会自动分配一个唯一的id 号，并将id号返回给用户。

3.2.1.2 示例代码

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
      dataSongClient.setDatabaseName("test");

      StudentBean studentBean = new StudentBean();
//    studentBean.set_id("1"); //非必须设置
      studentBean.setAge(2);
      studentBean.setClassid("sdf");
      studentBean.setCreatetime(new Date());
      studentBean.setName("sdfssdfdf");
        studentBean.setInterest("足球 篮球 乒乓球");

dataSongClient.getDataService().saveData("StudentBean",studentBean); //对于相同_id的数据，会直接覆盖。所以，修改数据时需要把不需要修改的字段也带上，遵循rest规范。

//批量插入
List<StudentBean> datas = new ArrayList<>();
dataSongClient.getDataService().batchSaveData( datas);

说明：插入时表名不是必须显示的指定，可以根据数据类型自动解析对应的表名。

3.2.2 数据删除

3.2.2.1 接口说明

服务接口http://127.0.0.1:8080/datasong/dataService/{dbName}/{tableName}/{id}
操作符DELETE
参数说明dbName逻辑数据库名
tablaName逻辑表名
id数据主键，如果多条逗号分隔即可
返回值DeleteDataResponse返回操作响应结构体，包含删除操作执行结果的状态码
说明数据删除是通过数据库名、数据表名以及数据id唯一的指定一条数据进行删除的。

3.2.2.2 示例代码

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

boolean result = dataSongClient.getDataService().deleteData(StudentBean.class, "11"); //表名可以是类，可以是字符串

System.out.println(result);



//批量删除写法如下：
List<String> ids = Arrays.asList(new String[]{"11","12","13"});
long result = dataSongClient.getDataService().batchDeleteData(StudentBean.class, ids); //库名可以是类，可以是字符串

3.2.3 数据检索

老版接口，功能更全，使用起来比较繁琐，不推荐使用。

服务接口http://127.0.0.1:8080/datasong/dataService/{dbName}/{tableName}
操作符POST
参数说明dbName逻辑数据库名
tablaName逻辑表名
requestbody查询请求
返回值SearchDataResponse返回操作响应结构体，包含查询操作执行结果的状态码和数据
说明数据检索包含数据的基本查询以及数据的统计查询，通过如图4-2所示的查询条件实体类构造不同的查询Json串。

3.2.4数据获取

3.2.4.1 接口说明

服务接口http://127.0.0.1:8080/datasong/dataService/{dbName}/{tableName}/{id}
操作符GET
参数说明dbName逻辑数据库名
tablaName逻辑表名
id数据主键，如果多条逗号分隔即可
返回值GetDataResponse返回操作响应结构体，包含查询操作执行结果的状态码和数据
说明通过数据库、数据表、id唯一指定一条数据并按照既定格式返回。如果数据不存在，则通过状态码和状态字段提醒用户。

3.2.4.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");//实质库名

StudentBean result = dataSongClient.getDataService().getData(StudentBean.class, "1"); //表名可以是类，可以是字符串。如果是字符串返回的是json格式

System.out.println( DataSongJsonUtils.toJson(result));


//如果是批量获取，写法如下
List<String> ids = Arrays.asList(new String[]{"1","2","3"});
List<StudentBean> result = dataSongClient.getDataService().batchGetData(StudentBean.class, ids); //表名可以是类，可以是字符串

3.2.5 数据清空

3.2.5.1 接口说明

服务接口http://127.0.0.1:8080/datasong/dataService/{dbName}/{tableName}
操作符DELTE
参数说明dbName逻辑数据库名
tablaName逻辑表名
返回值ClearDataResponse返回操作响应结构体，包含清空操作执行结果的状态码
说明通过数据库、数据表唯一指定一个数据表（sql数据表或Nosql数据表）并进行数据清空操作。

3.2.5.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

boolean result = dataSongClient.getDataService().clearData(StudentBean.class); //表名可以是类，可以是字符串

System.out.println( result);

3.3 文件操作接口

3.3.1 文件本地上传

3.3.1.1 接口说明

服务接口http://127.0.0.1:15680/datasong/fileService/{dbName}/{tableName}
操作符PUT
参数说明dbName逻辑数据库名
tablaName逻辑表名
requestbody文件描述
返回值PutFileResponse返回操作响应结构体，包含文件上传操作执行结果的状态码
说明上传本地文件，文件作为一条数据逻辑上属于一个指定的数据表。

3.3.1.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

String id = dataSongClient.getFileService().uploadFile(StudentBean.class,"D:\\新建文本文档.txt"); //对于相同_id的数据，会直接覆盖

System.out.println( id);

3.3.2 文件删除

3.3.2.1 接口说明

服务接口http://127.0.0.1: 15680/datasong/fileService/{dbName}/{tableName}/{id}
操作符DELETE
参数说明dbName逻辑数据库名
tablaName逻辑表名
id文件主键
返回值DeleteFileResponse返回操作响应结构体，包含文件删除操作执行结果的状态码
说明根据数据库、数据表、数据文件的id号唯一确定一个文件并删除。

3.3.2.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");
boolean id = dataSongClient.getFileService().deleteFile(StudentBean.class,"dddddddd");
System.out.println( id);

3.3.3 文件下载

3.3.3.1 接口说明

服务接口http://127.0.0.1: 15680/datasong/fileService/{dbName}/{tableName}/{id}
操作符GET
参数说明dbName逻辑数据库名
tablaName逻辑表名
id文件主键
返回值GetFileResponse返回操作响应结构体，包含文件下载操作执行结果的状态码
说明根据配置文件将文件下载到本地指定的缓存目录下。

3.3.3.1 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

boolean id = dataSongClient.getFileService().downloadFile(StudentBean.class,"dddddddd","d://ddd.txt");

System.out.println( id);

3.3.4 文件流式上传

3.3.4.1 接口说明

服务接口http://127.0.0.1: 15680/datasong/fileService/stream/{dbName}/{tableName}
操作符POST
参数说明dbName逻辑数据库名
tablaName逻辑表名
requestbody文件流
返回值PutFileResponse返回操作响应结构体，包含文件流式上传操作执行结果的状态码
说明

3.3.4.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

FileInputStream inputStream = new FileInputStream(new File("D:\\新建文本文档.txt"));//流也可以通过浏览器回传的流获取

String id = dataSongClient.getFileService().uploadFile(StudentBean.class,"新建文本文档.txt",inputStream); //对于相同_id的数据，会直接覆盖

System.out.println( id);

3.3.5 文件流式下载

3.3.5.1 接口说明

服务接口http://127.0.0.1: 15680/datasong/fileService/stream/{dbName}/{tableName}/{id}
操作符GET
参数说明dbName逻辑数据库名
tablaName逻辑表名
id文件id
返回值Response文件流
说明根据用户请求找到指定文件，并以流式方式返回，支持浏览器直接解析。

3.3.5.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

InputStream inputStream = dataSongClient.getFileService().downloadFileStream(StudentBean.class,"dddddddd");

System.out.println( inputStream);

3.3.6 文件预览

3.3.6.1 接口说明

服务接口http://127.0.0.1:15680/datasong/fileService/preview/{dbName}/{tableName}/{id}
操作符GET
参数说明dbName逻辑数据库名
tablaName逻辑表名
id文件id
返回值Response文件流
说明根据用户请求找到指定文件预览，并以流式方式返回，支持浏览器直接解析。

3.3.6.2 代码示例

DataSongClient dataSongClient = DataSongHttpClient.getInstance(ip,port);
dataSongClient.setDatabaseName("test");

boolean result = dataSongClient.getFileService().previewFile(StudentBean.class,"dddddddd", servletResponse);

System.out.println( result);

标签：dataSongClient,数据库,接口,dbName,说明,智能,DataSong,用户手册,id
来源： https://blog.csdn.net/wenyichuan/article/details/118961401