13 Weitere bereitgestellte Funktionen
In diesem Abschnitt werden weitere Funktionen und Aktionen erläutert, die ABES/Objects spezifisch vorhanden sind.
Es wird die jeweilige Funktionalität erläutert sowie die Aufrufsyntax und das Rückgabeergebnis beschrieben.
- Funktion GetVersions
- Funktion GetRoles
- Funktion SetAssociation
- Funktion ClearAssociation
- Funktion ReconnectDb
- Aktion Upload
1. Funktion GetVersions
Diese Funktion ist eine Diagnose-Funktion, die die aktuell vorhandenen Versionsstände ausliest und als Json-Objekt zurückliefert.
Diese Funktion hat keine Parameter und kann mit und ohne Autorisierung aufgerufen werden.
Beispiel: Aufruf mit Autorisierung
|
Request |
|
|
Header |
Authorization: AbesObjects 123456… |
|
GET |
http://test.server.de/odata/GetVersions() |
Rückgabe:
|
Response (Status=200) |
|
{ “Versions”: { “VersionOData”: “2.1.3”, “VersionFramework”: “2.0.0.10215”, “VersionDBfound”: “110206”, “VersionDBrequired”: “10206” } } |
Die Elemente geben Auskunft über die Versionen der verwendeten Odata-Schnittstelle, des Backend-Framworks und der aktiven Datenbank.
Außerdem wird die für das Backend-Framework benötigte Datenbank-Version ausgegeben.
Falls keine oder eine ungültige Autorisierung mitgegeben wurde, dann wird das Feld ” VersionDBfound” entsprechend gefüllt und die Angabe zu benötigten Datenbank fehlt.
Beispiel: Aufruf ohne Autorisierung
|
Request |
|
|
GET |
http://test.server.de/odata/GetVersions() |
Rückgabe:
|
Response (Status=200) |
|
{ “Versions”: { “VersionOData”: “2.1.3”, “VersionFramework”: “2.0.0.10215”, “VersionDBfound”: “? (not authorized)” } } |
2. Funktion GetRoles
Mittels der Funktion GetRoles können die Rollen eines Objektes ermittelt werden.
Dazu sind der Schlüssel und der Klassenname des Objektes zu übergeben.
|
Parametername |
Parametertyp |
Beschreibung |
|
_OID |
string |
Schlüssel des Objektes |
|
Classname |
string |
Klasse, zu der das Objekt gehört |
Beispielaufruf:
|
Request |
|
|
GET |
http://test.server.de/odata/GetRoles( _OID=’477167524F722B793545453746634932716D50793446′, Classname=’Person’) |
Im Beispiel würde folgende Auflistung der Rollen zum angefragten Objekt zurückgegeben werden:
|
Response (Status=200) |
|
{ “Actor”: { “_OID”: “477167524F722B793545453746634932716D50793446”, “Classname”: “Person” }, “Roles”: [ { “_OID”: “48587862302F50775A495462732B6347322B43583178”, “Classname”:”Anwender” } ] } |
Dass Array “Roles” kann auch leer sein, falls keine Rollen für das angefragte Objekt definiert sind.
3. Funktion SetAssociation
Mittels der Funktion SetAssociation können Assoziationen auf Objekte aus anderen Entitäten gesetzt werden.
Da Navigations-Properties in OData für ABES/Objects nicht editiert werden können, wird die entsprechende Funktionalität mit dieser und der nachfolgenden Funktion (ClearAssociation) bereitgestellt.
|
Parametername |
Parametertyp |
Beschreibung |
|
AOParentClassName |
string |
Klasse, zu der das Objekt gehört, das die Assoziation beinhaltet |
|
AOParentItemOID |
string |
Schlüssel des Objektes, das die Assoziation beinhaltet |
|
AOAssociationClassName |
string |
Klasse, zu der das assoziierte Objekt gehört |
|
AOAssociationItemOID |
string |
Schlüssel des Objektes, das assoziiert werden soll |
Beispielaufruf:
|
Request |
|
|
GET |
http://test.server.de/odata/SetAssociation( AOParentClassName=’Kurs’, AOParentItemOID=’477167524F722B793545453746634932716D50793446′, AOAssociationClassName=’KursTyp’, AOAssociationItemOID=’475721679524F722B79354545374663548932716D5B0′) |
Im Erfolgsfall wird folgende Struktur zurückgegeben:
|
Response (Status=200) |
|
{ “status”: “succsess”, “message” : “Association was set.” } |
Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:
|
Http-Statuscode |
Beschreibung |
|
400 |
Unbekannte Entität für AOParentClassName |
|
400 |
Unbekannte Entität für AOAssociationClassName |
|
404 |
Schlüssel AOParentItemOID nicht vorhanden |
|
404 |
Schlüssel AOAssociationItemOID nicht vorhanden |
|
400 |
Angegebene Assoziation ist in der Parent-Entität nicht definiert |
|
901 (app defined) |
Änderung der Assoziation wurde durch das FrameWork aus fachlichen Gründen abgelehnt, Hinweis auf ABES/Objects-Ereignisprotokoll |
4. Funktion ClearAssociation
Mittels der Funktion ClearAssociation können Assoziationen auf Objekte aus anderen Entitäten entfernt werden.
Da Navigations-Properties in OData für ABES/Objects nicht editiert werden können, wird die entsprechende Funktionalität mit dieser und der vorhergehenden Funktion (SetAssociation) bereitgestellt.
|
Parametername |
Parametertyp |
Beschreibung |
|
AOParentClassName |
string |
Klasse, zu der das Objekt gehört, das die Assoziation beinhaltet |
|
AOParentItemOID |
string |
Schlüssel des Objektes, das die Assoziation beinhaltet |
|
AOAssociationClassName |
string |
Klasse, zu der das assoziierte Objekt gehört |
Beispielaufruf:
|
Request |
|
|
GET |
http://test.server.de/odata/ClearAssociation( AOParentClassName=’Kurs’, AOParentItemOID=’477167524F722B793545453746634932716D50793446′, AOAssociationClassName=’KursTyp’) |
Im Erfolgsfall wird folgende Struktur zurückgegeben:
|
Response (Status=200) |
|
{ “status”: “succsess”, “message” : “Association was cleared.” } |
Die nachfolgenden Bedingungen werden geprüft und ziehen ggf. Fehlermeldungen nach sich:
|
Http-Statuscode |
Beschreibung |
|
400 |
Unbekannte Entität für AOParentClassName |
|
400 |
Unbekannte Entität für AOAssociationClassName |
|
404 |
Schlüssel AOParentItemOID nicht vorhanden |
|
400 |
Angegebene Assoziation ist in der Parent-Entität nicht definiert |
|
901 (app defined) |
Löschung der Assoziation wurde durch das FrameWork aus fachlichen Gründen abgelehnt, Hinweis auf ABES/Objects-Ereignisprotokoll |
5. Funktion ReconnectDb
Es kann vorkommen, dass die Odata-Schnittstelle die Verbindung zum DB-Server verliert – bspw. weil vorübergehende Verbindungsprobleme zur Datenbank auftraten.
In diesem Fall liefert die Odata-Schnittstelle „interne Servererror“ (Statuscode 500) zurück, obwohl der Request selbst fehlerfrei war.
In diesem Fall sollte ein Neu-Aufbau der DB-Verbindung mittels der Funktion ReconnectDb initiiert werden:
|
Request |
|
|
GET |
http://test.server.de/odata/ReconnectDb() |
Die Funktion selbst erfordert keine Parameter.
Als Rückgabe erfolgt der Statuscode 200 (Ok), im Fehlerfall erneut der Statuscode 500.
6. Aktion Upload
Für den Datei-Upload sind 2 Schritte notwendig:
- Neu-Anlage oder Auswahl einer bestehenden AbesObjects-Entität, welcher die Datei zugeordnet werden soll;
Dies kann bpsw. eine neue oder bestehende Anfrage sein. Benötigt wird dann die OID der Entität. - Upload der Datei als “POST” mit Hilfe des folgenden Endpunktes: …/odata/Upload;
Die Datei selbst wird als Formdata im Body des Requests übertragen. Zusätzlich werden im Body noch die beiden Parameter „AblageKontextClassName“ und „AblageKontextOID“ benötigt. Die Werte der Parameter stellen den Bezug zur Entität in AbesObjects her, welcher die Datei zugeordnet wird. Der Wert „AblageKontextClassName“ bezeichnet die Klasse und der zweite Parameter die OID.
Zu beachten ist, dass im Header ein gültiges „Authorization“-Token mitgeschickt werden muss.
Im Erfolgsfall erhält man in der Response den Statuscode 201 und falls keine Daten übertragen wurden, den Statuscode 204. Mögliche Fehler sind:
- 401: nicht autorisiert
- 400: fehlender oder falscher Parameter (mit zusätzlichen Informationen)
- 500: interner Fehler (mit zusätzlichen Informationen)
Nachfolgend ein exemplarischer POST-Request über Postman:
Die Bildschirmfotos können in aktuellen Programmversionen visuell abweichen.
Sie haben Fragen oder Anregungen? Schreiben Sie uns gerne an support@rackow-software.de