...

Projekt/Produkt

...

ELPRO CLOUD

...

Ausgabe

...

Grundlegende REST-API für elproCLOUD

...

Version

...

1.0.0

1. Inhaltsverzeichnis

• 1. Inhaltsverzeichnis

• 2. Wortlaut

• 3. Kommunikationskonzept elproCLOUD <> externe Anwendung

  • REST-API für die Abfrage von Daten

• 4. Version der REST-API

• 5. Allgemein für alle Anfragen

  • 5.1 Art des Sicherheitssystems

  • 5.2 Benutzerumfang

  • 5.3 Http-Fehler-Codes

  • 5.4 Schema für Anfrage und Antwort

• 6 Geräte

• 7 Sensoren

• 8 Öffentliche Endpunkte und technische Spezifikation

...

1. Inhaltsverzeichnis

...

2. Allgemein

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

2.2 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 verknüpft mit Messungen, Geolocation und Ereignisdaten.

Sobald das Gerät neu gestartet wird, wird eine neue Sensordatensenke mit einer neuen ID erstellt.

2.3 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 mit

...

Alarmierung

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

...

2.4 Datenformat

Beachten Sie, dass jedes JSON, das von der API akzeptiert und zurückgegeben wird, dem JSON-Standard entsprechen muss, wie er in der ECMA-404 Standard mit den folgenden Änderungen.

1. JSON-Eigenschaftsnamen sind case invariant und es kann keine Garantie für die Groß- und 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.

...

3. REST-API

...

Der Client kann über die REST-API Informationen von elproCLOUD anfordern. Die Kommunikation läuft typischerweise in der folgenden Reihenfolge ab:

...

Das Gerät sendet seine Daten und

...

Vorkommnisse in einem

...

festgelegten Zeitintervall 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/... (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.

{

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

}

5. Allgemein für alle Anfragen

...

Spezifikation:

• Der Endpunkt REST API URL https://apibridge.elpro.cloud

  • Das API-Token wird von ELPRO bereitgestellt

• Für Entwickler ist die technische Spezifikation von OpenAPI als Swagger UI verfügbar https://apibridge.elpro.cloud/swagger

3.1 Datensätze und allgemeines Abfrageschema

Der Kunde kann verschiedene Datensätze anfordern, darunter

• Messwerte

• Geodaten

• Occurences

• Abweichungen

3.1.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: 

Im Falle eines Fehlens oder einer Nichtübereinstimmung wird eine Fehlermeldung mit dem HTTP-Status 401 "

...

Unauthorized" zurückgegeben.

...

3.1.2 Benutzerumfang

Die abgerufenen Daten fallen in den

...

Bereich der Organisation des authentifizierten API-Benutzers. Sie werden mit dem HTTP-Statuscode 200 (

...

Success) zurückgegeben.

...

3.1.3 Http-Fehler-Codes

...

...

...

...

...

...

...

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

...

3.2 Konfigurations-API

Die REST-Schnittstelle bietet einen sehr einfachen Endpunkt für die Konfiguration von LIBERO Gx-Geräten.

Konfigurationsvorlage erstellen und hochladen

• Verwenden Sie den Wizard in elproCLOUD, um eine Konfigurationsvorlage für einen LIBERO Gx zu erstellen

• Wählen Sie den richtigen LIBERO Gx-Typ (die ersten drei Ziffern der Seriennummer sind wichtig)

• Füllen Sie die Formulare des Wizard aus, bis Sie die Übersichtsseite erreicht haben

  • Alt+Klick auf die Schaltfläche "Sensor kaufen und starten".

  • Ein Dateidownload wird angezeigt

  • Speichern Sie die Datei unter einem passenden Namen (z.B. LIBERO_GH_longlive_freezer.json)

• Verwenden Sie den Endpunkt POST /api/v1/Templates, um den Inhalt der gespeicherten Konfigurations-JSON-Datei hochzuladen

  • Wichtig: Die Konfiguration muss JSON-escaped sein. Tun Sie dies programmatisch oder verwenden Sie ein Online-Tool

  • Das Anfrageobjekt wird in der Swagger UI beschrieben

• Optional: Verwenden Sie den Endpunkt GET /api/v1/Templates, um alle verfügbaren Vorlagen aufzulisten

Konfigurieren Sie die Vorlagen

• Verwenden Sie den Endpunkt PUT /api/v1/Device/{deviceSerialNumber} zur Konfiguration der Geräte

  • Ein Aufruf pro Gerät, verwenden Sie ein Skript, um diesen Prozess zu automatisieren

  • Drei mögliche Nutzdaten, die durch $type angegeben werden

    • Weitere Informationen zu den spezifischen Objekten finden Sie in der Swagger UI

    • DeviceConfigurationRequestByTemplateId und DeviceConfigurationRequestByTemplateName können zur Konfiguration eines Geräts verwendet werden

      • Optional: Bereitstellung von Metadaten, siehe Swagger UI für weitere Informationen zu Platzhaltern

    • DeviceConfigurationRequestClearPending kann verwendet werden, um eine ausstehende Konfiguration für Geräte zu löschen, die noch nicht mit der Organisation gepaart worden sind

3.3 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 signifikant 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.

{

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

}

...

4. Nachrichten Queue (AMQP)

...

• Es wird eine "Kunden-Queue" mit dem AMQ-Protokoll bereitgestellt, die erreichbar ist unter amqp.elpro.cloud.

• Der Queue-Name ist der Name der explizit bereitgestellten RabbitMQ-Queueu. Queueu und Benutzer werden von ELPRO verwaltet.

• Außerdem eine einzigartige Benutzername und Passwort für jeden Kunden zur Verfügung gestellt wird. Siehe unten in diesem Dokument für eine Beispiel-Implementierung.

• Jeder Kunde kann einen AMQP-Client seiner Wahl zum Lesen (read) und Bestätigen (acknowledge) gemäss der Liste der Nachrichtentypen nutzen.

• Die Verbindung ist TLS (Port 443)

• Auf der Produktivumgebung ist die Time To Live (TTL) der Warteschlangendaten auf drei Tage festgelegt.

4.1 Nachrichtenmodelle

Die Warteschlangen-Nachrichten haben folgende grundlegende Nutzdaten im JSON-Format:

4.2 Nachrichtentyp

Jeder Typ repräsentiert eine spezielle JSON-Nutzlast innerhalb des Data JSON-Objekts. So weiß ein Verbraucher, welches Datenmodell verwendet wird.

• eapi_measurement_new

• eapi_geodata_new

• eapi_Ereignis_neu

• eapi_deviation_enter

• eapi_deviation_leave

4.3 Datenmodelle

Die Daten-Nutzdaten sind für jeden Typ unterschiedlich.

4.3.1 Messwerte

4.3.1.1 Beispiel-Messungen

Daten mit Typ: "eapi_measurement_new"

{
    "type": "eapi_measurement_new",
    "data": {
	    "sensorId": "5368"
		"deviceId": "951FF00000340",
        "timeStamp": "2022-10-11T16:21:27+00:00",
		"error": "Short Circuit",
		"status": 0,
        "unit": "°C",
		"unitType": “temperature",
		"value": 24.6,
		"tiltAngle": 2.4,
    }
}

4.3.2 GeoDaten

4.3.2.1 Beispiel GeoDaten

Daten mit Typ: "eapi_geodata_new" 

{
    "type": "eapi_geodata_new",
    "data": {
        "timeStamp": "2022-10-11T15:21:24+00:00",
        "latitude": 47.19999075,
        "longitude": 9.50875282,
        "accuracy": 2316,
        "deviceId": "951FF00000340",
        "sensorId": "5369"
    }
}

4.3.3 Occurence

4.3.3.1 Beispiel Occurence

Daten mit dem Typ "eapi_occurrence_new" 

{
    "type": "eapi_occurrence_new",
    "data": {
        "timeStamp": "2022-10-11T15:21:24+00:00",
        "typeName": "LoggerStatusChange",
        "previousState": "Start",
        "newState": "LogDelayed",
        "deviceId": "951FF00000340",
        "sensorId": "5369"
    }
}

4.3.4 Abweichung

4.3.4.1 Beispiel Abweichung aufgetreten

Daten mit dem Typ "eapi_deviation_enter" 

{
    "type": "eapi_deviation_enter",
    "data": {
        "deviceId": "951FF00000340",
        "sensorId": 5763,
        "timeStamp": "2022-10-26T17:00:22+00:00",
        "historyType": "enter",
        "deviationType": "limit",
        "reason": "upper_limit_alarm"
    }
}

4.3.4.2 Beispiel Abweichung verlassen

Daten mit dem Typ "eapi_deviation_leave"

{
    "type": "eapi_deviation_leave",
    "data": {
        "deviceId": "951FF00000340",
        "sensorId": 5763,
        "timeStamp": "2022-10-26T18:00:22+00:00",
        "historyType": "leave",
        "deviationType": "limit",
        "reason": "upper_limit_alarm"
    }
}

4.4 AMQP-Nachrichten verwenden

4.4.1 Beispiel-Client-Code mit RabbitMQ in C#

Beispielcode für die Verbindung zu einer Warteschlange mit .NET und der Nuget-Bibliothek RabbitMQ:

public ObservableCollection<MessageModel> Messages { get; private set; }

public static IConnection connection;
public static IModel channel;
public static EventingBasicConsumer consumer;

public void Read()
{        
    var serverName = "amqp.elpro.cloud"
    var queueName = "398ab9ae90efce88dcf623cc49e302e1";
    bool autoACK = true;

    try
    {
        // Prepare 
        var factory = new ConnectionFactory()
        {
            HostName = serverName,
            UserName = "user",
            Password = "password",
            Port = 443,
            Ssl = new SslOption() 
            { 
              Enabled = true, 
              ServerName = serverName
            }
        };

        connection = factory.CreateConnection();
        channel = connection.CreateModel();
      
        var routingKey = $"*.eapi_*"; //*.eapi_measurement_new e.g.                        
        Console.WriteLine(" [*] Waiting for msgs.");

        // Consumer
        consumer = new EventingBasicConsumer(channel);
        consumer.Received += (model, ea) =>
        {
            var body = ea.Body.ToArray();
            var messageText = Encoding.UTF8.GetString(body);

            var message = new MessageModel(ea.RoutingKey, messageText);

            Dispatcher.Dispatch(() => Messages.Add(message));
        };

        // Subscribe
        channel.BasicConsume(queue: queueName,
                    autoAck: autoACK,
                    consumer: consumer);

    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error at RabbitMQ.Test: {ex.Message}");
    }
}

...

5. Verbindungsdetails und technische Spezifikation

• Endpunkt REST API URL https://apibridge.elpro.cloud

• AMQP-Server: amqp.elpro.cloud

• Für Entwickler die technische Spezifikation von OpenAPI als Swagger UI https://apibridge.elpro.cloud/swagger