8. Tag-Service

Zugriff erfolgt über client.tag(). Ein Tag ist die Definition (Metadaten) eines Datenpunkts (Sensorwert, Zähler, Status). In V5 können detaillierte Einstellungen wie Alarm, Aggregation und Formeln über 10 spezifische PATCH-Operationen pro Tab sicher und teilweise aktualisiert werden.

ID-Regel: Präfix TAG_ ist erforderlich. Weitere Informationen finden Sie unter Domain-ID-Regeln.

8.1 Methodenübersicht

CRUD

Methode	Rückgabetyp	HTTP	Endpunkt
create(TagRequestV5)	TagResponseV5 oder null	POST	/api/v5/tag
update(tag_id, TagRequestV5)	TagResponseV5 oder null	PUT	/api/v5/tag/{id}
delete(tag_id)	boolean	DELETE	/api/v5/tag/{id}
get(tag_id)	TagResponseV5 oder null	GET	/api/v5/tag/{id}
exists(tag_id)	boolean	GET	/api/v5/tag/{id}/exists

Liste / Count

Methode	Rückgabetyp	HTTP	Endpunkt
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()	long	GET	/api/v5/tag/count
countBySite(site_id)	long	GET	/api/v5/tag/count?site_id=...
countByOpc(opc_id)	long	GET	/api/v5/tag/count?opc_id=...
countByAsset(asset_id)	long	GET	/api/v5/tag/count?asset_id=...

PATCH — Teilaktualisierung pro Tab (Kernfunktion V5)

Die 10 PATCH-Typen folgen der Regel null-Feld = keine Änderung (Verarbeitung in der Server-DAO gemäß COALESCE). Einige PATCH-Operationen führen auf dem Server automatisch eine Neuverteilung von CEP/EQL durch.

Methode	HTTP	Endpunkt	Seiteneffekt
patchBasic(id, TagBasicPatchRequestV5)	PATCH	/api/v5/tag/{id}/basic	—
patchAlarm(id, TagAlarmPatchRequestV5)	PATCH	/api/v5/tag/{id}/alarm	CEP/EQL-Neuverteilung
patchMetadata(id, TagMetadataPatchRequestV5)	PATCH	/api/v5/tag/{id}/metadata	—
patchCalculation(id, TagCalculationPatchRequestV5)	PATCH	/api/v5/tag/{id}/calculation	Neuaufruf von deployCalculation
patchSampling(id, TagSamplingPatchRequestV5)	PATCH	/api/v5/tag/{id}/sampling	—
patchAggregation(id, TagAggregationPatchRequestV5)	PATCH	/api/v5/tag/{id}/aggregation	Neuaufruf von 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 (Vollständige Registrierung/Bearbeitung)

Feld	Typ	Beschreibung
tag_id	String	Tag-ID (PK, TAG_ erforderlich)
tag_name	String	Anzeigename
opc_id	String	Zugehörige OPC (FK)
site_id	String	Zugehöriger Standort
linked_asset_id	String	Verknüpfte Anlage (Equipment)
java_type	String	Wert-Datentyp — Double, Float, Int, Long, Short, Boolean, String, Date
unit	String	Einheit (z. B. ℃, RPM, kPa)
source_type	String	(Nur Antwort) Quelltyp — abgeleitet aus dem Verbindungsprotokoll des Tags (OPC/PLC/MODBUS/DATABASE/MESSAGING/API/SYSTEM)
description	String	Beschreibung

8.3 PATCH DTO Felder (pro Tab)

TagBasicPatchRequestV5 (Basis)

Feld	Beschreibung
tag_name	Anzeigename
java_type	Datentyp
description	Beschreibung

TagMetadataPatchRequestV5 (Metadaten)

Feld	Beschreibung
tag_type	Tag-Typ
importance	Priorität (1~10)
use_metric	Metrik-Verwendung
rate	Empfangszyklus (ms) — Dokumentationswert. Das tatsächliche Polling-Intervall wird in den Verbindungseinstellungen festgelegt
rw	Lesen/Schreiben (R/W/RW)
alias_name	Alias
min_value / max_value	Skalierungsbasis für Gauge-Charts — Werte werden nicht validiert
display_format	UI-Anzeigeformat
unit	Einheit
number_round / number_scale	Rundung / Dezimalstellen
io_address / source_tag_name	I/O-Adresse · Original-Tagname
lat / lng	Breitengrad / Längengrad

TagAlarmPatchRequestV5 (Alarm)

Feld	Beschreibung
trip_hi, hi_hi, hi, lo, lo_lo, trip_lo	Schwellenwerte (6 Stufen)
bool_true, bool_true_priority, bool_true_message	Boolean TRUE Alarm
bool_false, bool_false_priority, bool_false_message	Boolean FALSE Alarm
band_message	Normalband-Nachricht
duplicate_check_minutes	Zeitintervall zur Unterdrückung redundanter Alarme (Minuten)
user_defined_alarm_class	Benutzerdefinierte Klasse
use_alarm	Alarm-Verwendung (Y/N)
recieve_me, recieve_others	Empfang durch Eigen/Andere
send_email, send_sms	E-Mail/SMS-Versand

TagCalculationPatchRequestV5 (Formel)

Feld	Beschreibung
calculation_eql	EQL-Ausdruck
use_calculation	Verwendung (Y/N)

TagSamplingPatchRequestV5 (Sampling)

Feld	Beschreibung
use_sampling	Verwendung (Y/N)

TagAggregationPatchRequestV5 (Aggregation)

Feld	Beschreibung
use_aggregation	Verwendung
aggregation_1_minutes ~ aggregation_1_hours	Aktivierungsflags für 5 verschiedene Zyklen

TagAiPatchRequestV5 (KI-Anomalieerkennung)

Feld	Beschreibung
use_target	Ziel der multivariaten Korrelationsanalyse (Y/N) — Analyse wird erst aktiviert, wenn 2 oder mehr Tags einer Anlage zugewiesen sind
use_category	Verzweigungspalte zur Aufteilung multivariater Daten (Y/N) — z. B. Rezept, Anlagenmodus, Betrieb

TagPublishPatchRequestV5 (Veröffentlichung)

Feld	Beschreibung
publish_mqtt	MQTT-Veröffentlichung (Y/N)
publish_kafka	Kafka-Veröffentlichung (Y/N) — Damit das OPC-UA-Server-Plugin Daten empfangen kann, muss dies Y sein

TagAttributePatchRequestV5 (Notiz)

Feld	Beschreibung
note	Freiform-Memo

TagLinkPatchRequestV5 (Anlagen-Mapping)

Feld	Beschreibung
linked_asset_id	ID der verknüpften Anlage. Leere Zeichenfolge = Mapping aufheben

8.4 Anwendungsbeispiele

Tag-Erstellung (OPC-Verbindungstag)

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

Einzelabfrage / Existenzprüfung

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

Liste nach Standort / OPC / Asset

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

Count

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

Vollständige Bearbeitung (PUT)

Bei erneuter Übermittlung aller Felder:

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

Teilaktualisierung — patchBasic

Nur Name und Beschreibung ändern:

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

Teilaktualisierung — patchAlarm

Einstellung der Alarm-Schwellenwerte (CEP/EQL-Neuverteilung auf dem Server):

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

Teilaktualisierung — patchMetadata

Änderung von Alias und Anzeigeformat:

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

Teilaktualisierung — patchCalculation

Zuweisung einer EQL-Formel (Server ruft deployCalculation erneut auf):

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

Teilaktualisierung — patchAggregation

Aktivierung der Aggregation für 5 Zyklen (deployAggregation wird erneut aufgerufen):

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

Teilaktualisierung — patchPublish

Umschalten der MQTT/Kafka-Veröffentlichung:

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

Teilaktualisierung — patchLink (Anlagen-Mapping)

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

Löschen

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

8.5 Nutzungsszenarien

Szenario — Automatische Klassifizierung und Stapeleinstellung von Tags einer neuen Linie

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

Szenario — Gleichzeitige Aktivierung von Aggregation und Veröffentlichung

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

Nächste Schritte

• Alarm-Service — Abfrage von Alarm-Events
• Path-Service — Anlagenpfad des Tags