Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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 verknüpft.

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

...

Virtuelle Darstellung mit alarmierenderAlarmierung

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.

...

2.4 Datenformat

Beachten Sie, dass jedes JSON, das von der API akzeptierte und zurückgegebene JSON 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 unabhängig von der Groß-/Kleinschreibung 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.

...

Info

Bitte beachten Sie, dass einige Abfrageergebnisse eingeschränkt limitiert sind

Spezifikation:

3.1 Datensätze und allgemeines Abfrageschema

Der Kunde kann verschiedene Datensätze anfordern, darunter

  • MessungenMesswerte

  • Geodaten

  • VorkommenOccurences

  • AbweichungAbweichungen

3.1.1 Art des Sicherheitssystems

...

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 autorisiertUnauthorized" 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 (ErfolgSuccess) zurückgegeben.

3.1.3 Http-Fehler-Codes

400

Schlechte Anfrage

Bad request

z.B. fehlender obligatorischer Parameter

401

Nicht autorisiert

Unauthorized

Ungültiger oder fehlender API-Schlüssel

404

Ressource nicht gefunden

Resource not found

Ungültige Seriennummer oder ID

406

Nicht akzeptabel

Not Acceptable

Accept Header sollte nur application/json lauten

410

Lizenz erschöpft

License exhausted

Anzahl der verbrauchten Abfragen oder Datentransfers

500 Server

-Fehler

Error

Unerwartete interne Ausnahme

503

Dienst vorübergehend nicht verfügbar

Dienst aufgrund von Wartung oder Update nicht verfügbar

...

Service Temporarily Unavailable

Dienst aufgrund von Wartung oder Update nicht verfügbar

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.

...

Major-Nummern stellen eine Schnittstelle zur elproCLOUD zur Verfügung und werden erhöht, wenn die Funktionalität der Schnittstelle drastisch signifikant verändert wird. Minor-Nummern werden erhöht, wenn der zurückgegebenen Datenstruktur Informationen hinzugefügt werden. 

...

Code Block
languagejson
{

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

}

...

4. Nachrichten

...

Queue (AMQP)

...

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

  • Die WarteschlangenDer Queue-Name ist der Name der explizit bereitgestellten RabbitMQ-WarteschlangeQueueu. Warteschlange Queueu und Benutzer werden von ELPRO verwaltet.

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

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

  • Die Verbindung ist TLS nur (Port 443)

  • In Produktion die Zeit zu leben Auf der Produktivumgebung ist die Time To Live (TTL) der Warteschlangendaten wird auf drei Tage festgelegt.

...

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

Feldname

Typ

Beschreibung

Typ

type

String

Mögliche Nachrichtentypen:

  • eapi_measurement_new

  • eapi_geodata_new

  • eapi_Ereignis_neu

  • eapi_deviation_enter

  • eapi_deviation_leave

Daten

data

JSON-

Objekt

Object

Innere JSON-Darstellung einer Info-Nachricht, siehe Info-Datenmodelle weiter unten in diesem Dokument

4.2 Nachrichtentyp

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

...

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

4.3.1

...

Messwerte

Feldname

Typ

Beschreibung

sensorId

Int64

Id für die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Kennung des Geräts

Wert

value

Dezimal

Decimal

Numerischer Wert der Maßnahme

Zeitstempel

timeStamp

DateTimeOffset

DateTime der Messung als

Zeitzone utcEinheit

Zeitzone utc

error

String

Fehlermeldung des jeweiligen Sensors

status

Decimal

Status des jeweiligen Sensors

unit

String

Einheit Token

Mögliche Werte:

K,°C,°F, %

unitType

String

Typ der Einheit als Text:

  • Temperatur

  • relative_Luftfeuchtigkeit

tiltAngle

Decimal

Numerischer Wert des Neigungswinkels vom Gerät

4.3.1.1 Beispiel-Messungen

...

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

4.3.2 GeoDaten

Feldname

Typ

Beschreibung

sensorId

Int64

Id

ID für die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Kennung des Geräts

Breitengrad

latitude

Doppelter

Double

Breitengrad mit 8 Ziffern Genauigkeit

Längengrad

longitude

Doppelter

Double

Längengrad mit 8 Ziffern Genauigkeit

Zeitstempel

timestamp

DateTimeOffset

datetime in der Zeitzone

utc

UTC

Genauigkeit

accuracy

Dezimal

Decimal

Genauigkeit in Metern

4.3.2.1 Beispiel GeoDaten

...

Code Block
{
    "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

Feldname

Typ

Beschreibung

sensorId

Int64

Id

ID für die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Kennung

Identifikation des Geräts

Zeitstempel

timeStamp

DateTime

DatumZeitpunkt

Datumund Zeitpunkt des Auftretens als Zeitzone

utc

UTC

typeName

String

"

LoggerStatusÄnderung

LoggerStatusChange"

previousState

String

Mögliche Werte:

"Undefined", "Init", "Shelflife", "Pairing", "Start", "LogDelayed", "LogTransit", LogPaused", "LogArrived", "StopStopped", "StopSleep", "Calibration", "EmergencyReadOut", "FatalError", "ProductionCalibration"

neuerStatus

newState

String

4.3.3.1

...

Beispiel Occurence

Daten mit dem Typ "eapi_occurrence_new" 

Code Block
languagejson
{
    "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

Feldname

Typ

Beschreibung

sensorId

Int64

Id für die Sensordaten, die eine Datensenke darstellen.

deviceId

String

Kennung des Geräts

Zeitstempel

timestamp

DateTimeOffset

DateTime der Abweichung als Zeitzone utc

historyType

String

Typ der Abweichung beschreibt den Beginn oder das Ende der Abweichung.

Mögliche Werte:

"

eingeben

enter"
"

verlassen

leave"

deviationType

String

Abweichungstyp, mögliche Werte:

"

Batterie

battery",
"

Ausfall

failure",
"

fehlt

missing",
"

Radio

radio",
"

Limit

limit"

Grund

reason

String

Abweichung Erklärung Code

limitzone

String (opt.)

Grenzwert Zonencode für eine Grenzwertabweichung

Mögliche Werte:

L1,L2,L3, H1,H2,H3...

4.3.4.1 Beispiel Abweichung

...

aufgetreten

Daten mit dem Typ "eapi_deviation_enter" 

Code Block
{
    "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"

Code Block
languagejson
{
    "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#

...

Code Block
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

...