.. _`kognihome/tools/kognidb`: ======= KogniDB ======= :Kontakt: Alexander Neumann , Nils Kucza :CITK: `kognidb `_ :Vorbedingung: ``kognidb`` unterstützt derzeit ausschließlich :term:`MySQL`. Außerdem werden :ref:`guides/rsb` und :ref:`guides/rst` benötigt und sollten **manuell** oder über :ref:`guides/citk` installiert werden. Danach kann kognidb mit `setuptools` installiert werde:: $ python setup.py install Werden RST und RSB nicht vorher installiert, wird ``setuptools`` versuchen die Abhängigkeiten aufzulösen. Die über :term:`PyPi` verfügbaren Pakete sind jedoch nicht kompatibel mit ``kognidb``. :Quickstart: Stellen Sie sicher, dass eine lokale :term:`MySQL`-Datenbankinstanz gestartet worden ist. Dann können Sie ``kognidb`` über die Kommandozeile ausführen. Als Parameter wird der Socket der lokalen MySQL-Datenbank erwartet:: $ kognidb /tmp/mysqld.socket No handlers could be found for logger "rstsandbox" Connection established... Der voreingestellte Socket hängt von der MySQL-Konfiguration ab, welche für verschiedene Betriebssysteme und Distributionen anders ausfallen kann. Das Programm kann mit ``CTRL+C`` beendet werden. RSB-Schnittstellen ------------------ .. rsbrpc:: PROVIDES-Pub-0 /service/kognidb register_app string int Meldet Anwendung in der Datenbank an und erzeugt einen Endpunkt für diese. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ get_clothing rst.kognihome.db.ClothingQuery rst.kognihome.db.ClothingResult Liefert eine Liste von Kleidungsstücken für einen Nutzer, die zu den übergebenen Tags passen. .. rsbrpc:: PROVIDES-Pub-2 /service/kognidb/ get_token_config string rst.kognihome.db.Configuration Liefert die Konfiguration für für den Nutzer mit dem übergebenen Authentifizierungstoken. .. rsbrpc:: PROVIDES-Pub-2 /service/kognidb/ get_user_config int rst.kognihome.db.Configuration Liefert die Konfiguration für für den Nutzer mit der übergebenen ID. .. rsbrpc:: PROVIDES-Pub-2 /service/kognidb/ get_user_info int rst.kognihome.db.UserInfo Liefert Nutzerdaten zu einer ID. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ get_user_tokens int rst.kognihome.db.IdentificationTokens Liefert alle Tokens, die zu einem Nutzer mit übergebener ID gehören. .. rsbrpc:: PROVIDES-Pub-2 /service/kognidb/ identify_user string rst.kognihome.db.UserInfo Liefert Nutzeraten des mit dem Token assozierten Nutzers. .. rsbrpc:: PROVIDES-Pub-0 /service/kognidb/ get_drawer string int Liefert die Schubladen-ID für einen gesuchten Gegenstand .. rsbrpc:: PROVIDES-Pub-0 /service/kognidb/ get_empty_hanger string int Liefert die Bügel-ID eines leeren Platzes in der Garderobe. Der Inhalt des übergebenen Eingabeparameters wird nicht berücksichtigt. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ get_vital_data int rst.kognihome.db.VitalDataResult Liefert Vital Daten zu einer ID. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ set_vital_data rst.kognihome.db.VitalDataSetQuerry int Überschreiben der Vital Daten. Die ID zur Nutzeridentifizierung ist enthalten. Liefert einen Fehlercode zurück. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ get_daily_logs rst.kognihome.db.DailyLogsQuery rst.kognihome.db.DailyLogsResult Liefert alle Daily Logs zu einer ID zwischen zwei anzugebenen Zeiten. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ add_daily_log rst.kognihome.db.DailyLogsAddQuery int Hinzufügen eines Logs. Liefert einen Fehlercode zurück. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ get_activity_logs rst.kognihome.db.ActivityLogsQuery rst.kognihome.db.ActivityLogsResult Liefert alle Aktivity Logs zu einer ID zwischen zwei anzugebenen Zeiten. .. rsbrpc:: PROVIDES-Pub-1 /service/kognidb/ add_activity_log rst.kognihome.db.ActivityLogsAddQuery int Hinzufügen eines Logs. Liefert einen Fehlercode zurück. .. rsbrpclist:: :type: PROVIDES Anmerkungen ----------- Zur *Anmeldung* von Anwendungen bzw. der Erstellung eines Endpunktes werden Nutzername und Passwort der Anwendung in der Form ``name:pw`` als String als Parameter übergeben. Diese Form ist vorläufig und bietet keine Sicherheit, da Nachrichten auf den entsprechenden Scopes mitgehört werden können. In wie weit dieses Verfahren durch ein sichereres ersetzt wird, steht zum aktuellen Zeitpunkt noch nicht fest. *Temporäre Berechtigungen* werden auf Anwendungsbasis vergeben. So kann eine Adresse bzw. ein Token auch mit Rechten für mehrere Anwendungen verknüpft werden (mit unterschiedlicher Gültigkeit). Außerdem bleibt die Sonderberechtigung eines Tokens für alle anderen Anwendungen transparent. Alle Anfragen benutzen den gleichen RPC `identify_user`. Hat das Token keine Berechtigung für die anfragende Anwendung, wird die Standardnutzerin zurückgegeben. Ergo kann die Anwendung den Fall wie ein unbekanntes Tag handhaben. Die gewünschte Anwendung bekommt einen _generierten_ Nutzer mit der Rolle ``temporary`` und einer zufälligen ID gemeldet. Dass es diese Rolle *NICHT* in der Datenbank gibt, sondern nur im RST-Typ ist dabei beabsichtigt, um den temporären Charakter zu unterstreichen. Im Umkehrschluss heißt das auch, dass Nutzer/Bewohner prinzipiell alle temporär vergebenen Rechte besitzen. Das kann durch anwendungsspezifische Konfigurationen bei Bedarf unterbunden werden. Gleiches gilt für den Entzug von Rechten (z.B für Paul) unter bestimmten Bedingungen. Datenbank Management -------------------- *KogniDB* wird bis aus weiteres im **read-only** modus betrieben. Demzufolge bietet ``kognidb`` als Connector keine Methoden zum Schreiben bzw. Einpflegen von Daten. Im Unterordner ``schemes`` des Projekts befindet sich eine :term:`MWB`-Datei, welche mit der `MySQL Workbench `_ bearbeitet werden kann. Außerdem befindet sich das aktuelle Datenbankschema als :term:`PNG` im gleichen Ordner. .. image:: images/scheme.png :width: 60% :align: center Stand: April 2017 Die Workbenchdatei enthält außerdem den Datenbank-:term:`Seed`, welcher als Referenzdatensatz für die geplanten Szenarien genutzt wird. Vor Tests ist es also ratsam via `Forward Engineering `_ den Datenbanksatz auf den neuesten Stand zu bringen. Der Seed kann auch mit Hilfe von der Workbench editiert werden. Bitte stellen Sie **unbedingt** sicher, dass Sie den aktuellsten Stand der Workbench-Datei besitzen und Synchronisieren Sie ihre Änderungen **umgehend**. term:`MWB`-Dateien lassen sich bei Konflikten nicht kombinieren, sodass im Zweifelsfall Ihre Änderung verloren ist und Sie die Änderungen erneut durchführen müssen. .. image:: images/workbench_seed.png :width: 60% :align: center In Insert-Tab können Daten für das Forward Engineering zugefügt werden. Stellen Sie sicher, dass Sie die Änderungen speichern, bevor Sie das Tab schließen.