Zugriff via REST-API

Die REST-API Schnittstelle bietet die Möglichkeiten Daten direkt zu exportieren und anderen Programmen weiterzuverarbeiten. Anwendungsfälle hierfür sind die Weiterverarbeitung in einer Simulationsumgebung oder das Austauschen von Informationen in vor- oder nachgelagerte Systeme wie ein 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}
]}

Beispiele für REST-API Abrufe

Schritt 01: Verwalten von Schlüsseln

Unter Einstellungen / Keys kann ein neuer Schlüssel für ein Tabellenobjekt 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. Dieser kann jederzeit zurückgesetzt werden, sollte der Schlüssel eventuell kompromittiert sein.

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 vereinfacht die Weiterverarbeitung.

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

Nachdem die Tabellen und Spalten bekannt sind, können Daten abgerufen werden. Dabei wird der Spaltennamen und ein Limit übergeben. Das Limit gibt an wie viele Werte abgefragt werden sollen.

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 zugehörigen Metadaten abfragen zu können, werden diese in die Abfrage integriert. Zusätzlich kann ein Filterkriterium angegeben werden, nach dem gefiltert werden soll, z.B. eine Auftragsnummer. 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)