设备异常

一、应用场景

异常是一种物联云平台对设备触发异常规则后的状态定义，异常是可被恢复和处理的，所以异常是有状态的，分别为待处理、已处理和恢复。异常记录则是针对发生异常的设备进行设备信息和异常信息的展示。
开发者可通过本服务来获取设备异常的状态、记录等信息，也可通过相应接口来完成对异常的处理
客户可以在其他应用中完成处理异常的操作，可通过获取到相应的异常记录，通过本服务对异常记录进行处理，完成业务闭环。

二、功能说明

本服务提供设备异常的状态、记录查询，开发者可通过此能力获取异常的相关信息，并可以使用异常处理能力，完成异常的处理。

三、前提条件

  1. 获取授权

四、关键流程

无

五、API列表

5.1 查询告警状态、记录

5.1.1 查看异常规则当前状态列表

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）展示告警的异常或恢复状态。

接口限制：B端用户权限。

返回信息：异常规则列表，包括告警类型，等级，触发时间等。

请求方式

POST

请求地址

/v2/corp/alarm/states

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json
Api-Version true int 固定为：3

请求参数

名称 必填 类型 备注
offset False Int 从某个偏移量开始请求，默认为0
limit False Int 请求的条目数量，默认为10
order False Map<String,String> 可以指定通过设备默认的某个字段排序（键值对），desc降序，asc升序
filter False List<String> 指定返回字段（字符串列表）
query True Object 查询字段，支持字段：id、device_id、rule_id、product_id、status、content、count、new_time、start_time、exception_count、tag_id、alarm_state_id、alarm_type、association_id、system_scope

请求示例：

{
    "offset": 0,
    "limit": 10,
    "query": {
        "device_id": {
            "$in": [237303308,1043107594]
        }
    },
    "filter": [
        "id",
        "name",
        "product_name",
        "device_id",
        "product_id",
        "rule_id",
        "status",
        "content",
        "current_value",
        "start_time"
    ],
    "order": {
        "start_time": "desc"
    }
}

返回参数说明

名称 必填 类型 备注
count True Int 符合查询条件异常状态总数
list True List 当前异常状态列表
list.id True String 异常状态ID
list.product_id True String 产品ID
list.device_id True Int 设备ID
list.rule_id True String 异常规则ID
list.status True Int 异常状态，枚举值，1：异常；2：恢复；4：处理中
list.content True String 异常内容
list.count True Int 异常次数
list.current True String 引发异常的设备值
list.start_time True String 触发异常开始时间，格式：yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.new_time True String 最新一次达到异常时间，格式：yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.mac True String 设备MAC
list.exception_count True Int 异常次数
list.tag_id True String 异常等级标签
list.current_value True String 异常当前值, key->value格式，用来标识多个属性触发的异常值
list.alarm_state_id True String 异常状态标识
list.alarm_type True Int 异常告警类型, 枚举值：1：单个物模型属性告警，2：在线状态告警，3：单个物模型属性状态持续变化告警，4：多个物模型属性状态持续变化告警，5：多个物模型属性告警
list.system_scope False Int 规则范围，枚举值，0：产品下全部设备；1：项目下指定设备；2：品类下指定设备；3：产品下指定设备；4：边缘计算应用；默认为0。

返回示例：

{
    "count": "异常状态总数",
    "list": [{
        "id": "异常状态id",
        "product_id": "设备异常状态所属产品标识",
        "device_id": "产生异常状态的设备标识",
        "rule_id": "异常规则标识",
        "status": "异常状态",
        "content": "异常内容",
        "current": "引发异常的当前值",
        "count": "此状态已异常次数",
        "start_time": "异常开始时间",
        "new_time": "最近异常时间",
        "mac": "设备mac地址",
        "exception_count": "异常次数",
        "tag_id": "异常标签标识",
        "current_value": "异常异常当前值, json对象",
        "alarm_state_id": "异常状态标识",
        "alarm_type": "1",
        "system_scope": 1
    }, {
        "id": "异常状态id",
        "product_id": "设备异常状态所属产品标识",
        "device_id": "产生异常状态的设备标识",
        "rule_id": "异常规则标识",
        "status": "异常状态",
        "content": "异常内容",
        "current": "引发异常的当前值",
        "count": "此状态已异常次数",
        "start_time": "异常开始时间",
        "new_time": "最近异常时间",
        "mac": "设备mac地址",
        "exception_count": "异常次数",
        "tag_id": "异常标签标识",
        "current_value": "异常异常当前值, json对象",
        "alarm_state_id": "异常状态标识",
        "alarm_type": "1",
        "system_scope": 0
    }]
}
错误码 描述
4001001 参数验证不通过
4001002 参数不能为空

5.1.2 查询历史异常记录

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）查询设备历史异常记录。

接口限制：B端用户权限。

返回信息：设备异常历史记录。

请求方式

POST

请求地址

/v2/corp/alarm/state-reccords

请求头

名称 必填 类型 备注
Access-Token true String 访问Token（B端用户权限）
Content-Type true String application/json
Api-Version true int 固定为：3

请求参数

名称 必填 类型 备注
offset False Int 请求起始偏移量，默认为0
limit False Int 本次请求数量，默认为10
filter True List<String> 返回列表需要字段（字符串列表）
query False Object 查询字段，支持字段：id、device_id、rule_id、product_id、status、notify_type、content、count、new_time、start_time、exception_count、tag_id、alarm_type、notification_content、association_id、system_scope
order False Map<String,String> 排序

请求示例：

{
    "offset": 0,
    "limit": 10,
    "query": {
        "device_id": {
            "$in": [237303308,1043107594]
        }
    },
    "filter": [
        "id",
        "name",
        "product_name",
        "device_id",
        "product_id",
        "rule_id",
        "status",
        "content",
        "current_value",
        "start_time"
    ],
    "order": {
        "start_time": "desc"
    }
}

返回参数说明

名称 必填 类型 备注
count True Int 异常状态历史记录总数
list True List<Object> 异常状态历史记录列表
list.id True String 异常状态历史记录标识
list.product_id True String 产品ID
list.device_id True Int 设备ID
list.rule_id True String 异常规则ID
list.status True Int 异常状态，枚举值，1：异常；2：恢复；3：已处理；4：处理中
list.content True String 异常内容
list.count True Int 异常次数
list.current True String 引发异常的当前值
list.start_time True String 异常开始时间，格式：yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.new_time True String 最近一次异常时间，格式：yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.mac True String 设备MAC
list.exception_count True Int 异常次数
list.tag_id True String 异常等级标签
list.current_value True String 异常异常当前值, json对象
list.alarm_type True Int 异常类型, 1:数据端点异常, 2:设备状态异常, 3:数据端点状态持续变化异常, 4:多数据端点状态持续变化异常,5:多数据端点异常
list.processing False Object 处理中的相关信息
list.processing.dealing_person False String 处理中人
list.processing.dealing_cause False String 处理中处理原因
list.processing.dealing_time False String 处理中处理时间，格式：yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.processing.dealing_type False Int 处理类型，1:正常，2:误报，3:调试
list.processed False Object 已处理的相关信息
list.processed.dealing_person False String 已处理人
list.processed.dealing_cause False String 已处理原因
list.processed.dealing_time False String 已处理处理时间，格式：yyyy-MM-dd’T’HH:mm:ss.SS’Z’
list.processed.dealing_type False Int 处理类型，1:正常，2:误报，3:调试
list.system_scope False Int 规则范围，枚举值，0：产品下全部设备；1：项目下指定设备；2：品类下指定设备；3：产品下指定设备；4：边缘计算应用；默认为0。

返回示例：

{
    "count": "异常状态历史记录总数",
    "list": [{
            "id": "异常状态历史记录标识",
            "product_id": "设备异常状态历史记录所属产品标识",
            "device_id": "产生异常状态历史记录的设备标识",
            "rule_id": "异常规则标识",
            "status": "异常历史记录状态",
            "content": "异常历史记录内容",
            "current": "引发历史记录异常的当前值",
            "count": "此状态已异常次数",
            "start_time": "历史记录异常开始时间",
            "new_time": "历史记录最近异常时间",
            "recover_time": "历史记录恢复时间",
            "processed_time": "历史记录被处理时间",
            "mac": "历史记录设备mac地址",
            "exception_count": "异常次数",
            "tag_id": "异常标签标识",
            "current_value": "异常异常当前值, json对象",
            "alarm_state_id": "异常状态标识",
            "alarm_type": "异常类型, 1:数据端点异常, 2:设备状态异常, 3:数据端点状态持续变化异常, 4:多数据端点状态持续变化异常,5:多数据端点异常",
            "processing": {
                "dealing_person": "处理中处理人",
                "dealing_cause": "处理中处理原因",
                "dealing_time": "处理中处理时间",
                "dealing_type": "处理类型，1:正常，2:误报，3:调试"
            },
            "processed": {
                "dealing_person": "已处理处理人",
                "dealing_cause": "已处理处理原因",
                "dealing_time": "已处理处理时间",
                "dealing_type": "处理类型，1:正常，2:误报，3:调试"
            },
            "system_scope": 1
        },
        {
            "id": "异常状态历史记录标识",
            "product_id": "设备异常状态历史记录所属产品标识",
            "device_id": "产生异常状态历史记录的设备标识",
            "rule_id": "异常规则标识",
            "status": "异常历史记录状态",
            "content": "异常历史记录内容",
            "current": "引发历史记录异常的当前值",
            "count": "此状态已异常次数",
            "start_time": "历史记录异常开始时间",
            "new_time": "历史记录最近异常时间",
            "recover_time": "历史记录恢复时间",
            "processed_time": "历史记录被处理时间",
            "mac": "历史记录设备mac地址",
            "exception_count": "异常次数",
            "tag_id": "异常标签标识",
            "current_value": "异常异常当前值, json对象",
            "alarm_state_id": "异常状态标识",
            "alarm_type": "异常类型, 1:数据端点异常, 2:设备状态异常, 3:数据端点状态持续变化异常, 4:多数据端点状态持续变化异常,5:多数据端点异常",
            "processing": {
                "dealing_person": "处理中处理人",
                "dealing_cause": "处理中处理原因",
                "dealing_time": "处理中处理时间",
                "dealing_type": "处理类型，1:正常，2:误报，3:调试"
            },
            "processed": {
                "dealing_person": "已处理处理人",
                "dealing_cause": "已处理处理原因",
                "dealing_time": "已处理处理时间",
                "dealing_type": "处理类型，1:正常，2:误报，3:调试"
            },
            "system_scope": 0
        }
    ]
}
错误码 描述
4001001 参数验证不通过
4001002 参数不能为空

5.2 处理异常

5.2.1 标记当前异常记录为已处理

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）批量标记当前异常记录为已处理。

接口限制：B端用户权限。

请求方式

POST

请求地址

/v2/corp/alarm/state-processed?parameter=base64(dealingContent)

名称 必填 类型 备注
parameter False string 处理意见，格式为 base64(dealingContent)，其中dealingContent为JSON字符串 { “dealing_person”: “处理人”, “dealing_cause”: “处理原因”, “dealing_time”: “处理时间” }
dealing_person False string 处理人，当有处理意见参数时，则处理意见必须包含该参数
dealing_cause False string 处理原因，当有处理意见参数时，则处理意见必须包含该参数
dealing_time False string 处理时间，当有处理意见参数时，则处理意见必须包含该参数格式如: yyyy-MM-dd’T’HH:mm:ss.SS’Z’

请求头

名称 必填 类型 备注
Content-Type True String application/json
Api-Version False int 接口版本，0:默认版本；2:V2版本；3：V3版本
Access-Token True String 企业成员、企业授权

请求参数

名称 必填 类型 备注
名称 必填 类型 备注
state_ids True List<String> 异常状态ID列表（字符串列表）

请求示例：

{
    "state_ids": ["alarm-state-id-1", "alarm-state-id-2"]
}

返回参数说明

名称 必填 类型 备注
result True Array 返回结果
:————— :— :—– :—————
result.state_id True String 处理前异常状态id
result.record_id True String 处理后异常记录id

返回示例：

{
    "result": [{
        "state_id": "处理前异常状态id",
        "record_id": "处理后异常记录id"
    }, {
        "state_id": "处理前异常状态id",
        "record_id": "处理后异常记录id"
    }]
}
错误码 描述
- -
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题