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ロールでのみ発行されるため、コンソールの「すべて確認はADMIN」という区分はV5では別途存在しません。

limit ≤ 1000 です。

パスの read は名前のみが残ったものです。サーバーはアラーム1つに対して確認1つを記録します — 確認。

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);

現場アプリのように社員名で確認する場合は、リクエストヘッダー 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` = 現在ONのもの
`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。指標はアラーム性能を参照してください。

次のステップ

Tag サービス — patchAlarmでアラーム閾値を設定
Path サービス — アラーム発生資産のツリーパス

9.1 メソッド一覧​

9.2 AlarmResponse DTO​

アラーム本体フィールド​

位置JOINフィールド (list応答に含まれる)​

9.3 アラーム優先度​

9.4 使用例​

最近のアラーム一覧​

活性アラーム​

未確認活性アラーム​

アラーム確認​

送信先​

非表示の発生​

サービス除外と復帰​

アラーム設定ID​

アラームシステム性能​

次のステップ​