Zum Hauptinhalt springen

API-Benutzerhandbuch

Dies ist das vollständige Benutzerhandbuch für die PlantPulse Java API Client-Bibliothek (plantpulse-api). Über 13 Domain-Services können Sie auf alle Master- und Betriebsdaten der Platform zugreifen, einschließlich Standorte, Anlagen, Tags, Alarme und Arbeitsaufträge.

Bibliotheksmerkmale​

  • Standard-REST — Zweckgemäße Verwendung der GET/POST/PUT/PATCH/DELETE-Methoden
  • Typ-DTO — Alle Anfragen und Antworten werden automatisch in *RequestV5 / *ResponseV5 Klassen gemappt (kein manuelles Parsen von JSONObject erforderlich)
  • Tab-basiertes PATCH — Unterstützung von 10 Arten von Teiländerungen für Tags, wie Alarme, Metadaten, Formeln und Aggregationen
  • 13 Domain-Services — system, site, customer, employee, product, asset, opc, tag, alarm, order, calendar, path, flow
  • Sichere Standardwerte — Rückgabe von null oder einer leeren Liste im Fehlerfall (kein Werfen von Exceptions)

Für wen ist dieses Handbuch gedacht? Dies ist eine umfassende Referenz für Entwickler, die externe Systeme (MES, ERP, eigene Dashboards usw.) implementieren, welche über Java an die PlantPulse Platform angebunden werden.

Schneller Überblick​

BereichInformation
Erste SchritteBitte lesen Sie in dieser Reihenfolge: 1. Erste Schritte → 2. Domain-ID-Regeln → 3. Antwortformate und Fehlerbehandlung.
Spezifische DomainsNavigieren Sie im folgenden Inhaltsverzeichnis direkt zum entsprechenden Service (z. B. Tag, Order).
Direkte REST-AufrufeIm Vollständigen Endpunktverzeichnis finden Sie die URL- und Methoden-Mappings.
Workflow-BeispieleEnd-to-End-Szenarien finden Sie in der Sammlung integrierter Beispiele.
KI-AssistenzMCP-Server — Ermöglicht Clients wie Claude, Tags, Alarme und Anlagen in natürlicher Sprache abzufragen und Alarme zu prüfen.

Kernkonzepte​

  • Einstiegspunkt: new APIClient_V5(proto, host, port, user, token, debug) → connect()
  • 13 Services: client.system(), client.site(), client.customer(), client.employee(), client.product(), client.asset(), client.opc(), client.tag(), client.alarm(), client.order(), client.calendar(), client.path(), client.flow()
  • Rückgabe von Typ-DTOs: Alle Methoden geben Typklassen (SiteResponseV5, TagResponseV5 usw.) anstelle von JSONObject zurück
  • Sichere Standardwerte bei Fehlern: create/update/get → null, list → leere Liste, delete/exists → false, count → 0
  • Extraktion von Fehlerantworten: Statische Methoden BaseServiceV5.getErrorCode(env), getErrorMessage(env), getHttpStatus(env)
  • Domain-ID-Validierung: Der Server prüft festgelegte Präfixe für jede Domain. Die Ebene wird über asset_type statt über ein Präfix bestimmt — Domain-ID-Regeln
  • Basispfad: Alle Aufrufe erfolgen über Endpunkte unter /api/v5

Inhaltsverzeichnis​

Start und Grundregeln​

  1. Erste Schritte — Client-Erstellung und Verbindung
  2. Domain-ID-Regeln ⭐ Bitte unbedingt zuerst lesen
  3. Antwortformate und Fehlerbehandlung

Infrastruktur- und Model-Domains​

  1. System-Service — Health Check
  2. Site-Service — Standort-Master (Werk)
  3. OPC-Service — Erfassungskanäle
  4. Asset-Service — Anlagenhierarchie (Area, Line, Equipment)
  5. Tag-Service — Tag-Definition + 10 PATCH-Typen
  6. Path-Service — Anlagenpfad-Abfrage

Betriebs-Domains​

  1. Alarm-Service — Alarmereignis-Abfrage
  2. Calendar-Service — Termine (Inspektion, Stillstand usw.)
  3. Order-Service — Work-Order + Lebenszyklus

Stammdaten​

  1. Customer-Service — Kunden
  2. Employee-Service — Mitarbeiter
  3. Product-Service — Produkte

Automatisierung​

  1. Flow-Service — Abfrage von Flow / Flow-Node

Anhang​

  1. Vollständiges Endpunktverzeichnis — URL-Mapping, Instandhaltungsaufträge, CMMS-Webhooks, Alarmperformance
  2. Sammlung integrierter Beispiele — End-to-End-Workflows
  3. MCP-Server — Schnittstelle für KI-Assistenten zur Abfrage von Vor-Ort-Daten in natürlicher Sprache

Kontakt: webmaster@kopens.com