1. Inhaltsverzeichnis
2. Wortlaut
Physikalisches Gerät
Ein physisches Gerät wird durch eine Seriennummer identifiziert und hat 1 bis n Kanäle.
Jeder Kanal kann unabhängig konfiguriert werden (z.B. eigenes Messintervall) und hat einen oder mehrere Sensoren, die 1 bis m verschiedene Sensorwerte liefern können.
Zum Beispiel;
ein Wert: Temperatur (für einen Temperatursensor)
zwei Tupel von: relative Feuchte und Temperatur (für einen rH-Sensor)
Drei-Tupel von: status, #changes, relative on (für einen DI-Sensor)
Virtuelle Darstellung von Alarmen
In elproCLOUD haben wir eine Eins-zu-Eins-Zuordnung von Gerät und Kanal.
Für die Werte eines Sensors haben wir eine eins-zu-n-Zuordnung zu virtuellen Sensoren.
Ein virtueller Sensor wird für jede Konfiguration eines realen Sensors erstellt und dient dazu, verschiedene Arten von Alarmen mit demselben Sensorwert zu verbinden.
3. Kommunikationskonzept elproCLOUD <> externe Anwendung
REST-API für die Abfrage von Daten
| Inc drawio | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Die Kommunikation zwischen der elproCLOUD und der externen Anwendung wird über eine REST-API realisiert 1<=2 und 4=>3. Die Schnittstelle 1<=2 wird verwendet, um Informationen von externen Anwendungen von der elproCLOUD anzufordern. Die Schnittstelle 4=>3 liefert die Informationen, die von der externen Anwendung angefordert wurden.
Die Kommunikation läuft in der Regel in der folgenden Reihenfolge ab:
| Inc drawio | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Das Gerät sendet seine Daten und Ereignisse in einem definierten festen Intervall an die elproCLOUD.
Es gibt Mechanismen, bei denen das Gerät seine Daten direkt an die elproCLOUD sendet und nicht auf das nächste Kommunikationsintervall wartet.
Die Kunden-App fordert die Daten von elproCLOUD über die REST-API bei Bedarf oder in einem selbst definierten Intervall an. Dieses Intervall sollte auf der Grundlage einer Risikoeinschätzung festgelegt werden.
4. Version der REST-API
Für die REST-API ist ein Versionierungsmechanismus implementiert.
Die Versionierung umfasst eine Major- und eine Minor-Nummer.
Major-Nummern stellen eine Schnittstelle zur elproCLOUD zur Verfügung und werden erhöht, wenn die Funktionalität der Schnittstelle wesentlich verändert wird. Minor-Nummern werden erhöht, wenn der zurückgegebenen Datenstruktur Informationen hinzugefügt werden.
Die wichtigsten REST-API-Versionen werden weiterhin über die URL verfügbar sein.
elprocloud_request_url/api/v1/... (für v1 der REST-API)
elprocloud_request_url/api/v2/... (für v2 der REST-API)
Major.Minor Versionierung wird in der zurückgegebenen json-Antwort enthalten sein.
| Code Block | ||
|---|---|---|
| ||
{
"version": "<Major.Minor>",
} |
5. Allgemein für alle Anfragen
5.1 Art des Sicherheitssystems
Zunächst richtet ELPRO einen API-Schlüssel für einen bestimmten Benutzer einer Organisation ein.
Geben Sie Ihren API-Autorisierungscode im Anfrage-Header als Schlüssel und Wert an:
EAPI-ELCLV2 | 123a45b67_SAMPLE_f12345ab6c789d0 |
Im Falle eines Fehlens oder einer Nichtübereinstimmung wird eine Fehlermeldung mit dem HTTP-Status 401 "Nicht autorisiert" zurückgegeben.
5.2 Benutzerumfang
Die abgerufenen Daten fallen in den Zuständigkeitsbereich der Organisation des authentifizierten API-Benutzers. Sie werden mit dem HTTP-Statuscode 200 (Erfolg) zurückgegeben.
5.3 Http-Fehler-Codes
400 Bad Request | z.B. fehlender obligatorischer Parameter |
401 Unauthorized | Ungültiger oder fehlender API-Schlüssel |
404 Ressource not found | Ungültige Seriennummer oder ID |
406 Not Acceptable | Accept Header sollte nur application/json lauten |
410 License exhausted | Anzahl der verbrauchten Abfragen oder Datentransfers |
500 Server Error | Unerwartete interne Ausnahme |
503 Service Temporarily Unavailable | Dienst aufgrund von Wartung oder Update nicht verfügbar |
5.4 Schema für Anfrage und Antwort
Beachten Sie, dass jedes von der API akzeptierte und zurückgegebene JSON dem JSON-Standard entsprechen muss, wie er in der ECMA-404 Standard mit den folgenden Änderungen.
JSON-Eigenschaftsnamen sind unabhängig von der Groß-/Kleinschreibung und es kann keine Garantie für die Groß-/Kleinschreibung von Namen gegeben werden, die von der API zurückgegeben werden. Das bedeutet, dass kein Unterschied zwischen Groß- und Kleinbuchstaben in Eigenschaftsnamen gemacht wird.
Die relative Reihenfolge der JSON-Namen in Antworten kann nicht garantiert werden. Das bedeutet, dass Sie sich beim Parsen und Verarbeiten von Antworten nicht auf die Reihenfolge der Eigenschaften in den Antworten verlassen sollten.
6 Geräte
Die Darstellung der Geräte wird durch ihre eindeutigen Seriennummern identifiziert. Diese Datenobjekte enthalten eine Untergruppe von Informationen sowie eine Liste von SensorIds für Datensenken, die Messdaten enthalten. Mit dem angegebenen API-Schlüssel werden der Benutzer und die verknüpften Geräte identifiziert.
7 Sensoren
Sensoren stellen eine Datensenke dar, in der die Daten eines Runs gespeichert werden. Jeder Sensor hat ein Start- und Enddatum. Die Sensor-ID ist eindeutig und mit Messwerten, Positionen und Ereignisdaten verknüpft.
Sobald das Gerät neu gestartet wird, wird eine neue Sensordatensenke mit einer neuen ID erstellt.
8 Öffentliche Endpunkte und technische Spezifikation
Endpunkt Production Base Url API https://apibridge.elpro.cloud
Für Entwickler die technische Spezifikation von OpenAPI als Swagger UI https://apibridge.elpro.cloud/swagger