Lesezugriff auf smartPLAZA via REST-API

Die REST-API-Schnittstelle bietet die Möglichkeit, Daten direkt zu exportieren und in anderen Programmen weiterzuverarbeiten. Anwendungsfälle hierfür sind die Weiterverarbeitung in einer Simulationsumgebung oder der Austausch von Informationen mit vor- oder nachgelagerten Systemen wie z.B. einem ERP. In diesem Beispiel zeigen wir, wie die einzelnen Informationen in Python abgerufen werden können.

Übersicht API Funktionen

Funktion /tables-get

Die Anfrage gibt ein Array mit allem dem Schlüssel zugeordneten Tabellen zurück. Mit der Abfrage /tables-get werden die vorhandenen Messwertspalten und Meta-Daten Spalten pro Tabelle abgerufen. Dabei wird ein JSON-Dokument mit folgendem Aufbau zurückgegeben:

r = get("http://localhost/tables-get?_key=1c719300634174af")

Antwort der Anfrage:

{'success': True, 
'tables': 
   [
      {'name': 'Tabelle_Daten', 
       'metadata': [{'id': 'mdedefaf4c5', 'name': '__IMPORT_ID', 'type': 'int'},…]
       'columns': [{'id': 'c74b45c94d1_1', 'name': 'Temp. 1 Mischk. [°C] (Integral)'},….]
}]

Wenn es mehr als eine Metadatenspalte und eine Messwertspalte gibt, existieren mehr Name-Wert-Paare. Jede Spalte gibt als Information eine ID, einen Namen und die Metadaten sowie das eingestellte Datenformat zurück. Wenn einem Schlüssel mehrere Tabellen zugeordnet sind, stehen die Tabellenstrukturen im JSON hintereinander.

Funktion /data-get

Messwerte können mit Hilfe eines POST-Statements abgerufen werden. Hierzu wird der Servername und ein Schlüssel benötigt.

r = post(
    "http://localhost/data-get?_key=1c719300634174af",
    dumps({
        "columns": [
        ...
        ],
        "metadata": [
            ...
        ],
        "filters": [
            {
                "id": ...,
                "values": ...
            }
        ],
        "limit": 5
    })
)

Typen von Filter:

• Wertefilter: Ein Wertefilter benötigt die ID einer Meta-Datenspalte sowie einen Wert bzw. eine Liste von Werten nach denen gefiltert werden soll.
• Bereichsfilter: Ein Bereichsfilter benötigt die einer Meta-Datenspalte einen "min" und einen "max" Wert zwischen denen gefiltert werden soll.

Antwort der Abfrage:

{'success': True, 
'data': 
   [{'c247e1bb848_1': 3701.0},
   {'c247e1bb848_1': 3548.5}, 
   {'c247e1bb848_1': 3664.30}, 
   {'c247e1bb848_1': 3705.69}, 
   {'c247e1bb848_1': 3634.0}
]}

Beispiel für einen REST-API Abruf

Schritt 01: Verwalten von Schlüsseln

In der smartPLAZA kann unter Einstellungen / Keys ein neuer Schlüssel für eine Tabelle erstellt werden. Der Schlüssel besteht aus 16 Zeichen. Hinweis: Dieser Schlüssel ist wie ein Passwort zu sehen, damit können die Informationen aus der Tabelle ausgelesen werden. Der Schüssel ist zurücksetzbar, falls der Inhalt kompromittiert sein könnte.

Ein Schlüssel kann pro Tabelle angelegt werden oder mehrere Tabellen abdecken.

Schritt 02: Tabellenaufbau abfragen

Im Codebeispiel wird die Anzahl der Spalten pro Tabelle ausgegeben und die Spaltennamen mit den internen IDs zu einem Name-Wert JSON-Paar zusammengefasst. Dies erleichtert die Weiterverarbeitung. In den Dictionaries columns (Messwerte) und metadata (Metadaten) werden die internen IDs mit Klartextnamen gespeichert.

Hinweis: Je nach Bereitstellung der smartPLAZA wird http:// (ggf. bei lokalen Installationen) oder https:// verwendet.

from requests import get, post
from json import dumps

r = get("http://localhost/tables-get?_key=1c719300634174af")
reply = r.json()

print("Tabelle:", reply["tables"][0]["name"])
print("Metadaten:", len(reply["tables"][0]["metadata"]))
print("Spalten:", len(reply["tables"][0]["columns"]))

columns = dict(map(lambda col: (col["name"], col["id"]), reply["tables"][0]["columns"]))
metadata = dict(map(lambda col: (col["name"], col["id"]), reply["tables"][0]["metadata"]))

Schritt 03: Abfrage von Messwerten

Die Abfrage /data-get wird über ein post-Statement angesprochen. Die Abfrage benötigt den Key sowie die Spalteninformationen und ein Limit. Das Limit gibt die Menge an abzurufenden Werten an.

r = post(
    "http://localhost/data-get?_key=1c719300634174af",
    dumps({
        "columns": [columns["Temperatur"]],
        "limit": 5
    })
)
reply = r.json()

print(dumps(reply, indent=2))

Schritt 04: Abfrage von Messwerten mit Filter und Meta-Attributen

Um neben den reinen Messwerten auch die dazugehörigen Metadaten abfragen zu können, werden diese in die Abfrage integriert. Zusätzlich wird ein Filterkriterium angegeben, in diesem Beispiel die Auftragsnummer "24451". Der Filter benötigt den Spaltennamen sowie die zu filternden Werte.

r = post(
    "http://localhost/data-get?_key=1c719300634174af",
    dumps({
        "columns": [
            columns["Temperatur 1"],
            columns["Temperatur 2"],
            columns["Temperatur 3"],
        ],
        "metadata": [
            metadata["Schicht"],
            metadata["Uhrzeit"]
        ],
        "filters": [
            {
                "id": metadata["Fertigungsauftrag"],
                "values": ["24451"]
            }
        ],
        "limit": 5
    })
)
reply = r.json()

print(dumps(reply, indent=2))

###Antwort
{'success': True, 
'data':
    [
      {'c247e1bb848_1': 3701.0}, 
      {'c247e1bb848_1': 3548.5}, 
      {'c247e1bb848_1': 3664.300048828125}, 
      {'c247e1bb848_1': 3705.699951171875}, 
      {'c247e1bb848_1': 3634.0}
   ]
}

Schritt 05: Daten in Pandas übernehmen

Neben dem Export im JSON-Format können die Daten auch direkt in Python, z.B. in Pandas, weiterverarbeitet werden. Dazu werden die bereits beschriebenen Abfragen durchgeführt und anschließend das JSON in ein Dataframe überführt.

import pandas as pd

df = pd.DataFrame.from_dict(reply["data"])

print(df)