Zum Hauptinhalt springen

1. Erste Schritte

Diese Anleitung führt Sie durch die Schritte bis zum ersten Aufruf mit dem V5 Java API Client.

Schnellstart (60 Sekunden)​

Die 3 benötigten Angaben

PunktWertWoher
Serveradressehttp://<server-ip>:80 (mit TLS https://<server-ip>:443)REST API Endpunkt. :7443 ist ausschließlich der Verwaltungskonsole vorbehalten — verwenden Sie für die API 80/443
Konto-IDz. B.: apiBenutzerkonto für API-Aufrufe
TokenUUID-FormatIn der Konsole unter Sicherheitsverwaltung → API-Authentifizierungstoken (/token/index) für dieses Konto ausstellen → Sicherheitseinstellungen · Sicherheitsverwaltung

Mit diesen drei Werten gelingt der erste Aufruf mit dem folgenden einzelnen Block.

import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;

try (APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", "<issued-token>", false)) {
    client.connect();                                       // 인증
    System.out.println(client.system().ping().isPing());    // → true
    for (SiteResponseV5 s : client.site().list())           // 사이트 목록
        System.out.println(s.getSite_id() + " — " + s.getSite_name());
}

Wenn dieser Block true und die Standortliste ausgibt, ist alles bereit. Die Abschnitte 1.1 bis 1.7 erläutern die einzelnen Schritte im Detail.

1.1 Abhängigkeit hinzufügen​

Fügen Sie die JAR-Datei einfach dem Klassenpfad hinzu.

# 빌드 (Gradle + Java 21)
cd plantpulse-api
./gradlew build

Die Artefakte werden unter target/ erzeugt.

DateiVerwendung
target/plantpulse-api.jarZur Integration in ein bestehendes Projekt samt Abhängigkeiten

1.2 Client erstellen​

Die Optionen werden dem Konstruktor APIClient_V5 direkt übergeben.

import plantpulse.api.v5.APIClient_V5;

APIClient_V5 client = new APIClient_V5(
        "HTTPS",                                       // 프로토콜: "HTTP" 또는 "HTTPS"
        "100.68.69.41",                                // host
        443,                                           // port (REST API: 80=HTTP, 443=HTTPS)
        "api",                                         // user_id
        "19ba7a54-1132-49f2-967e-3c6f5cd989a0",        // token (api_key 발급용)
        false);                                        // debug

client.connect();          // 인증 + HTTP 클라이언트 초기화

// ... API 호출 ...

client.close();            // 종료

Konstruktorparameter​

ParameterTypBeschreibung
protocolString"HTTP" oder "HTTPS"
hostStringServer-Host oder IP
portintServer-Port
user_idStringKonto-ID für die Authentifizierung
tokenStringAusgestelltes Token (UUID-Format)
debugbooleanDebug-Log für HTTP-Requests und -Responses

Authentifizierungsablauf: Beim Aufruf von connect() wird intern über user_id + token ein api_key bezogen, der anschließend bei allen Aufrufen automatisch im Header mitgesendet wird. Ein manueller Eingriff ist nicht erforderlich.

1.3 Erster API-Aufruf — ping & Standortliste​

import java.util.List;
import plantpulse.api.v5.APIClient_V5;
import plantpulse.api.v5.dto.response.SiteResponseV5;
import plantpulse.api.v5.dto.response.SystemPingResponseV5;

public class FirstCall {
    public static void main(String[] args) throws Exception {

        try (APIClient_V5 client = new APIClient_V5(
                "HTTP", "100.68.69.41", 80, "api",
                "19ba7a54-1132-49f2-967e-3c6f5cd989a0", false)) {

            client.connect();

            // 1) 서버 헬스체크
            SystemPingResponseV5 ping = client.system().ping();
            System.out.println("Server alive: " + ping.isPing()
                + " (v" + ping.getVersion() + ")");

            // 2) 사이트 목록 (typed DTO 리스트)
            List<SiteResponseV5> sites = client.site().list();
            for (SiteResponseV5 s : sites) {
                System.out.println(s.getSite_id() + " — " + s.getSite_name());
            }
        }
    }
}

Ausführungsergebnis:

Server alive: true (v5.0)
SITE_00001 — 대전 1공장
SITE_00002 — 천안 2공장

1.4 try-with-resources-Muster​

APIClient_V5 implementiert AutoCloseable. Die Verwendung von try-with-resources wird empfohlen.

try (APIClient_V5 client = new APIClient_V5(proto, host, port, user, token, false)) {
    client.connect();
    // ... API 호출 ...
}
// close() 자동 호출 — HTTP 커넥션 정리

1.5 Die 13 Services auf einen Blick​

Unmittelbar nach connect() sind über die folgenden Service-Methoden alle Domänen erreichbar (Lazy-Initialisierung).

client.system()    // 헬스체크
client.site()      // 사이트(공장)
client.customer()  // 고객
client.employee()  // 직원
client.product()   // 제품
client.asset()     // 자산 계층 (Area → Line → Equipment)
client.opc()       // OPC 데이터 채널
client.tag()       // 태그(데이터 포인트)
client.alarm()     // 알람
client.order()     // 작업지시
client.calendar()  // 일정
client.path()      // 자산 경로
client.flow()      // Flow / Flow Node

1.6 Standardmuster der V5-Methodensignaturen​

Alle Domänen-Services folgen einem einheitlichen Methodenmuster. Nur der Domänenname unterscheidet sich, die Verwendung ist identisch.

MusterRückgabetypRückgabewert bei FehlerBeschreibung
create(req)*ResponseV5nullAnlegen
update(id, req)*ResponseV5nullVollständige Änderung
delete(id)booleanfalseLöschen
get(id)*ResponseV5nullEinzelabfrage
list()List<*ResponseV5>Leere ListeGesamtliste
exists(id)booleanfalseExistenzprüfung
count()long0Anzahl

⚠️ Es werden keine Exceptions geworfen. Kommunikationsfehler oder ERROR-Antworten des Servers werden als die oben genannten sicheren Standardwerte zurückgegeben. Die Fehlerursache entnehmen Sie dem Log oder BaseServiceV5.getErrorCode(env). Details siehe Antwortformat und Fehlerbehandlung.

1.7 Debug-Modus​

Wird das letzte Konstruktorargument auf true gesetzt, werden HTTP-Requests und -Responses auf der Konsole ausgegeben.

APIClient_V5 client = new APIClient_V5(
        "HTTP", "100.68.69.41", 80, "api", TOKEN, true);  // debug=true

Beispielausgabe:

[V5] GET https://server/api/v5/site headers={api_key=ab****cd}
[V5] response: 200 {"_status":"OK","data":[{"site_id":"SITE_00001",...}]}

Nächste Schritte​