跳到主要内容

8. 标签服务

通过 client.tag() 进行访问。标签是数据点（传感器值、计数器、状态）的定义（元数据）。在 V5 版本中，可以通过 10 种分标签页 PATCH 方式，安全地对报警、集计、计算等详细设置进行部分修改。

ID 规则：必须带有 TAG_ 前缀。详情请参考 域名 ID 规则。

8.1 方法一览​

CRUD​

方法返回类型HTTP端点
create(TagRequestV5)TagResponseV5 或 nullPOST/api/v5/tag
update(tag_id, TagRequestV5)TagResponseV5 或 nullPUT/api/v5/tag/{id}
delete(tag_id)booleanDELETE/api/v5/tag/{id}
get(tag_id)TagResponseV5 或 nullGET/api/v5/tag/{id}
exists(tag_id)booleanGET/api/v5/tag/{id}/exists

列表 / 计数​

方法返回类型HTTP端点
list()List<TagResponseV5>GET/api/v5/tag
listBySite(site_id)List<TagResponseV5>GET/api/v5/tag?site_id=...
listByOpc(opc_id)List<TagResponseV5>GET/api/v5/tag?opc_id=...
listByAsset(asset_id)List<TagResponseV5>GET/api/v5/tag?asset_id=...
count()longGET/api/v5/tag/count
countBySite(site_id)longGET/api/v5/tag/count?site_id=...
countByOpc(opc_id)longGET/api/v5/tag/count?opc_id=...
countByAsset(asset_id)longGET/api/v5/tag/count?asset_id=...

PATCH — 分标签页部分修改 (V5 核心功能)​

10 种 PATCH 遵循 null 字段 = 不变更 规则（在服务器 DAO 中由 COALESCE 处理）。部分 PATCH 在服务器端会自动执行 CEP/EQL 的再部署。

方法HTTP端点副作用
patchBasic(id, TagBasicPatchRequestV5)PATCH/api/v5/tag/{id}/basic—
patchAlarm(id, TagAlarmPatchRequestV5)PATCH/api/v5/tag/{id}/alarmCEP/EQL 再部署
patchMetadata(id, TagMetadataPatchRequestV5)PATCH/api/v5/tag/{id}/metadata—
patchCalculation(id, TagCalculationPatchRequestV5)PATCH/api/v5/tag/{id}/calculation重新调用 deployCalculation
patchSampling(id, TagSamplingPatchRequestV5)PATCH/api/v5/tag/{id}/sampling—
patchAggregation(id, TagAggregationPatchRequestV5)PATCH/api/v5/tag/{id}/aggregation重新调用 deployAggregation
patchAi(id, TagAiPatchRequestV5)PATCH/api/v5/tag/{id}/ai—
patchPublish(id, TagPublishPatchRequestV5)PATCH/api/v5/tag/{id}/publish—
patchAttribute(id, TagAttributePatchRequestV5)PATCH/api/v5/tag/{id}/attribute—
patchLink(id, TagLinkPatchRequestV5)PATCH/api/v5/tag/{id}/link—

8.2 TagRequestV5 / TagResponseV5 (用于整体注册·修改)​

字段类型说明
tag_idString标签 ID (PK, TAG_ 必填)
tag_nameString显示名称
opc_idString所属 OPC (FK)
site_idString所属站点
linked_asset_idString连接的设备(Equipment)
java_typeString值数据类型 — Double, Float, Int, Long, Short, Boolean, String, Date
unitString单位 (例: ℃, RPM, kPa)
source_typeString(仅响应) 来源类型 — 派生自标签的连接协议 (OPC/PLC/MODBUS/DATABASE/MESSAGING/API/SYSTEM)
descriptionString说明

8.3 PATCH DTO 字段 (分标签页)​

TagBasicPatchRequestV5 (基本)​

字段说明
tag_name显示名称
java_type数据类型
description说明

TagMetadataPatchRequestV5 (元数据)​

字段说明
tag_type标签类型
importance重要度 (1~10)
use_metric是否使用指标
rate接收周期 (ms) — 记录用。实际轮询间隔在连接设置中定义
rw读/写 (R/W/RW)
alias_name别名
min_value / max_value仪表盘刻度基准 — 不验证数值
display_formatUI 显示格式
unit单位
number_round / number_scale四舍五入 / 小数点
io_address / source_tag_nameI/O 地址·原始标签名
lat / lng经纬度

TagAlarmPatchRequestV5 (报警)​

字段说明
trip_hi, hi_hi, hi, lo, lo_lo, trip_lo阈值 (6 级)
bool_true, bool_true_priority, bool_true_message布尔 TRUE 报警
bool_false, bool_false_priority, bool_false_message布尔 FALSE 报警
band_message正常区间消息
duplicate_check_minutes重复报警屏蔽分钟数
user_defined_alarm_class用户定义类
use_alarm是否使用报警 (Y/N)
recieve_me, recieve_others本人/他人接收
send_email, send_sms电子邮件/SMS 发送

TagCalculationPatchRequestV5 (计算)​

字段说明
calculation_eqlEQL 表达式
use_calculation是否使用 (Y/N)

TagSamplingPatchRequestV5 (采样)​

字段说明
use_sampling是否使用 (Y/N)

TagAggregationPatchRequestV5 (集计)​

字段说明
use_aggregation是否使用
aggregation_1_minutes ~ aggregation_1_hours5 种周期激活标志

TagAiPatchRequestV5 (AI 异常诊断)​

字段说明
use_target多变量相关分析 对象 (Y/N) — 单个设备必须有 2 个以上标签才激活分析
use_category划分多变量数据的 分支列 (Y/N) — 配方·设备模式·运行等

TagPublishPatchRequestV5 (发布)​

字段说明
publish_mqttMQTT 发布 (Y/N)
publish_kafkaKafka 发布 (Y/N) — OPC-UA 服务器插件若要接收数据，必须为 Y

TagAttributePatchRequestV5 (备注)​

字段说明
note自由格式备注

TagLinkPatchRequestV5 (设备映射)​

字段说明
linked_asset_id连接设备 ID。空字符串 = 解除映射

8.4 使用示例​

标签创建 (OPC 连接标签)​

import plantpulse.api.v5.dto.request.TagRequestV5;
import plantpulse.api.v5.dto.response.TagResponseV5;

TagRequestV5 req = new TagRequestV5();
req.setTag_id("TAG_EDGE_00303_90007");
req.setTag_name("Spindle RPM");
req.setOpc_id("OPC_EDGE_00303");
req.setSite_id("SITE_DJ");
req.setLinked_asset_id("EQUIPMENT_000001");
req.setJava_type("Double");
req.setUnit("RPM");
req.setDescription("Spindle 회전수");

TagResponseV5 created = client.tag().create(req);

单条查询 / 存在确认​

TagResponseV5 tag = client.tag().get("TAG_EDGE_00303_90007");
if (tag != null) {
    System.out.println(tag.getTag_name() + " (" + tag.getUnit() + ")");
}

boolean exists = client.tag().exists("TAG_EDGE_00303_90007");

按站点 / OPC / 资产查询列表​

List<TagResponseV5> siteTags  = client.tag().listBySite("SITE_DJ");
List<TagResponseV5> opcTags   = client.tag().listByOpc("OPC_PLC_L1_001");
List<TagResponseV5> assetTags = client.tag().listByAsset("EQUIPMENT_000001");

计数​

long total       = client.tag().count();
long siteTotal   = client.tag().countBySite("SITE_DJ");
long opcTotal    = client.tag().countByOpc("OPC_PLC_L1_001");
long assetTotal  = client.tag().countByAsset("EQUIPMENT_000001");

整体修改 (PUT)​

重新发送所有字段时：

TagRequestV5 update = new TagRequestV5();
update.setTag_id("TAG_EDGE_00303_90007");
update.setTag_name("Spindle RPM (변경됨)");
update.setOpc_id("OPC_EDGE_00303");
update.setSite_id("SITE_DJ");
update.setJava_type("Double");
update.setUnit("RPM");
// ... 모든 필드 ...
client.tag().update("TAG_EDGE_00303_90007", update);

部分修改 — patchBasic​

仅更改名称和说明：

import plantpulse.api.v5.dto.request.TagBasicPatchRequestV5;

TagBasicPatchRequestV5 patch = new TagBasicPatchRequestV5();
patch.setTag_name("Spindle RPM (보정 후)");
patch.setDescription("2026-05-14 보정 적용");
// java_type 은 null 로 두면 변경 안 함
client.tag().patchBasic("TAG_EDGE_00303_90007", patch);

部分修改 — patchAlarm​

设置报警阈值 (服务器端执行 CEP/EQL 再部署)：

import plantpulse.api.v5.dto.request.TagAlarmPatchRequestV5;

TagAlarmPatchRequestV5 alarm = new TagAlarmPatchRequestV5();
alarm.setUse_alarm("Y");
alarm.setLo_lo("0");
alarm.setLo("10");
alarm.setHi("80");
alarm.setHi_hi("95");
alarm.setTrip_hi("100");
alarm.setDuplicate_check_minutes(5);
alarm.setSend_email("Y");
client.tag().patchAlarm("TAG_EDGE_00303_90007", alarm);

部分修改 — patchMetadata​

更改别名和显示格式：

import plantpulse.api.v5.dto.request.TagMetadataPatchRequestV5;

TagMetadataPatchRequestV5 meta = new TagMetadataPatchRequestV5();
meta.setAlias_name("HMI_TAG_RPM_01");
meta.setDisplay_format("#,##0");
meta.setNumber_scale(0);
meta.setImportance(8);
client.tag().patchMetadata("TAG_EDGE_00303_90007", meta);

部分修改 — patchCalculation​

附加 EQL 计算公式 (服务器端重新调用 deployCalculation)：

import plantpulse.api.v5.dto.request.TagCalculationPatchRequestV5;

TagCalculationPatchRequestV5 calc = new TagCalculationPatchRequestV5();
calc.setUse_calculation("Y");
calc.setCalculation_eql("VAL('TAG_RAW_RPM') * 60 / 1000");   // 가상의 EQL
client.tag().patchCalculation("TAG_EDGE_00303_90007", calc);

部分修改 — patchAggregation​

激活 5 种周期集计 (重新调用 deployAggregation)：

import plantpulse.api.v5.dto.request.TagAggregationPatchRequestV5;

TagAggregationPatchRequestV5 agg = new TagAggregationPatchRequestV5();
agg.setUse_aggregation("Y");
agg.setAggregation_1_minutes("Y");
agg.setAggregation_5_minutes("Y");
agg.setAggregation_10_minutes("Y");
agg.setAggregation_30_minutes("N");
agg.setAggregation_1_hours("Y");
client.tag().patchAggregation("TAG_EDGE_00303_90007", agg);

部分修改 — patchPublish​

MQTT/Kafka 发布切换：

import plantpulse.api.v5.dto.request.TagPublishPatchRequestV5;

TagPublishPatchRequestV5 pub = new TagPublishPatchRequestV5();
pub.setPublish_mqtt("Y");
pub.setPublish_kafka("N");
client.tag().patchPublish("TAG_EDGE_00303_90007", pub);

部分修改 — patchLink (资产映射)​

import plantpulse.api.v5.dto.request.TagLinkPatchRequestV5;

// 자산에 연결
TagLinkPatchRequestV5 link = new TagLinkPatchRequestV5();
link.setLinked_asset_id("EQUIPMENT_000001");
client.tag().patchLink("TAG_EDGE_00303_90007", link);

// 매핑 해제 — 빈 문자열
TagLinkPatchRequestV5 unlink = new TagLinkPatchRequestV5();
unlink.setLinked_asset_id("");
client.tag().patchLink("TAG_EDGE_00303_90007", unlink);

删除​

boolean ok = client.tag().delete("TAG_EDGE_00303_90007");

8.5 应用场景​

场景 — 新生产线标签自动分类后批量设置​

// 1) 자동 등록된 태그 목록 (OPC 연결 직후)
List<TagResponseV5> tags = client.tag().listByOpc("OPC_PLC_L2_001");

// 2) 이름 패턴으로 자산 자동 연결 + 알람 일괄 설정
for (TagResponseV5 t : tags) {
    String name = t.getTag_name();

    // 자산 매핑
    TagLinkPatchRequestV5 link = new TagLinkPatchRequestV5();
    if (name.contains("CNC1")) {
        link.setLinked_asset_id("EQUIPMENT_CNC1");
    } else if (name.contains("CNC2")) {
        link.setLinked_asset_id("EQUIPMENT_CNC2");
    } else {
        continue;
    }
    client.tag().patchLink(t.getTag_id(), link);

    // 온도 태그는 알람 임계치 자동 설정
    if (name.endsWith("_TEMP")) {
        TagAlarmPatchRequestV5 alarm = new TagAlarmPatchRequestV5();
        alarm.setUse_alarm("Y");
        alarm.setHi("80");
        alarm.setHi_hi("95");
        client.tag().patchAlarm(t.getTag_id(), alarm);
    }
}

场景 — 同时激活集计与发布​

String tagId = "TAG_EDGE_00303_90007";

TagAggregationPatchRequestV5 agg = new TagAggregationPatchRequestV5();
agg.setUse_aggregation("Y");
agg.setAggregation_1_minutes("Y");
agg.setAggregation_1_hours("Y");
client.tag().patchAggregation(tagId, agg);

TagPublishPatchRequestV5 pub = new TagPublishPatchRequestV5();
pub.setPublish_mqtt("Y");
client.tag().patchPublish(tagId, pub);

下一步​