边缘应用告警规则对接

1.对接目标

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

2.云端告警规则API

2.1 描述

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

2.2 准备工作

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

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

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

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

2.3 接入指南

2.3.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.4 API说明

• API仅支持HTTPS协议，以post请求访问；

• API调用SDK及样例参考地址： https://github.com/aliyun/iotx-api-gateway-client。

返回报文格式

业务返回码定义

2.5 具体API开发

2.5.1 新增或更新告警规则

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

接口定义

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

入参

入参明细

出参data域（String）

业务示例

新增云端单设备阈值告警规则，时间窗口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

入参

入参明细

点击操作如下图所示：

出参data域（JSONArray）

出参data域（JSONArray）

业务示例

批量删除边缘端告警。

请求示例

{
    ["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

入参

入参明细

出参data域（JSONObject）

业务示例

筛选条件全填，查询第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

入参

入参明细

出参data域（JSONObject）

业务示例

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

请求示例

{
    "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

入参

入参明细

出参data域（JSONArray）

业务示例

批量停止告警规则。

请求示例

{
    ["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

入参

入参明细

出参data域（JSONObject）

业务示例

批量确认告警记录。

请求示例

{
    "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字段代表数据总数。

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

获取集群列表

接口定义

入参

出参

分页数据对象ClusterDTOList

示例

请求示例

{
  "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"
        }]
    }
}

数据同步预检查

接口定义

入参

出参

示例

请求示例

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

返回示例

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

触发数据同步

接口定义

入参

出参

示例

请求示例

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

返回示例

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

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

接口定义

入参

出参

示例

请求示例

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

返回示例

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

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

接口定义

入参

出参

示例

请求示例

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

返回示例

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

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

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

消息示例：

{
    "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"

 }

恢复告警包含如下字段：

5. HTTP 接口

告警规则查询

API名称

getAlarmRuleList

请求地址

/alarm/rule/get

版本1.0.0请求参数

返回参数

告警规则批量启停

API名称

operateAlarmRule

请求地址

/alarm/rule/operate

版本1.0.0请求参数

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

告警事件查询

API名称

getAlarmRecordList

请求地址

/alarm/record/get

版本1.0.0请求参数

返回参数

告警事件批量确认

API名称

confirmAlarmRecord

请求地址

/alarm/record/confirm

版本1.0.0请求参数

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

6. 附录

6.1 sceneConfig和lowSceneConfig格式

云端告警配置

云端sceneConfig

边缘告警配置

边缘sceneConfig