ABES/Objects

Bedienungsanleitungen, Dokumentationen, Lern-Videos

13 Weitere bereitgestellte Funktionen

aoRestServer/ODATA für ABES/Objects - Hinweise für Frontend-Entwickler

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.

 

  1. Funktion GetVersions
  2. Funktion GetRoles
  3. Funktion SetAssociation
  4. Funktion ClearAssociation
  5. Funktion ReconnectDb
  6. 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:

  1. 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.
  2. 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: