Virtuelle Darstellung mit alarmierender

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

Die Kommunikation zwischen der elproCLOUD und der externen Anwendung wird über eine REST-API realisiert 1<=2 and und 4=>3. The interface Die Schnittstelle 1<=2 is used to request information by external application from the elproCLOUD. The interface 4=>3 will provide information that was requested by the external application.

The communication runs typically in the following sequence:

Image Removed

The device will send its data and occurences in defined fix intevall to the elproCLOUD.
There are mechanismens, where the device will send its data directly to the elproCLOUD and will not wait for the next communication interval.

The customer app requests the data from elproCLOUD via the REST-API on demand or in a self defined intervall. This interval should be defined based on a risk-assesment.

4. Version of the REST-API

For the REST-API a versioning mechanism is implemented.

The versioning includes a Major and a Minor number.

Major numbers will provide an interface to the elproCLOUD and will be increased, if the functionality of the interface is dramatically changed. Minor numbers will be increased, if information is added to the returned data structure. 

Major REST-API Versions will be still available via the URL 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:

Image Added

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 drastisch 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/…    ... (for für v1 of the der REST-API)

• elprocloud_request_url/api/v2/…    ... (for für v2 of the der REST-API)

 Major Major.Minor Versioning will be included in the returned json responseVersionierung wird in der zurückgegebenen json-Antwort enthalten sein.

{

"version": "<Major.Minor>",

}

5.

Allgemein für alle Anfragen

5.1

Initially, ELPRO sets up an API key for a dedicated user of an organization.

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: 

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 (SuccessErfolg) zurückgegeben.

5.3 Http

-Fehler-Codes

5.4 Request and Response Schema

Note that any JSON accepted and returned by the API must follow the JSON standard as defined in the ECMA-404 standard with the following amendments.

1. JSON property names are case invariant and no guarantee can be made regarding the casing of names, which are returned by the API. This means that no difference is made between uppercase and lowercase letters in property names.

2. The relative order of JSON names in responses is not be guaranteed. This means that the order of properties in the responses should not be depended on, when parsing and processing responses.

6 Devices

Representation of devices are identified by their unique serial numbers. These data objects carry a subset of information, as well as a list of SensorIds for data sinks, which contain measurement data. With the given API key, the user and the linked devices are identified.

7 Sensors

Sensors represent a data sink holding the data of a run. Each sensor has a start and end date. Its sensor id is unique and links to measurements, geolocation and occurrence data.

Once the Device is restarted, a new sensor data sink will be created with a new id.

8 Public Endpoints and Technical Specification

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.

1. 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.

2. 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 Laufs gespeichert werden. Jeder Sensor hat ein Start- und Enddatum. Seine Sensor-ID ist eindeutig und mit Messungen, Geolocation 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

• For Developers the OpenAPI technical specification as Für Entwickler die technische Spezifikation von OpenAPI als Swagger UI https://apibridge.elpro.cloud/swagger