文档

边缘应用告警规则对接

更新时间:
一键部署

1.对接目标

1.云端:提供云端的SDK API给到ISV用于管理态的应用的远端告警API调用。2.同步:平台通过云->边同步机制,把云端的应用的告警规则和数据同步到边缘集群。3.边侧:提供边侧的SDK API给到ISV用于运行态告警规则的校验和信息获取。

2.云端告警规则API

2.1 描述

告警开放服务是应用服务平台告警功能的API版本,除继承原有告警功能外,还扩展支持告警边缘端部署运行不同类型设备联合告警时间窗口延迟触发告警等功能

2.2 准备工作

开始接入告警开放服务前,需要入驻应用服务平台:

  • 创建新项目或进入已有项目,在添加能力中选择空间管理、告警开放服务

  • 确保在空间管理的绑定空间功能中,将需要云端触发告警的设备绑定到空间中。

  • 在项目集成态能力列表中,网关菜单创建网关实例,将需要边缘端触发的告警设备绑定网关。

2.3 接入指南

2.3.1 接入步骤

1

AppKey和AppSecret

AppKey:API访问凭证编号,用于验证API接入API Gateway合法性;AppSecret:与AppKey配套的验证密钥,请妥善保管并确保不在网络中传输。所有的告警服务API均定义在IoT API网关上,AppKey和AppSecret是API网关的凭证访问,用户在接入时,可集成iot-api-gateway-clientsdk,并配置AppKey和AppSecret。在应用服务平台创建项目后,可进入项目,在项目开发态里获取到AppKey和AppSecret。如下图所示:2

2.4 API说明

返回报文格式

参数

类型

备注

code

Integer

业务返回码

message

String

英文描述信息

localMessage

String

中文描述信息

data

null(无数据)

这时没有data字段,表示接口的返回值中没有结果;

JSONObject(对象类型)

表示结果是一系列值,值的类型要根据接口而定;

JSONArray(数组类型)

表示结果是一系列值,值的类型要根据接口而定;

Integer/Long/Byte/Double等(值类型)

表示结果是一系列值,值的类型要根据接口而定;

业务返回码定义

错误码

错误信息

业务结果描述

200

success.

成功

500

service error.

服务端错误

10374

There are rules with the same content.

该规则触发源设置的规则数量已经超过上限。

28403

The project not exist.

该项目不存在。

28405

Param illegal.

参数非法。

28420

No access to alarm rule.

无权访问该告警规则。

28457

Alarm status illegal.

规则状态不合法。

29262

Alarm lowSceneConfig error.

限值告警下限配置错误。

29263

InstanceId param error.

边缘实例ID错误。

29264

InstanceId not exist.

边缘实例ID不存在。

29267

Deploy alarm instance error.

部署告警边缘实例失败。

29268

Alarm device not bind.

配置告警的设备未绑定到项目。

29269

Only cloud support multiDevice.

只有云端告警支持多设备。

2.5 具体API开发

2.5.1 新增或更新告警规则

新增或更新云端或边端告警规则。

接口定义

路径:/alarm/rule/addorupdate版本:1.0.0

入参

参数名

字段类型

是否必填

描述

alarmName

String

必填

告警规则名称

alarmLevel

Integer

必填

告警等级,0严重,1高,2中,3低

auxiliaryLevel

Integer

非必填

辅助等级,0~999,客户自定义

alarmContent

String

必填

告警内容

productKey

String

必填

设备PK

sceneConfig

String

必填

阈值告警规则配置(限值告警高限值配置)

receivers

JSONArray

非必填

告警接收者

-> type

String

非必填

类型,EMAIL邮件,receivers存在时必填

-> email

String

非必填

邮箱地址

alarmType

Integer

必填

告警类型,1运行告警,2故障告警

alarmMode

Integer

必填

告警模式,1阈值告警,2限值告警

timeWindow

Integer

非必填

时间窗口,持续一段时间后触发,单位:秒,边缘告警不填

runEnv

String

必填

运行环境,cloud云端,edge边缘端

alarmRuleId

String

非必填

告警规则ID,更新时必填

lowSceneConfig

String

非必填

限值告警的低限值规则配置,限制告警必填

入参明细

参数名

字段描述

sceneConfig

见附录1

lowSceneConfig

见附录1

出参data域(String)

参数名

字段类型

描述

新增或更新的告警记录ID

业务示例

新增云端单设备阈值告警规则,时间窗口5分钟。

请求示例

{
    "alarmName": "新增告警规则",
    "alarmLevel": 0,
    "auxiliaryLevel": 10,
    "alarmContent": "设备产生告警",
    "productKey": "a1gEQeIkPn5",
    "sceneConfig": "{/* 见附录1 */}",
    "receivers": [
      {
          "type": "EMAIL",
        "email": "test@163.com"
      }
    ]
    "alarmType": 1,
    "alarmMode": 1,
    "timeWindow": 300,
    "runEnv": "cloud",
    "multiDevice": 0
}

返回示例

返回成功:
{
    "code": 200,
    "message": "success",
    "data": "8e2e8d41f4604878b413fc588333f068"
}

返回失败:
{
    "code": 28403,
    "message": "The project not exist",
    "localizedMsg": "该项目不存在"
}

2.5.2 批量删除告警规则

单条或批量删除告警规则,返回删除失败的规则ID。

接口定义

路径:/alarm/rule/delete版本:1.0.0

入参

参数名

字段类型

是否必填

描述

alarmRuleIds

JSONArray

必填

告警规则ID的集合

clusterId

String

非必填

集群ID,告警运行在边缘端时必填

入参明细

参数名

字段描述

clusterId

集群ID

点击操作如下图所示:3

出参data域(JSONArray)

数组子参数

删除失败的告警规则ID

出参data域(JSONArray)

数组子参数

删除失败的告警规则ID

业务示例

批量删除边缘端告警。

请求示例

{
    ["8e2e8d41f4604878b413fc588333f068", "df152383d40842b0814346cc88cfd1b4"],
    "pVxFeNmZ8axogEnWCD9E"
}

返回示例

返回成功:
{
    "code": 200,
    "message": "success",
    "data": ["df152383d40842b0814346cc88cfd1b4"]
}

返回失败:
{
    "code": 28420,
    "message": "No access to alarm rule",
    "localizedMsg": "无权访问该告警规则"
}

2.5.3 分页查询告警规则列表

分页查询告警规则列表,按创建日期倒序。

接口定义

路径:/alarm/rule/query版本:1.0.0

入参

参数名

字段类型

是否必填

描述

nameLike

String

非必填

告警规则名称,模糊匹配

alarmLevel

Integer

非必填

告警等级,0严重,1高,2中,3低

status

Integer

非必填

启用状态,1启用,0停止

alarmType

Integer

非必填

告警类型,1运行告警,2故障告警

alarmMode

Integer

非必填

告警模式,1阈值告警,2限值告警,默认阈值告警

runEnv

String

非必填

运行环境,cloud云端,edge边缘端

pageNo

Integer

非必填

当前页码,默认1

pageSize

Integer

非必填

每页条数,默认20

入参明细

参数名

字段描述

出参data域(JSONObject)

参数名

字段类型

描述

total

Integer

总条数

pageNo

Integer

当前页码

pageSize

Integer

每页条数

data

Integer

告警规则列表

-> alarmRuleId

String

告警规则ID

-> alarmName

String

告警规则名称

-> status

Integer

启用状态,1启用,0停止

-> alarmLevel

Integer

告警等级,0严重,1高,2中,3低

-> auxiliaryLevel

Integer

辅助等级,0~999,用户自定义

-> content

String

告警内容

-> productKey

String

设备PK

-> alarmType

Integer

告警类型,1运行告警,2故障告警

-> runEnv

String

运行环境,cloud云端,edge边缘端

-> multiDevice

Integer

是否多设备,0单设备,1多设备

-> alarmMode

Integer

告警模式,1阈值告警,2限值告警

-> timeWindow

Integer

时间窗口,告警满足条件持续一段时间后触发,单位:秒

业务示例

筛选条件全填,查询第1页10条告警规则。

请求示例

{
    "nameLike": "告警",
    "alarmLevel": 0,
    "alarmType": 1,
    "status": 1,
    "alarmMode": "2",
    "runEnv": "edge",
    "pageNo": 1,
    "pageSize": 10
}

返回示例

返回成功:
{
    "code": 200,
    "message": "success",
    "data": {
        "total": 100,
        "pageNo": 1,
        "pageSize": 10,
        "data": [
            {
                "alarmRuleId": "df152383d40842b0814346cc88cfd1b4",
                "alarmName": "设备告警",
                "status": 1,
                "alarmLevel": 0,
                "auxiliaryLevel": 5,
                "content": "设备电压超标",
                "productKey": "a1gEQeIkPn5",
                "alarmType": 1,
                "runEnv": "edge",
                "multiDevice": 0,
                "alarmMode": 2,
                "timeWindow": 600
            }
        ]
    }
}

返回失败:
{
    "code": 28403,
    "message": "The project not exist",
    "localizedMsg": "该项目不存在"
}

2.5.4 查询单个告警规则的详情

根据告警规则ID查询单个告警规则的详情。

接口定义

路径:/alarm/rule/detail/get版本:1.0.0

入参

参数名

字段类型

是否必填

描述

alarmRuleId

String

必填

告警规则ID

入参明细

参数名

字段描述

出参data域(JSONObject)

参数名

字段类型

描述

alarmRuleId

String

告警规则ID

alarmName

String

告警规则名称

status

Integer

启用状态,1启用,0停止

alarmLevel

Integer

告警等级,0严重,1高,2中,3低

auxiliaryLevel

Integer

辅助等级,0~999,用户自定义

content

String

告警内容

productKey

String

设备PK

sceneConfig

String

阈值告警规则配置(限值告警高限值配置)

receivers

JSONArray

告警接收者

-> type

String

类型,EMAIL邮件

-> email

String

邮箱地址

alarmType

Integer

告警类型,1运行告警,2故障告警

lowSceneConfig

String

限值告警的低限值规则配置

runEnv

String

运行环境,cloud云端,edge边缘端

multiDevice

Integer

是否多设备,0单设备,1多设备

alarmMode

Integer

告警模式,1阈值告警,2限值告警

timeWindow

Integer

时间窗口,告警满足条件持续一段时间后触发,单位:秒

业务示例

查询单个告警规则的详细信息。

请求示例

{
    "alarmRuleId": "df152383d40842b0814346cc88cfd1b4"
}

返回示例

返回成功:
{
    "code": 200,
    "message": "success",
    "data": {
        "alarmRuleId": "df152383d40842b0814346cc88cfd1b4",
        "alarmName": "设备告警",
        "status": 1,
        "alarmLevel": 0,
        "auxiliaryLevel": 5,
        "content": "设备电压超标",
        "productKey": "a1gEQeIkPn5",
        "sceneConfig": "{}",
        "receivers": [
          {
            "type": "EMAIL",
            "email": "test@163.com"
          }
        ],
        "alarmType": 1,
        "lowSceneConfig": "{}",
        "runEnv": "edge",
        "multiDevice": 0,
        "alarmMode": 2,
        "timeWindow": 600
    }
}

返回失败:
{
    "code": 28403,
    "message": "The project not exist",
    "localizedMsg": "该项目不存在"
}

2.5.5 批量操作告警规则启停

批量启动、停止告警规则。

接口定义

路径:/alarm/rule/status/update版本:1.0.0

入参

参数名

字段类型

是否必填

描述

alarmRuleIds

JSONArray

必填

告警规则ID

operType

Integer

必填

操作类型,1启动,0停止

clusterId

String

非必填

集群ID,告警运行在边缘端时必填

入参明细

参数名

字段描述

出参data域(JSONArray)

参数名

字段类型

描述

启停失败的告警规则ID

业务示例

批量停止告警规则。

请求示例

{
    ["8e2e8d41f4604878b413fc588333f068", "df152383d40842b0814346cc88cfd1b4"],
    "operType": 0,
    "pVxFeNmZ8axogEnWCD9E"
}

返回示例

返回成功:
{
    "code": 200,
    "message": "success",
    "data": ["df152383d40842b0814346cc88cfd1b4"]
}

返回失败:
{
    "code": 28420,
    "message": "No access to alarm rule",
    "localizedMsg": "无权访问该告警规则"
}

2.5.6 批量更新告警记录确认状态

批量确认告警记录。

接口定义

路径:/alarm/record/confirm版本:1.0.0

入参

参数名

字段类型

是否必填

描述

alarmRecordIds

JSONArray

必填

告警记录ID

confirm

Integer

必填

确认状态,0未确认,1已确认

入参明细

参数名

字段描述

出参data域(JSONObject)

参数名

字段类型

描述

修改确认状态失败的告警记录ID

业务示例

批量确认告警记录。

请求示例

{
    "alarmRecordIds": [1000000001, 1000000002],
    "confirm": 1
}

返回示例

返回成功:
{
    "code": 200,
    "message": "success",
    "data": [1000000002]
}

返回失败:
{
    "code": 28403,
    "message": "The project not exist",
    "localizedMsg": "该项目不存在"
}

3.云端和边缘端数据同步API

地产平台通过封装LP云边同步能力,对外开放如下API:0、获取边缘集群列表1、数据同步预检查2、触发数据同步3、数据同步结果查询

3.1 接口定义

分页参数会出现在请求参数和返回结果中,用于下文中API调用参照。

  • 在请求参数中代表请求分页的页数(pageNo)和每页的记录数(pageSize)。

  • 在响应结果中的页数(pageNo)和每页的记录数(pageSize)与请求参数一致,同时还有total字段代表数据总数。

所有的分页接口除特殊说明外,都遵循下面的约束:

参数

类型

备注

pageNo

Integer

请求的页码非必填,默认为1,有效范围 [1, ∞)

pageSize

Integer

每页的记录数非必填,默认为20,有效范围[1,100]

获取集群列表

接口定义

path

版本

是否需要登录

/home/paas/cluster/edge/query

1.0.0

入参

字段

类型

是否必传

备注

pageNo

Integer

请求的页码,请求的页码,详细见上述分页参数定义。

pageSize

Integer

每页的记录数,详细见请求的页码,详细见上述分页参数定义。

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

data

JSONObject

-data

ClusterDTOList

分页数据对象列表ClusterDTOList

-pageNo

Integer

请求的页码,详细见请求的页码,详细见上述分页参数定义。

-pageSize

Integer

请求的页码,详细见请求的页码,详细见上述分页参数定义。

-total

Integer

总记录数

分页数据对象ClusterDTOList

id

String

集群ID

name

String

集群名称

gmtCreate

String

集群创建时间

gmtModified

String

集群修改时间

示例

请求示例

{
  "pageNo":1,
  "pageSize":20
}

返回示例

{
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data":{
    "pageNo": 1,
    "pageSize": 20,
    "total": 10,
      "data":[{
        "id": "xxx",
      "name": "cluster01",
        "gmtCreate": "2020-03-04 18:00:00",
        "gmtModified": "2020-03-04 18:00:00"
        }]
    }
}

数据同步预检查

接口定义

path

版本

是否需要登录

/home/paas/data/edge/sync/precheck

1.0.0

入参

字段

类型

是否必传

备注

clusterId

String

集群ID

opsType

String

SYNC_DATA - 同步数据CLEAR_DATA - 清理数据

dataTypeList

JSONArray

数据类型列表

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

data

String

SYNCING - 同步中NO - 不需要同步YES - 需要同步

示例

请求示例

{
  "clusterId": "xxx",
  "opsType": "SYNC_DATA",
  "dataTypeList": [
      "ACCOUNT",
    "SPACE"
    "RTPC"
    "ALARM"
  ]
}

返回示例

{
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data": "XXX"
}

触发数据同步

接口定义

path

版本

是否需要登录

/home/paas/data/edge/sync/dispatch

1.0.0

入参

字段

类型

是否必传

备注

clusterId

String

集群ID

opsType

String

SYNC_DATA - 同步数据CLEAR_DATA - 清理数据

dataTypeList

JSONArray

数据类型列表

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

data

String

taskGroupId - 任务组ID

示例

请求示例

{
  "clusterId": "xxx",
  "opsType": "SYNC_DATA",
  "dataTypeList": [
      "ACCOUNT",
    "SPACE"
  ]
}

返回示例

{
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data": "XXX"
}

根据数据同步请求查询结果

接口定义

path

版本

是否需要登录

/home/paas/data/edge/sync/query

1.0.0

入参

字段

类型

是否必传

备注

clusterId

String

集群ID

opsType

String

SYNC_DATA - 同步数据CLEAR_DATA - 清理数据

dataTypeList

JSONArray

数据类型列表

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

data

JSONObject

-dataSyncStatus

String

同步的结果NONE - 无任务SYNCING - 同步中SUCCESS - 同步成功FAIL - 同步失败

-preCheckResult

String

是否需要同步SYNCING - 同步中NO - 不需要同步YES - 需要同步

-taskGroupId

String

任务组ID,便于工单排查

示例

请求示例

{
  "clusterId": "xxx",
  "opsType": "SYNC_DATA",
  "dataTypeList": [
      "ACCOUNT",
    "SPACE"
  ]
}

返回示例

{
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data": {
    "dataSyncStatus": "SUCCESS",
    "preCheckResult": "NO",
    "taskGroupId": "XXX"
  }
}

根据任务组查询数据同步结果

接口定义

path

版本

是否需要登录

/home/paas/data/edge/sync/querybytaskgroupid

1.0.0

入参

字段

类型

是否必传

备注

taskGroupId

String

任务组ID

出参

字段

类型

备注

code

Integer

返回码

message

String

返回信息

data

String

同步的结果NONE - 无任务SYNCING - 同步中SUCCESS - 同步成功FAIL - 同步失败

示例

请求示例

{
  "clusterId": "xxx",
  "opsType": "SYNC_DATA",
  "dataTypeList": [
      "ACCOUNT",
    "SPACE"
  ]
}

返回示例

{
  "code": 200,
  "message": null,
  "localizedMsg": null,
  "data": "SUCCESS"
}

4.边缘端实时告警事件订阅MQ

请求主题为: IOTX_ALARM_RECORD消息内容: 消息分为两种,一种是告警类型消息,另外一种是恢复告警类型消息,可以根据recovery的值来判断。每个消息体是一个JSON字符串。包括如下字段:

key

value

alarmId

记录ID

alarmName

告警名称

deviceName

设备DN

productKey

设备PK

alarmLevel

告警等级

auxiliaryLevel

告警辅助等级,0-999

recovery

固定为0,代表触发告警类型

alarmContent

告警内容

alarmType

告警类型,1运行告警,2故障告警

alarmMode

告警模式,1阈值告警,2限值告警

restrictAlarmType

限值告警类型 1 高限值告警 2低限值告警

extConfig

扩展配置

time

告警时间

sceneId

规则ID

消息示例:

{
    "alarmId": "alarm_event_id_0000001",
  "sceneId":"xxxxx",
  "alarmName": "alarmName1",
  "deviceName": "devicename1",
  "productKey": "productKey1",
  "alarmLevel": 3,
  "auxiliaryLevel": 300,
  "recovery": 1,
  "recoverTime": "2019-12-24 12:40:00",
  "alarmContent": "room1001温度过高",
  "alarmType": 1,
  "alarmMode": 1,
  "restrictAlarmType": 1,
  "extConfig": "{\"trigger\":\"device1\", ... }",
  "time": "2019-12-23 12:39:00"

 }

恢复告警包含如下字段:

key

value

alarmName

告警名称

deviceName

设备DN

productKey

设备PK

alarmLevel

告警等级

auxiliaryLevel

告警辅助等级,0-999

alarmContent

告警内容

alarmType

告警类型,1运行告警,2故障告警

alarmMode

告警模式,1阈值告警,2限值告警

restrictAlarmType

限值告警类型 1 高限值告警 2低限值告警

extConfig

扩展配置

time

告警时间

sceneId

规则ID

recovery

值固定为1,代表恢复告警类型

recoveryTime

告警恢复时间

5. HTTP 接口

告警规则查询

API名称

getAlarmRuleList

请求地址

/alarm/rule/get

版本1.0.0请求参数

参数名

参数描述

字段类型

是否允许为空

appKey

应用appKey

String

不可空

pageSize

页面大小

Integer

不可空

pageNo

当前页码,从1开始

Integer

不可空

alarmNameLike

告警名称

String

可空

alarmLevel

告警等级,0严重,1高,2中,3低

Integer

可空

alarmType

告警类型,1运行告警,2故障告警

Integer

可空

alarmMode

告警模式,1阈值告警,2限值告警

Integer

可空

status

告警状态查询, 1启用,0未启用

Integer

可空

edgeProductKey

设备PK

String

可空

edgeDeviceName

设备DN

String

可空

返回参数

参数名

参数描述

字段类型

alarmRuleId

规则ID

String

name

告警名称

String

status

启用状态,1启用,0未启用

String

alarmLevel

告警等级,0-3

Integer

auxiliaryLevel

告警辅助等级,0-999

Integer

alarmMode

告警模式,1阈值告警,2限值告警

Integer

alarmType

告警类型,1运行告警,2故障告警

Integer

alarmContent

告警内容

String

sceneConfig

场景规则配置

String

extConfig

扩展配置

String

lowSceneConfig

限值告警的低阈值场景规则配置

String

email

接收告警的邮箱

List

告警规则批量启停

API名称

operateAlarmRule

请求地址

/alarm/rule/operate

版本1.0.0请求参数

返回参数Boolean类型,表示是否启动或停止成功。

告警事件查询

API名称

getAlarmRecordList

请求地址

/alarm/record/get

版本1.0.0请求参数

参数名

参数描述

字段类型

是否允许为空

appKey

应用ID

String

不可空

ruleIds

告警规则ID列表

List

operation

启动或停止操作。1启动,0停止

Byte

不可空

不可空

参数名

参数描述

字段类型

是否允许为空

appKey

应用ID

String

不可空

pageSize

页面大小

Integer

不可空

pageNo

当前页码

Integer

不可空

alarmName

告警名称

String

可空

alarmLevel

告警等级

Integer

可空

productKey

设备PK

String

可空

deviceName

设备DN

String

可空

recovery

是否恢复

Byte

可空

confirm

是否确认

Byte

可空

confirmType

确认类型。1故障,2误报,3报警

Byte

可空

confirmComment

确认描述

String

可空

startDate

起始时间(yyyy-MM-dd HH:mm:ss)

String

可空

endDate

截止时间(yyyy-MM-dd HH:mm:ss)

String

可空

alarmType

告警类型,1运行告警,2故障告警

Byte

可空

alarmMode

告警模式,1阈值告警,2限值告警

Byte

可空

restrictAlarmType

限值告警类型 1 高限值告警 2低限值告警

Byte

可空

返回参数

参数名

参数描述

字段类型

alarmId

记录ID

String

alarmName

告警名称

String

deviceName

设备DN

String

productKey

设备PK

String

productName

产品名

String

alarmLevel

告警等级

Integer

auxiliaryLevel

告警辅助等级,0-999

Integer

recovery

是否恢复

Byte

confirm

是否确认

Byte

confirmType

确认类型。1故障,2误报,3报警

Byte

confirmComment

确认描述

String

recoveryTime

恢复时间(yyyy-MM-dd HH:mm:ss)

Date

confirmTime

确认时间(yyyy-MM-dd HH:mm:ss)

Date

alarmContent

告警内容

String

alarmType

告警类型,1运行告警,2故障告警

Byte

alarmMode

告警模式,1阈值告警,2限值告警

Byte

restrictAlarmType

限值告警类型 1 高限值告警 2低限值告警

Byte

extConfig

扩展配置

String

time

告警时间

Date

operator

操作人员

String

告警事件批量确认

API名称

confirmAlarmRecord

请求地址

/alarm/record/confirm

版本1.0.0请求参数

参数名

参数描述

字段类型

是否允许为空

appKey

应用ID

String

不可空

alarmIds

告警ID列表

List<String>

不可空

confirm

确认状态

Byte

不可空

operator

确认操作人

String

不可空

confirmType

确认类型(1故障,2误报,3报警)

Byte

可空

confirmComment

确认描述(最大长度256)

String

可空

返回参数Boolean类型,表示是否确认成功。

6. 附录

6.1 sceneConfig和lowSceneConfig格式

云端告警配置

云端sceneConfig

边缘告警配置

边缘sceneConfig

  • 本页导读 (0)
文档反馈