故障管理平台开放能力.docx
《故障管理平台开放能力.docx》由会员分享，可在线阅读，更多相关《故障管理平台开放能力.docx（24页珍藏版）》请在冰豆网上搜索。
故障管理平台开放能力
故障管理平台开放能力
1.总体概述
故障管理平台对外能力开放包括：
告警订阅能力，批量告警输出能力，告警实时查询接口能力，告警统计接口能力。
2.实时告警订阅能力
2.1.能力描述
告警订阅能力用于订阅方设定需要告警订阅的规则，并连接故障管理系统接口获取实时告警消息，以及通过告警同步进行告警校准。
包括一个配置功能以及三个接口：
1.告警订阅配置功能：
以HTTP方式，网管提供URL页面,用于配置告警过滤条件及订阅方IP+端口号等；配置条件项包括但不限于以下内容：
网元类型、设备厂家、告警级别、告警标题、网管告警ID等。
2.告警发送接口：
以SOCKET方式用于向订阅方进行实时告警消息发送。
3.告警同步接口：
以SOCKET或者文件方式用于向订阅方进行非实时告警同步。
4.心跳机制：
在告警实时发送接口中，按照固定周期发送心跳消息，用于双方进行连接通道可用性检测。
2.1.1.告警订阅配置功能
1、用户为故障管理系统管理员，系统管理员负责对需要订阅的信息进行审核和收集，审核确认后连接故障管理系统，打开故障管理系统登陆页面。
2、用户输入账号密码后登陆故障管理系统。
3、登陆成功后，进入告警订阅规则配置页面，进行规则配置，配置完成后提交。
4、故障管理系统保存告警发送规则，并下发至告警发送模块。
新建或修改规则，都不应对已建立连接的告警发送产生影响。
针对只修改告警过滤条件的情况，告警发送模块过滤条件的生效时间不大于10分钟。
2.1.2.实时告警发送接口
1、告警数据消费者作为socket客户端，主动建立与故障管理系统的连接。
2、告警数据消费者发送登录请求，登录请求信息包括用户名、鉴权码。
告警数据消费者发给故障管理系统的登录请求消息
消息名：
reqLoginAlarm
参数：
1）user：
登录用户名，用户名中不得含有指定特殊字符如：
分号“;”等。
2）key：
鉴权码，鉴权码中不得含有指定特殊字符如：
分号“;”等。
消息样例：
reqLoginAlarm;user=yiy;key=qw#$@;
故障管理系统发给告警数据消费者的登录请求的响应消息
消息名：
ackLoginAlarm
参数：
1）result：
登录结果。
取值succ表示登录成功，fail表示登录失败。
2）resDesc：
登录失败原因，长度小于32个字符。
消息样例：
ackLoginAlarm;result=fail;resDesc=username-error；
3、故障管理系统对用户名和授权码进行认证，接受或拒绝登录请求。
故障管理系统检测到告警数据消费者连续三次登录失败后或者超过60s没有通过鉴权，主动断开与告警数据消费者的连接。
如检测到该用户名已有实时告警发送的连接建立，则拒绝登陆。
4、故障管理系统根据订阅配置条件对实时告警进行过滤，并发送从鉴权成功时刻开始的符合条件的实时告警。
5、当告警数据消费者发现实时告警消息序号不连续时（漏告警）且差值不大于1000时，可向故障管理系统发起1次消息方式告警同步请求（即每次缺漏的告警，告警数据消费者只能发起1次消息同步请求，如5分钟内发起的次数大于5次，则进行自动通知需进行人工干预。
），并告知故障管理系统同步告警消息的起始序号（如果同步请求未成功，告警数据消费者下次请求时至少比前次请求的告警消息起始序号+1）。
实时告警消息序号差值超过1000时，采用文件方式同步缺失告警。
告警数据消费者发现缺失告警时，发给故障管理系统的消息方式同步告警请求消息
消息名：
reqSyncAlarmMsg
参数：
1）reqID，操作序号，用于区分同一连接的多次请求。
2）alarmSeq，同步告警的起始告警消息序号。
丢失多条告警时，为最小告警消息序列号。
同一个起始告警消息序号的消息方式同步请求告警订阅方只能发送一次。
消息样例：
reqSyncAlarmMsg;reqID=33;alarmSeq=10
6、故障管理系统响应请求，返回确认信息。
故障管理系统发给告警数据消费者的消息方式同步告警请求的响应消息
消息名：
ackSyncAlarmMsg
参数：
1）reqID，操作序号，取值为请求消息的reqID。
2）result：
响应结果。
取值succ表示请求成功，fail为请求失败。
3）resDesc：
失败原因，长度小于32个字符，不允许带分号“;”。
消息样例：
ackSyncAlarmMsg;reqId=33;result=succ;resDesc=null
7、故障管理系统暂停发送实时告警，在告警消息发送缓存中查询告警数据消费者提供的同步告警消息起始序号的告警，然后补发从该告警消息序号开始的告警消息（方式和格式同4），含告警产生消息和告警清除消息，之后继续上报实时告警消息。
当故障管理系统没有找到该起始序号的告警数据（超出缓存范围）时，忽略该同步请求，从暂停序号之后的最新告警开始实时告警上报。
8、告警数据消费者每隔60秒发送一次心跳信息给故障管理系统，进行连接可用性确认。
如果在180秒内故障管理系统没有接收到告警数据消费者的任何信息时，故障管理系统主动断开socket连接。
9、故障管理系统收到告警数据消费者的心跳后，响应返回确认信息。
如果在180秒内告警数据消费者没有接收到故障管理系统的任何信息，告警数据消费者主动断开socket连接，然后尝试重新连接。
10、告警数据消费者告警数据接口程序终止前，向故障管理系统发起关闭socket连接的通知。
故障管理系统收到通知后停止发送告警，断开连接。
告警数据消费者判断该关闭通知发送成功后，断开和故障管理系统的连接。
告警数据消费者发给故障管理系统的关闭连接通知消息
消息样例：
closeConnAlarm
2.1.3.告警同步接口
1、告警数据消费者作为客户端，主动建立与故障管理系统的连接。
2、告警数据消费者申请告警同步请求，请求信息包括登录请求信息（包括用户名、授权码）以及故障管理系统同步告警范围。
3、故障管理系统响应请求，返回确认信息。
4、故障管理系统基于请求条件，生成告警数据文件，发送文件通知消息给告警数据消费者。
5、告警数据消费者从故障管理系统侧获取数据文件。
6、告警数据消费者断开和故障管理系统的连接。
2.1.4.心跳接口
心跳消息用于连接状态检查，处于告警正常发送的过程中，定时发送。
1、告警数据消费者每隔60秒发送一次心跳信息给故障管理系统，进行连接可用性确认。
如果在180秒内故障管理系统没有接收到告警数据消费者的任何信息时，故障管理系统主动断开socket连接。
2、故障管理系统收到告警数据消费者的心跳后，响应返回确认信息。
如果在180秒内告警数据消费者没有接收到故障管理系统的任何信息，告警数据消费者主动断开socket连接，然后尝试重新连接。
2.2.使用说明
告警订阅能力封装为一系列的接口，用户在获得权限和认证的前提下可以自行调用。
通过“告警订阅配置功能”可以订阅需要的告警发送规则，配置完成后通过“告警发送接口”获取实时告警消息，同时用“心跳接口”检查连接状态，以及通过“告警同步接口”进行告警校准。
2.3.服务地址（可选）
无
2.4.实时告警订阅服务接口
2.4.1.告警订阅配置功能服务
2.4.1.1.接口/服务描述（包括使用场景）
用户在获得权限和认证的前提下，通过告警转发配置界面，订阅方在该界面输入订阅系统的系统名称、简称、系统厂家、联系人、联系电话、联系邮箱等相关维护性信息，同时需要输入订阅方的机器IP、端口号和告警的过滤条件。
过滤条件项包括但不限于以下内容：
网元类型、设备厂家、告警级别、告警标题、网管告警ID。
2.4.1.2.接口形式
HTTPURL页面
2.4.1.3.接口参数
输入参数：
参数名称
类型
是否必选
默认值
描述
系统名称
String（100）
是
无
订阅方中文系统名称
系统简称
String（100）
是
无
订阅方英文简写
系统厂家
String（100）
是
无
订阅方系统厂家，用于工程维护
联系人
String（100）
是
无
订阅方联系人，用于工程维护
联系人电话
String（20）
是
无
订阅方联系人电话，用于工程维护
联系人邮箱
String（50）
是
无
订阅方联系人邮箱，用于工程维护
IP地址
String（15）
是
无
告警发送的IP地址
端口
Int（5）
是
无
告警发送的端口号
登陆用户名
String（15）
是
无
用于告警消费者连接告警发送模块时登陆所使用的用户名
鉴权码
String（15）
是
无
用于告警消费者连接告警发送模块时登陆所使用的鉴权码
过滤条件
String（300）
是
无
页面配置过滤条件包括但不限于：
网元类型、设备厂家、告警级别、告警标题、网管告警ID
输出参数：
无
2.4.1.4.性能要求
实时性：
页面响应时长不大于30秒
并发数：
大于等于10
吞吐量：
无
2.4.2.告警发送接口服务
2.4.2.1.接口/服务描述（包括使用场景）
用于向订阅方进行实时告警消息发送。
2.4.2.2.接口形式
Socket，故障管理系统为server端，告警数据消费者为client端。
2.4.2.3.接口参数
输入参数：
无
输出参数：
实时告警（系统根据告警订阅配置功能中的过滤条件和需要发送的服务端IP地址端口信息）
告警数据字段定义参见“5.告警字段说明附录”。
采用json格式进行组织，消息体样例：
{
"alarmSeq":
"10",
"alarmStatus":
"1",
"alarmId":
"410969",
"neUID":
"1301HWWX1ENB2A2367",
"neName":
"深圳同发路D-HLH",
……
"alarmCause":
"数据通道配置失败",
"addInfo":
"",
}
2.4.2.4.性能要求
时延：
不大于1分钟
并发数：
支持的连接数不小于10
吞吐量：
不少于200条/秒
2.4.3.告警同步接口服务
2.4.3.1.接口/服务描述（包括使用场景）
用于向订阅方进行非实时告警同步，基于故障管理系统告警流水日志生成数据文件，包括告警产生消息和告警清除消息。
主要用于告警数据消费者故障或升级、故障管理系统故障或升级、实时告警流水漏告警条数大于1000等情况，小于1000条的情况下参见2.1.2实时告警发送接口和2.4.2章节接口的形式。
2.4.3.2.接口形式
基于HTTP协议的（RESTFUL+JSON）+FTP，故障管理系统为接口服务提供方。
2.4.3.3.接口参数
输入参数：
参数名称
类型
是否必选
默认值
描述
filterConds
过滤条件
String（300）
是
无
告警的过滤条件为需要同步的起始告警消息序号或者告警的开始时间和结束时间
userName
用户名
String（30）
是
无
用于链接验证
authCode
授权码
String（30）
是
无
用于链接验证
startTime/endTime：
所取告警的开始时间和结束时间。
若startTime或endTime为空，表示该条件不生效（即：
若startTime为空，则从当前告警中最早的开始；若endTime为空，则取到当前最新的告警截止）。
告警的开始/结束时间取值的约定取故障管理系统告警发现的时间。
alarmSeq，同步告警的起始告警消息序号，在一次请求中给定alarmSeq和startTime/endTime是互斥的，同一条请求中只能出现其中之一。
即一次文件流水方式同步，按起始告警消息序号同步，或者按告警流水记录时间同步。
按时间请求接口报文格式
{
"opDetail":
{
"filterConds":
{
"startTime":
"2016-10-2000:
00:
00",
"endTime":
"2016-10-2012:
00:
00",
},
"userName":
"ailk",
"authCode":
"xxxxx"
}
}
按序列号请求接口报文格式
{
"opDetail":
{
"filterConds":
{
"alarmSeq":
"2354346456"
},
"userName":
"ailk",
"authCode":
"xxxxx"
}
}
输出参数：
参数名称
类型
是否必选
默认值
描述
resultCode
返回结果
Int
（2）
是
无
1为FTP文件准备成功，0为失败
resultDescr
返回结果描述
String（300）
是
无
成功为空，失败情况下描述失败原因
{
"opDetail":
{
"resultCode":
0,
"resultDescr":
"接口请求失败，原因为：
xxxxxxx"
}
}
2.4.3.4.性能要求
实时性：
无
并发数：
大于等于10
吞吐量：
无
2.4.4.心跳接口服务
2.4.4.1.接口/服务描述（包括使用场景）
在告警实时发送接口中，用于消费方进行连接通道可用性检测。
告警数据消费者每隔60秒发送心跳消息给故障管理系统，故障管理系统实时做出心跳响应回复。
2.4.4.2.接口形式
Socket，与发送告警接口建立的连接为同一个连接
2.4.4.3.接口参数
输入参数：
心跳消息，以“reqHeartBeat;”做为一条心跳消息。
输出参数：
心跳响应消息，以“ackHeartBeat;”作为心跳响应消息。
参数：
reqID，操作序号，用于区分同一连接的多次请求。
消息样例：
reqHeartBeat;ReqId=33
输出参数：
心跳响应消息，以“ackHeartBeat;”作为心跳响应消息。
参数：
reqID，操作序号，用于区分同一连接的多次请求。
消息样例：
ackHeartBeat;ReqId=33
2.4.4.4.性能要求
实时性：
时间间隔1次/60秒
并发数：
同告警发送接口要求
吞吐量：
无
3.批量告警输出能力
3.1.批量告警输出能力接口服务
3.1.1.批量告警输出接口服务
3.1.1.1.接口/服务描述（包括使用场景）
向分析类应用共享海量告警数据。
用于按需求方的规则，通过文件方式批量同步海量告警。
用于将符合条件的告警信息输出给第三方系统。
配置条件项包括但不限于以下内容：
网元类型、设备厂家、告警级别、告警标题、网管告警ID、告警发生时间和告警结束时间；
3.1.1.2.接口形式
ftp或者Sftp+文件接口
3.1.1.3.接口参数
输入参数：
提前约定
参数名称
类型
是否必选
默认值
描述
FTP服务地址
String（15）
是
无
告警文件上传的IP地址
FTP服务端口
Int（5）
是
无
告警文件上传的端口号
FTP上传目录
String（100）
是
无
告警文件上传的目录
过滤条件
String（300）
是
无
告警文件产生过滤条件包括但不限于：
网元类型、设备厂家、告警级别、告警标题、网管告警ID
输出参数：
告警数据文件，字段定义和实时告警一致。
同步告警文件采用txt格式文件，文件后缀为“.txt”，每条告警信息（告警产生或告警清除）为json格式，多个告警的{}间用\r\n分割。
格式样例：
{
"alarmSeq":
"10",
"alarmStatus":
"1",
"alarmId":
"410969",
"neUID":
"1301HWWX1ENB100000",
"neName":
"深圳同发路D-HLH",
……
"alarmCause":
"数据通道配置失败",
"addInfo":
"",
}
3.1.1.4.性能要求
实时性：
依同步周期确定。
小时级数据时延不大于30分钟
并发数：
无
吞吐量：
不小于640M/小时（按每天告警量15G估算），10W条/小时
4.告警实时查询接口能力
4.1.告警实时查询接口服务
4.1.1.告警实时查询接口服务
4.1.1.1.接口/服务描述（包括使用场景）
故障预处理、工单质检等场景下，查询少量告警的详细信息。
按照条件查询告警的详细信息。
查询条件项包括但不限于以下内容：
网元类型、设备厂家、告警级别、告警标题、网管告警ID；
4.1.1.2.接口形式
基于HTTP协议（RESTFUL+JSON），故障管理系统为接口服务提供方。
4.1.1.3.接口参数
输入参数：
参数名称
类型
是否必选
描述
city
地市
String（30）
否
deviceType
设备类型
String（30）
否
neName
网元名称
String（100）
否
vendor
厂家
String（30）
否
alarmTitle
告警标题
String（100）
否
bTime
开始时间
Date
是
告警的开始时间
eTime
结束时间
Date
是
告警的结束时间
serialno
告警流水号
String（30）
否
参数样例:
{
"opDetail":
{
"city":
"南京",
"deviceType":
"ONU",
"neName":
"南京ONUXXXX1",
"bTime":
"2014-02-2800:
46:
17",
"eTime":
"2014-02-2810:
46:
17",
"serialno":
"00|18988888"
}
}
注：
如果查询出来的条数大于100条，只返回前100条，返回告警总数大于100条的情况下，在返回结果的标签内的溢出标志overflow=”1”，否则overflow=”0”。
输出参数：
以JSON格式进行组织
参数英文名称
参数名称
类型
默认值
描述
serialno
告警流水号
String（30）
无
city
地市
String（30）
无
neName
网元名称
String（100）
无
alarmSeverity
告警级别
Int
（1）
无
1，2，3，4对应一级告警、二级告警、三级告警、四级告警
alarmTitle
告警标题
String（30）
无
deviceType
设备类型
String（30）
无
vendor
厂家
String（30）
无
eventTime
告警发生时间
Date
无
格式化：
2014-02-2800:
46:
17
clearTime
告警恢复时间
Date
无
格式化：
2014-02-2800:
46:
17
sheetNo
工单号
String（30）
无
sheetStatus
工单状态
String（30）
无
{
"opDetail":
{
"overflow":
1,
"alarmList":
[{
"alarm":
{
"serialno":
"00|18988888",
"city":
"南京",
"neName":
"南通市如东县如东海洋水建公司-JT-ONU001-ZX-F420_onu",
"alarmSeverity":
3,
"alarmTitle":
"PON信号丢失",
"deviceType":
"ONU",
"venDor":
"中兴",
"eventTime":
"2014-02-2800:
46:
17",
"clearTime":
"2014-02-2800:
56:
17",
"sheetNo":
"JS-234-140228-5",
"sheetStatus":
"已归档"
}
},
{
"alarm":
{
"serialno":
"00|18988889",
"city":
"南京",
"neName":
"南通市如东县如东海洋水建公司-JT-ONU001-ZX-F421_onu",
"alarmSeverity":
3,
"alarmTitle":
"PON信号丢失",
"deviceType":
"ONU",
"venDor":
"中兴",
"eventTime":
"2014-02-2800:
46:
18",
"clearTime":
"2014-02-2800:
56:
18",
"sheetNo":
"JS-234-140228-4",
"sheetStatus":
"已归档"
}
}]
}
}
4.1.1.4.性能要求
实时性：
单条告警不大于10秒
并发数：
大于等于15（按每小时5000条次估算）
处理能力：
每小时不小于5000次
5.告警统计接口能力
5.1.告警统计接口服务
5.1.1.告警统计接口服务
5.1.1.1.接口/服务描述（包括使用场景）
按照约定的统计项、统计维度、统计周期统计，对告警进行统计，将统计结果通过基于HTTP协议的（RESTFUL+JSON）发送给其他系统,供展示类应用使用。
5.1.1.2.接口形式
基于HTTP协议的（RESTFUL+JSON）。
5.1.1.3.接口参数
输入参数：
提前约定
参数名称
类型
是否必选
默认值
描述
告警统计项
String（500）
是
无
需要故障管理系统推送的告警统计项
告警统计周期
Int（5）
是
60
告警统计的周期单位为：
分钟
告警统计维度条件
String（100）
是
无
告警统计的维度：
地市、专业等
输出参数：
告警统计结果数据
参数名称
类型
是否必选
默认值
描述
告警统计项
String（500）
是
无
需要故障管理系统推送的告警统计项
告警统计周期（分钟）
Int（5）
是
60
告警统计的周期
告警统计维度值
String（100）
是
无
告警统计的维度：
地市、专业等
统计值
String（50）
是
无
分维度统计结果值
5.1.1.4.性能要求
实时性：
依统计周期确定，小时级数据时延不大于15分钟
并发数：
大于等于10
吞吐量：
无
6.告警字段说明附录
告警字段：
参见《中国移动故障管理系统规范V3.0》中《03-01中国移动故障管理系统-数据规范-告警与资源》分册。
告警消息序号（alarmSerial），队列中的告警消息需连续标识，用于判断是否丢失告警消息，具体要求如下：
1、用连续正整数编号，初始编号从1开始，如果编号超过最大正整数（2^31-1）重新从1开始编号。
2、发送给多个告警数据消费者队列，每个队列维护一个独立的告警消息序号。
3、在系统升级等情况下，故障管理系统需保证序号能够连续编号。
告警字段值不能包含其它任何一个“告警字段:
升级会员 