10. 报警服务
通过 client.alarm() 进行访问。提供报警查询·统计、确认、隐藏发生·服务排除功能。所有方法均返回 ApiResult<T> — 若 isOk() 为真，则通过 getData() 获取值。报警设置(Config)管理在 client.alarmConfig() 侧。
9.1 方法一览
| 方法 | 返回类型 | HTTP | 端点 |
|---|---|---|---|
get(alarm_seq) | ApiResult<AlarmResponse> | GET | /api/v5/alarm/{alarm_seq} |
list(limit) | ApiResult<List<AlarmResponse>> | GET | /api/v5/alarm?limit=... |
active(site_id, limit) | ApiResult<List<AlarmResponse>> | GET | /api/v5/alarm/active |
search(criteria) | ApiResult<List<AlarmResponse>> | GET | /api/v5/alarm/search |
readOne(alarm_seq, read_user_id) | ApiResult<Boolean> | PUT | /api/v5/alarm/{alarm_seq}/read |
batchRead(alarm_seqs, read_user_id) | ApiResult<AlarmBatchReadResponse> | POST | /api/v5/alarm/batch/read |
readAll(user_id) | ApiResult<Boolean> | POST | /api/v5/alarm/read/all |
deliveries(alarm_seq) | ApiResult<List<AlarmDeliveryResponse>> | GET | /api/v5/alarm/{alarm_seq}/deliveries |
suppressed(kind, asset_id, design_reason, ref_id, active, limit) | ApiResult<List<AlarmSuppressedResponse>> | GET | /api/v5/alarm/suppressed |
outOfService(active) | ApiResult<List<AlarmOutOfServiceResponse>> | GET | /api/v5/alarm/out-of-service |
takeOutOfService(request) | ApiResult<AlarmOutOfServiceResponse> | POST | /api/v5/alarm/out-of-service |
returnToService(out_of_service_id, force, note) | ApiResult<AlarmReturnToServiceResponse> | POST | /api/v5/alarm/out-of-service/{out_of_service_id}/return |
readOne · batchRead · readAll 在持有令牌时可调用。由于 V5 令牌仅颁发给 ADMIN · API 角色，因此 V5 中没有控制台的 «所有确认均由 ADMIN 执行» 区分。
limit ≤ 1000。
路径中的 read 仅保留名称。服务器记录每个报警对应一次确认 — 确认。
9.2 AlarmResponse DTO
包含报警主体 + 位置(tag/opc/site) JOIN 的结果。
报警主体字段
| 字段 | 类型 | 说明 |
|---|---|---|
alarm_seq | long | 报警序列 (PK) |
alarm_config_id | String | 报警设置 ID |
priority | String | 优先级 (INFO, WARN, ERROR) |
description | String | 报警消息 |
is_on | Boolean | 当前激活状态 |
acknowledged | Boolean | 是否已确认 |
acknowledged_by | String | 确认者 — 登录 ID 或员工 ID |
acknowledged_by_type | String | 确认者种类 (USER, EMPLOYEE) |
acknowledged_at | Long | 确认时间 (毫秒) |
on_timestamp | long | 发生时间 (毫秒) |
off_timestamp | Long | 解除时间 (null = 未解除) |
on_duration | long | 持续时间 (毫秒) |
off_reason | String | 解除原因 — 报警解除原因 |
band | String | 触发频段 |
隐藏的发生不在此行。请通过 suppressed() 读取。
位置 JOIN 字段 (包含在 list 响应中)
| 字段 | 说明 |
|---|---|
tag_id, tag_name, tag_description | 标签信息 |
opc_id, opc_name | OPC 信息 |
site_id, site_name | 站点信息 |
tag_location | 资产路径字符串 (SITE > AREA > LINE > EQUIPMENT) |
9.3 报警优先级
| 代码 | 界面文本 |
|---|---|
INFO | 信息 |
WARN | 警告 |
ERROR | 严重 |
9.4 使用示例
最近报警列表
import java.util.List;
import plantpulse.api.v5.dto.response.AlarmResponse;
import plantpulse.api.v5.result.ApiResult;
ApiResult<List<AlarmResponse>> result = client.alarm().list(50);
if (result.isOk()) {
for (AlarmResponse a : result.getData()) {
System.out.printf("[%s] %s - %s (%s)%n",
a.getPriority(),
a.getSite_name(),
a.getDescription(),
a.getTag_location());
}
}
激活报警
List<AlarmResponse> active = client.alarm().active("SITE_000001", 500).getData();
System.out.println("현재 활성 알람: " + active.size() + "건");
未确认激活报警
long unacked = client.alarm().active("SITE_000001", 500).getData().stream()
.filter(a -> !Boolean.TRUE.equals(a.getAcknowledged()))
.count();
报警确认
确认者为令牌的用户。read_user_id 应设为 null — 若输入与令牌用户不同的名称，将返回 HTTP 422。若有人已先确认，则返回 HTTP 409 alarm.already_acknowledged 且维持首次记录。
ApiResult<Boolean> r = client.alarm().readOne(12345L, null);
像现场 App 这样以员工姓名确认时，请在请求头 X-PP-Performed-By 中携带员工信息。此时 acknowledged_by_type 将保留为 EMPLOYEE。
发送对象
不含已读标记的发送记录 — recipient_type · recipient_id · recipient_name · channel(CONSOLE, EMAIL, SMS, APP) · sent_at。
client.alarm().deliveries(12345L).getData().forEach(d ->
System.out.println(d.getRecipient_name() + " / " + d.getChannel()));
隐藏发生
因暂时隐藏 · 设计抑制 · 服务排除而隐藏的发生。所有过滤器均可使用 null。
| 参数 | 值 |
|---|---|
kind | SHELVED, SUPPRESSED_BY_DESIGN, OUT_OF_SERVICE |
design_reason | MAINTENANCE, REPAIR (当为 SUPPRESSED_BY_DESIGN 时) |
ref_id | 原因 ID — ALARM_SHELVE_…, 日历 ID, 维护工单 ID, ALARM_OUT_OF_SERVICE_… |
active | true = 当前开启项 |
limit | 1~1000 (默认 200) |
var hidden = client.alarm().suppressed("SUPPRESSED_BY_DESIGN", "ASSET_ID", "REPAIR", null, true, 100);
服务排除与恢复
仅 ADMIN 令牌可进行写入。无自动恢复。若恢复巡检被拒绝，则返回 HTTP 422 且维持服务排除状态。
| 拒绝原因 | HTTP | 代码 |
|---|---|---|
| 已在服务排除中 | 409 | alarm.oos.already |
| 原因值 · 备注 · 预计恢复时间错误 | 422 | alarm.oos.reason_invalid · memo_required · window_invalid |
| 恢复巡检失败 | 422 | alarm.oos.return_not_normal · return_no_value |
| 虽为恢复但无原因 | 422 | alarm.oos.note_required |
| 已恢复 | 409 | alarm.oos.already_returned |
将 force 设为 true 并提供 note，可跳过巡检直接恢复(return_check = FORCED)。原因包括 SENSOR_REMOVED, EQUIPMENT_REMOVED, CALIBRATION, MODIFICATION, OTHER。对于 OTHER 与安全·环境报警，备注为必填项。
var r = client.alarm().returnToService("ALARM_OUT_OF_SERVICE_000001", false, null);
报警设置 ID
新报警设置 ID 由服务器颁发(ALARM_CONFIG_ + 6位)。请通过 GET /api/v5/alarm/config/new-id 接收并使用；若使用自定义 ID 创建，将返回 HTTP 422 alarm.invalid.alarm_config_id。频段报警不通过 API 创建 — 由标签的报警设置(patchAlarm)创建，若尝试通过 POST /alarm/config 创建频段，将返回 HTTP 409 alarm.band.edit_on_tag。
标签的频段设置不要自定义 ID，请在 GET /api/v5/alarm/config/list/by-tag?tag_id=… 中查找 alarm_config_priority 为 BAND 的项。变更履历(/alarm/config/{alarm_config_id}/revisions)中的 alarm_config_id 在尚未设有频段设置的标签行中可能为 null。
报警系统性能
无 SDK 方法。请直接通过 V5 读取 — GET /api/v5/alarm/performance?scope_type=SITE&scope_id=…&days=7。指标请参考 报警性能。