Benutzerverwaltung

TYRIOS macht es möglich, Benutzer direkt über die API zu verwalten. Hier sind allgemeine Regeln für die Nutzung der Benutzer-API:

• TYRIOS hängt von verschiedenen Modulkonfigurationen ab. Es hängt von deiner Konfiguration ab, ob ein Endpunkt verfügbar ist.
• Es hängt von deinen Rechten ab, ob du einen bestimmten Endpunkt aufrufen kannst.
• TYRIOS ist ein aspektorientiertes System. Es hängt von der konkreten Konfiguration ab, welche Felder verfügbar sind und Prozesse. In diesem Dokument werden wir die typische Struktur besprechen.

Authentifizierung

Die API-Endpunkte von TYRIOS sind nur für autorisierte Nutzer verfügbar. Daher muss der Benutzer authentifiziert werden. Es gibt zwei verschiedene Arten der Authentifizierung:

• Authentifizierung durch BASIC-Authentifizierung. Das Benutzerkonto muss über ein aktiviertes REST API-Token verfügen. Du musst einen entsprechenden BASIC-Authentifizierungs-Header senden.
• Authentifizierung durch die Registrierung einer mobilen App. Du musst ein entsprechendes App-Registrierungs-Token senden.

Datenstruktur

Benutzer sind eine grundlegende Datenstruktur in TYRIOS. Nahezu jede andere Datenstruktur ist zumindest in irgendeiner Weise mit einem Benutzer über Referenzen verknüpft. Aufgrund der aspektorientierten Natur von TYRIOS bedeutet das, dass es sehr wahrscheinlich ist, dass du eine individuelle Datenstruktur hast. Dennoch ist es möglich, eine allgemeine Datenstruktur zu beschreiben, die die meisten Instanzen gemeinsam haben: UserData.

API-Endpunkte

Der allgemeine Endpunkt für die Benutzerverwaltung lautet

https://[instance.de]/service/BenutzerVerwaltung

Einen Benutzer erstellen

Um einen Benutzer anzulegen, musst du einen Benutzer mit einer PUT-Anfrage an den Endpunkt

https://[instance.de]/service/UserManagement/users

Der Body deiner Anfrage muss die UserData im json-Format enthalten.

Du kannst mit dieser Methode das Passwort des Benutzers festlegen, es wird dann automatisch verschlüsselt und kann nicht mehr abgefragt werden. Wenn das Benutzerfeld "guestUser" auf true gesetzt ist, erstellt das System automatisch einen Testbenutzer. In diesem Fall wird kein Nickname, Geburtstag oder Passwort benötigt.

Als Antwort erhältst du das vollständige UserData-Objekt.

Es ist nicht möglich, mit dieser Methode leere Benutzer zu erstellen.

Leere Benutzer erstellen

Leere Benutzer sind eine optimale Lösung, wenn du nur weißt, wie die Benutzer vom System bedroht werden sollen, du aber noch keine Kontaktinformationen kennst. Es ist also eine perfekte Möglichkeit für das Marketing. Um leere Benutzer zu erstellen, musst du eine PUT-Anfrage an den Endpunkt

https://[instance.de]/service/UserManagement/users/blankUsers

Der Payload muss die folgende Datenstruktur enthalten:

{
  "amount": 10, // Anzahl der Blanko-Benutzer, die erstellt werden sollen, erforderlich
  "preName": "blank", // Vorname des Blanko-Benutzers
  "name": "user", // Nachname des Blanko-Benutzers
  "tags": ["tag1", "tag2"] // optionales Array mit Tags zur Identifizierung der Benutzer, z.B. Marketingkampagne
}

Die Methode liefert als Antwort die folgende Struktur:

{ users: [ //Liste der UserData-Objekte mit den entsprechenden Benutzern ] }

Alle Benutzer auflisten

Alle verfügbaren Benutzer können mit einer GET-Anfrage an die URL abgerufen werden:

https://[instance.de]/service/UserManagement/users/

Das Ergebnis wird mit den Parametern offset und length paginiert. Außerdem unterstützt der Endpunkt das Filtern mit dem Parameter filter und das Sortieren mit dem Parameter sorting.

Der Filterparameter unterstützt alle Felder und muss als JSON-Datenstruktur kodiert werden.

Der Sortierparameter unterstützt Multisortierung und muss als JSON-Datenstruktur kodiert werden.

Die Datenantwort liefert eine Liste von UserData-Objekten mit der folgenden Struktur:

{
  "count": 122, // Anzahl der Elemente, die der aktuellen Anfrage entsprechen
  "users": [], // Liste der UserData-Objekte, die Anzahl hängt vom Längenparameter deiner Anfrage ab
  "pluginData": [] // Liste der Plugins (String), die direkt geladen werden können
}

Einen bestimmten Benutzer abrufen

Um die Daten eines bestimmten Benutzers abzurufen, musst du eine GET-Anfrage an die URL erstellen

https://[instance.de]/service/UserManagement/users/[userID]

Die Antwort ist das UserData-Objekt.

Einen Benutzer über einen eindeutigen Benutzer-Hash abrufen

Jeder Benutzer hat einen eindeutigen Benutzer-Hash, der den Benutzer identifiziert und der Benutzer für Kundenkarten sein kann. Du kannst einen Benutzer über einen Benutzer-Hash mit einer GET-Anfrage an die URL aufrufen

https://[instance.de]/service/UserManagement/users/byHash/[userHash]

Einen Benutzer aktualisieren

Um einen Benutzer zu aktualisieren, musst du eine POST-Anfrage an den Endpunkt senden

https://[instance-domain]/service/UserManagement/users/[userID]

Als Payload musst du die kompletten Benutzerdaten einschließlich der ID des Benutzers senden. Aufgrund des aspektorientierten Charakters des Systems empfehlen wir, zuerst die komplette Datenstruktur zu laden und sie dann zu aktualisieren.

Löschen eines Benutzers

Bisher NICHT über die REST API unterstützt

Registrierung eines Benutzers

Du kannst auch die Registrierungsfunktionen verwenden, um einen neuen Benutzer anzulegen. In diesem Zusammenhang gibt es mehr automatisierte Schritte im Hintergrund:

https://[instance-domain]/service/BenutzerVerwaltung/users/registration

Du kannst die gleichen Daten als JSON-Daten senden wie im Schritt "Erstellen", allerdings wird dem Benutzer für die weiteren Schritte möglicherweise eine E-Mail geschickt.

Benutzer-Barcode generieren

Du kannst einen Benutzer-Barcode erhalten, um den Benutzer zu identifizieren. Der Barcode verwendet den uniqueUserHash, der nicht erraten werden kann

https://[Instanz-Domäne]/Service/BenutzerVerwaltung/Benutzer/[BenutzerID]/Barcode

Generieren einer direkten Anmelde-URL

TYRIOS unterstützt direkte Anmelde-URLs. Du kannst diese URLs verwenden, um einen bestimmten Benutzer automatisch anzumelden, während der Benutzer zu einer bestimmten URL weitergeleitet wird

Um eine directLoginUrl zu generieren, musst du eine POST-Anfrage senden an

https://[instance-domain]/service/UserManagement/users/[userID]/directLogin

Du musst ein JSON-Objekt mit den folgenden Parametern senden:

{
  "redirectURL": "https://instance.de/url", // absolute url, an die der Benutzer nach dem Login weitergeleitet werden soll, erforderlich, max. Länge 255 Zeichen
  "validUntil": null // unix timestamp bis dieser Link gültig ist. Wenn null, wird der Link nie veraltet sein.
}