docs(api): add python api description

app/service/time_series_detector/detect_service.py

@@ -120,7 +120,7 @@ class DetectService(object):
         return True
 
     def __check_param(self, data):
-        if ("viewName" not in data.keys()) or ("attrId" not in data.keys()) or ("attrName" not in data.keys()) or ("time" not in data.keys()) or ("dataC" not in data.keys()) or ("dataB" not in data.keys()) or ("dataA" not in data.keys()):
+        if ("viewName" not in data.keys()) or ("viewId" not in data.keys()) or ("attrId" not in data.keys()) or ("attrName" not in data.keys()) or ("time" not in data.keys()) or ("dataC" not in data.keys()) or ("dataB" not in data.keys()) or ("dataA" not in data.keys()):
             return CHECK_PARAM_FAILED, "missing parameter"
         return OP_SUCCESS, ""
 

app/sql/time_series_detector/anomaly.sql

@@ -4,16 +4,16 @@ SET FOREIGN_KEY_CHECKS=0;
 -- ----------------------------
 DROP TABLE IF EXISTS `anomaly`;
 CREATE TABLE `anomaly` (
-  `id` bigint(20) NOT NULL AUTO_INCREMENT,
-  `view_id` varchar(31) DEFAULT NULL,
-  `view_name` varchar(63) DEFAULT NULL,
-  `attr_id` varchar(31) DEFAULT NULL,
-  `attr_name` varchar(63) DEFAULT NULL,
-  `time` datetime DEFAULT NULL,
-  `data_c` text NOT NULL,
-  `data_b` text NOT NULL,
-  `data_a` text NOT NULL,
-  `mark_flag` int(1) NOT NULL DEFAULT '0',
+  `id` int(10) NOT NULL AUTO_INCREMENT,
+  `view_id` varchar(31) NOT NULL DEFAULT '' comment '指标集id',
+  `view_name` varchar(63) NOT NULL DEFAULT '' comment '指标集名',
+  `attr_id` varchar(31) NOT NULL DEFAULT '' comment '指标id',
+  `attr_name` varchar(63) NOT NULL DEFAULT '' comment '指标名',
+  `time` datetime DEFAULT NULL comment '数据时间',
+  `data_c` text,
+  `data_b` text,
+  `data_a` text,
+  `mark_flag` tinyint(1) NOT NULL DEFAULT 0 comment '0:没有打标、1:打标为正样本、2:打标为负样本',
   PRIMARY KEY (`id`)
 ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;
 

app/sql/time_series_detector/sample_dataset.sql

@@ -4,21 +4,21 @@ SET FOREIGN_KEY_CHECKS=0;
 -- ----------------------------
 DROP TABLE IF EXISTS `sample_dataset`;
 CREATE TABLE `sample_dataset` (
-  `id` bigint(10) NOT NULL AUTO_INCREMENT,
-  `update_time` timestamp NULL DEFAULT NULL,
-  `view_id` varchar(31) DEFAULT NULL,
-  `view_name` varchar(63) DEFAULT NULL,
-  `attr_name` varchar(63) DEFAULT NULL,
-  `attr_id` varchar(31) DEFAULT NULL,
-  `source` varchar(31) DEFAULT NULL,
-  `train_or_test` varchar(31) DEFAULT NULL,
-  `positive_or_negative` varchar(31) DEFAULT NULL,
-  `window` int(2) DEFAULT NULL,
-  `data_time` int(11) DEFAULT NULL,
+  `id` int(10) NOT NULL AUTO_INCREMENT,
+  `update_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP comment '样本更新时间',
+  `view_id` varchar(31) NOT NULL DEFAULT '' comment '指标集id',
+  `view_name` varchar(63) NOT NULL DEFAULT '' comment '指标名',
+  `attr_name` varchar(63) NOT NULL DEFAULT '' comment '指标名',
+  `attr_id` varchar(31) NOT NULL DEFAULT '' comment '指标id',
+  `source` varchar(31) NOT NULL DEFAULT '' comment '样本来源',
+  `train_or_test` varchar(10) NOT NULL DEFAULT '' comment 'test：测试样本、train:训练样本',
+  `positive_or_negative` varchar(20) NOT NULL DEFAULT '' comment 'positive:正样本、negative负样本',
+  `window` int(10) NOT NULL DEFAULT 0 comment '窗口值，目前支持180',
+  `data_time` int(10) DEFAULT NULL comment '样本时间',
   `data_c` text,
   `data_b` text,
   `data_a` text,
-  `anomaly_id` bigint(10) DEFAULT NULL,
+  `anomaly_id` int(10) DEFAULT NULL comment '标识从anomaly里插入的样本',
   PRIMARY KEY (`id`)
 ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;
 

app/sql/time_series_detector/train_task.sql

@@ -4,19 +4,18 @@ SET FOREIGN_KEY_CHECKS=0;
 -- ----------------------------
 DROP TABLE IF EXISTS `train_task`;
 CREATE TABLE `train_task` (
-  `id` int(11) NOT NULL AUTO_INCREMENT,
-  `task_id` char(255) DEFAULT NULL,
-  `sample_num` int(11) DEFAULT NULL,
-  `postive_sample_num` int(11) DEFAULT NULL,
-  `negative_sample_num` int(11) DEFAULT NULL,
-  `window` int(2) DEFAULT NULL,
-  `model_name` varchar(20) DEFAULT NULL,
-  `source` varchar(255) DEFAULT NULL,
-  `start_time` timestamp NULL DEFAULT NULL,
-  `end_time` timestamp NULL DEFAULT NULL,
-  `status` varchar(11) DEFAULT NULL,
-  PRIMARY KEY (`id`),
-  KEY `id` (`id`)
+  `id` int(10) NOT NULL AUTO_INCREMENT,
+  `task_id` varchar(20) NOT NULL DEFAULT '' comment '训练任务id',
+  `sample_num` int(10) NOT NULL DEFAULT 0 comment '训练总样本数',
+  `postive_sample_num` int(10) NOT NULL DEFAULT 0 comment '训练正样本数',
+  `negative_sample_num` int(10) NOT NULL DEFAULT 0 comment '训练负样本数',
+  `window` int(10) NOT NULL DEFAULT 0 comment '窗口值，目前支持180',
+  `model_name` varchar(20) NOT NULL DEFAULT '' comment '模型名',
+  `source` varchar(255) NOT NULL DEFAULT '' comment '样本来源',
+  `start_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP comment '训练任务开始时间',
+  `end_time` timestamp NULL DEFAULT NULL comment '训练任务结束时间',
+  `status` varchar(11) NOT NULL DEFAULT '' comment 'complete:任务完成、running:任务正在运行、failed：任务失败',
+  PRIMARY KEY (`id`)
 ) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8;
 
 -- ----------------------------

docs/api_userguide.md

@@ -14,7 +14,9 @@
 针对当前一个值的检测，需要依赖过去三段数据，数据选取规则参考示例图：
 ![data_info](images/data_info.png)
 
-### 1、量值检测
+### 1、HTTP接口
+
+#### 1、量值检测
 
 * API： POST /{ip}:{port}/PredictValue
 * 功能说明：根据参考数据检测最近一个数据点是否异常
@@ -73,7 +75,7 @@
 | ret | int | 检测结果是否异常。0:异常；1:正常 |
 | p | string | 概率值，值越小，判定为异常的置信度越高，目前p<0.15，判决为异常 |
 
-### 2、率值检测
+#### 2、率值检测
 
 * API： POST /{ip}:{port}/PredictRate
 * 功能说明：根据参考数据检测最近一个数据点是否异常
@@ -129,4 +131,98 @@
 | code | int | 返回码。0:成功；非0:失败 |
 | msg | string | 返回消息 |
 | ret | int | 检测结果是否异常。0:异常；1:正常 |
-| p | string | 概率值，值越小，判定为异常的置信度越高 |
+| p | string | 概率值，值越小，判定为异常的置信度越高 |
+
+### 2、Python API
+
+Metis工程目录下time_series_detector目录为时间序列异常检测学件库，可以在python下直接调用
+
+#### 1、量值检测
+* 调用方法： 
+
+```
+  # Python
+  from time_series_detector import detect
+  detect_obj = detect.Detect()
+  detect_obj.value_predict(data)
+```
+
+* 功能说明：根据参考数据检测最近一个数据点是否异常
+* 传入参数：python字典
+	
+```
+{
+    "taskId":"1530608070706",
+    "window":180,
+    "dataC":"9,10,152,...,255,...,16",
+    "dataB":"9,10,152,...,255,...,18",
+    "dataA":"9,10,152,...,458"
+}
+```
+
+* 传入参数说明：同上
+
+* 返回参数：
+```
+    code, {
+        "ret":0,
+        "p":"0.05",
+    }
+
+```
+
+* 返回参数说明：
+
+| 名称  | 类型  | 说明 |
+|---|---|---|
+| code | int | 返回码。0:成功；非0:失败 |
+| ret | int | 检测结果是否异常。0:异常；1:正常 |
+| p | string | 概率值，值越小，判定为异常的置信度越高，目前p<0.15，判决为异常 |
+
+* 调用案例：
+
+![data_info](images/python_api_value_predict.png)
+
+#### 2、率值检测
+* 调用方法： 
+
+```
+  # Python
+  from time_series_detector import detect
+  detect_obj = detect.Detect()
+  detect_obj.rate_predict(data)
+```
+
+* 功能说明：根据参考数据检测最近一个数据点是否异常
+* 传入参数：python字典
+	
+```
+{
+    "dataC":"9,10,152,...,255,...,16",
+    "dataB":"9,10,152,...,255,...,18",
+    "dataA":"9,10,152,...,458"
+}
+```
+
+* 传入参数说明：同上
+
+* 返回参数：
+```
+    code, {
+        "ret":0,
+        "p":"0",
+    }
+
+```
+
+* 返回参数说明：
+
+| 名称  | 类型  | 说明 |
+|---|---|---|
+| code | int | 返回码。0:成功；非0:失败 |
+| ret | int | 检测结果是否异常。0:异常；1:正常 |
+| p | string | 概率值，值越小，判定为异常的置信度越高，目前p<0.15，判决为异常 |
+
+* 调用案例：
+
+![data_info](images/python_api_rate_predict.png)

time_series_detector/detect.py

@@ -33,7 +33,7 @@ class Detect(object):
         return True
 
     def __check_param(self, data):
-        if ("viewName" not in data.keys()) or ("attrId" not in data.keys()) or ("attrName" not in data.keys()) or ("time" not in data.keys()) or ("dataC" not in data.keys()) or ("dataB" not in data.keys()) or ("dataA" not in data.keys()):
+        if ("dataC" not in data.keys()) or ("dataB" not in data.keys()) or ("dataA" not in data.keys()):
             return TSD_CHECK_PARAM_FAILED, "missing parameter"
         if not data['dataA']:
             return TSD_CHECK_PARAM_FAILED, "dataA can not be empty"