Daten über eine REST-API in die smartPLAZA laden
DatenBerg Store stellt eine Schnittstelle mit temporärem Speicher bereit, der es erlaubt Daten von überall in Cloud- und On Premise-Instanzen von DatenBerg smartPLAZA zu übertragen. Die Übertragung erfolgt über die hier dokumentierte REST-API, sowie von DatenBerg bereitgestellte Tools.
Funktionsprinzip
Beim Import über die REST-API Schnitstelle werden drei Begriffe unterschieden:
- Store: Der kundenspezifische Datenspeicher
- Bucket: Das Pendant zu den einzelnen Tabellen in der smartPLAZA im DatenBerg Store (Pufferdatenquelle)
- Daten: Inhalte in den einzelnen Tabellen, wie beispielsweise Messmerkmale
Store
Ein Store stellt die nötigen Schnittstellen und Speicher für Ihre Daten bereit. Der Store agiert als Puffer zwischen der Datenaufnahme und den Import-Funktionalitäten in smartPLAZA, wo er als Datenquelle hinzugefügt werden kann. Zudem gibt es für jeden Store eine Richtlinie die besagt, wie lange aufgenommene Daten behalten werden.
Für jeden Store erhalten Sie einen Lese- und einen Schreibschlüssel. Diese erlauben jeweils ausschließlich das Auslesen der Daten zur Übertragung in smartPLAZA, beziehungsweise das Hinzufügen von neuen Daten.
Bucket
Um aufgenommene Daten logisch voneinander zu trennen, können diese beliebig vielen Buckets innerhalb eines Stores zugeordnet werden. Jeder Bucket erscheint später als eigene Datenquelle in smartPlaza.
Beispiel: An einer Produktionslinie werden Umweltdaten, Maschinenparameter und Qualitätsdaten in jeweils eigene Buckets innerhalb eines Stores aufgenommen.
Daten
Die Store API arbeitet mit einer Zeile von Name-Wert-Paaren als kleinste Dateneinheit. Dies können beispielsweise aufgenommene Sensordaten, aber auch Metadaten wie Text und Datumsangaben sein. Beim Einspielen der Daten wird von der API automatisch ein Zeitstempel hinzugefügt.
Verbindung mit smartPLAZA
Um Daten aus einem Store in smartPlaza zu übertragen, öffnen Sie das Data-Warehouse Modul und wählen Sie “Datenquelle hinzufügen”. Wählen Sie nun als Quelle “DatenBerg Store”, geben Sie Ihren Leseschlüssel ein und klicken Sie auf “Verbinden”. Wenn die Verbindung erfolgt ist, können Sie im nächsten Schritt jeden Ihrer erstellten Buckets als Datenquelle für den weiteren Import verwenden. Zum Upload können die Daten über zwei Wege übertragen werden:
- Als JSON-Datei
- Als CSV-Datei
Upload als JSON-Datei
Die JSON-Schnittstelle nimmt eine Zeile an Daten als JSON-Dokument an. Zur Identifikation benötigen Sie Ihren Schreibschlüssel sowie eine Bucket-ID. Neue Buckets werden bei der ersten Verwendung automatisch erstellt. Tritt ein Fehler auf, wird dieser als Text zurückgegeben. Ansonsten bleibt die Antwort leer.
POST Befehl des JSON-Uploads
POST https://api.datenberg.eu/v1-put-json?key=writeKey&bucket=bucket'
Umsetzung des JSON-Uploads in curl
curl -X POST -d $'{"sensor": "a1", "measurement": 1.05}' 'https://api.datenberg.eu/v1-put-json?key=writeKey&bucket=bucket'
Umsetzung des JSON-Uploads in Python
from requests import post
from json import dumps
post(
"https://api.datenberg.eu/v1-put-json?key=writeKey&bucket=bucket",
dumps({
"sensor": "a1",
"measurement": 1.05
})
)
Upload als CSV-Datei
Die CSV-Schnittstelle erwartet eine Zeile von Spaltenüberschriften und eine zugehörige Zeile an Daten in UTF-8-Kodierung. Zur Identifikation benötigen Sie Ihren Schreibschlüssel, sowie eine Bucket-ID. Neue Buckets werden bei der ersten Verwendung automatisch erstellt.
Tritt ein Fehler auf, wird dieser als Text zurückgegeben. Ansonsten bleibt die Antwort leer.
POST Befehl des CSV-Uploads
POST https://api.datenberg.eu/v1-put-csv?key=writeKey&bucket=bucket'
Umsetzung des CSV-Uploads in curl
curl -X POST -d $'sensor;measurement\na1;1.05' 'https://api.datenberg.eu/v1-put-csv?key=writeKey&bucket=bucket'
Umsetzung des JSON-Uploads in Python
from requests import post
post(
"https://api.datenberg.eu/v1-put-csv?key=writeKey&bucket=bucket",
"sensor;measurement\na1;1.05"
)
Beschränkungen
Es gibt keine absolute Beschränkung in der Anzahl Buckets pro Store, Zeilen pro Bucket und Messwerte pro Zeile. Die Echtzeitschnittstelle zwischen Store und smartPlaza arbeitet mit einer Auflösung von etwa fünf Sekunden. Wir empfehlen daher, Messwerte ebenfalls maximal in dieser Frequenz zu schreiben. Darüber kann unerwartetes Verhalten in nachgelagerten Schritten, wie Pipelines, auftreten.
In einer Zeile können maximal 100KB Daten gespeichert werden, gemessen an der Größe der repräsentativen CSV-Datei inklusive Überschriften.
Die API nimmt ausschließlich Daten mit TLS-Verschlüsselung an. Unverschlüsselte Abfragen werden abgewiesen.
Spaltenüberschriften und Daten werden kompatibel zum CSV-Format bereinigt. Das bedeutet, dass “;” sowie Zeilenenden in Text entfernt werden, auch wenn Sie die JSON-Schnittstelle verwenden.
Daten können in manchen Fällen länger als die angegebene Zeit im Speicher behalten werden. Es gibt keine Garantie über die Verfügbarkeit dieser Daten. Diese Verhalten kann sich jederzeit ändern.
