ContextQMD
Back to Sagegmbh

3.3. Aufbau der URL

wiki-spaces-s1-pages-2629435393-3-dot-3-dot-plus-aufbau-plus-der-plus-url.md

latest8.6 KB
Original Source

3.3. Aufbau der URL

By Frank Sprenger

3 min

Add a reaction

Grundlegender Aufbau

Jede Url ist nach folgendem Schema aufgebaut:

https://[baseurl]/[Virtual Directory]/[Application]/[Contract]/[Dataset]/[Ressourcentyp]

Je nach der Art der Verwendung der Sage 100 API sind die Angaben für die Basis Adresse unterschiedlich:

Bei Verwendung der API über das Sage API Gateway

https://connectivity.sage.de/ws/[EntitlementID]

|

Segment Name

|

Beispiel

|

Beschreibung

| | --- | --- | --- |

|

Segment Name

|

Beispiel

|

Beschreibung

| | --- | --- | --- | |

EntitlementID

|

260662

|

Die EntitlementID ist die eindeutige ID einer Kundeninstallation und muss immer angegeben werden

|

Bei Verwendung der API über den direkten Zugriff innerhalb einer Installation auf den Applikationsserver

https://[host]:[port]

Die folgenden Segmente sind für beide Varianten gleich:

|

Segment Name

|

Beispiel

|

Beschreibung

| | --- | --- | --- |

|

Segment Name

|

Beispiel

|

Beschreibung

| | --- | --- | --- | |

Virtual Directory

|

sdata/

|

Ein virtuelles Verzeichnis das besagt, dass die Bearbeitung der Anfrage auf darunter liegenden Segmenten, dem Sage 100 spezifischen SData Protokoll folgt. Dieses Segment muss immer den konstanten Wert "sdata" enthalten.

| |

Application

|

ol/

|

Name der Zielapplikation. Für die Sage 100 API ist dies immer "ol".

| |

Contract

|

apiKunden.Sage.API/

|

Name der API (ein Vertrag beinhaltet mehrere Endpunkte/Ressourcen)

| |

Dataset

|

OLDemo;123/

|

Der Dataset, der den Datenkontext angibt. In der Sage 100 API muss dies immer im Format "[Name der Datenbank];[Nummer des Mandaten]" erfolgen.

| |

Ressourcentyp

|

eptKunden.Sage.API

|

Der Endpunkt der Anfrage. Ein Endpunkt definiert immer einen Ressourcentyp.

|

In den Beispielen wird [baseurl] als Platzhalter für die Basis-Url verwendet. Der Platzhalter ist durch die oben erklärte Basis-Url, je nach Verwendung, zu ersetzen.

Urls von Ressourcen

Auf einem Ressourcentyp können in der Regel CRUD-Operationen gegen eine einzelne Ressource aber auch Queries ausgeführt werden.

Url eines Ressourcentyps

Ein Ressourcentyp wird dann angesprochen wenn das letzte Segment der URL nur den Namen der Typs beinhaltet.

https://[baseurl]/sdata/ol/apiKunden.Sage.API/OLDemo;123/eptKunden.Sage.API

Solche Urls sind für folgende Anfragearten zu verwenden:

  • Queries (GET) zum Lesen einer Liste von Ressourcen

  • Erzeugen (POST) einer Ressource

Url einer einzelnen Ressourcen

Das Sage 100 API Protokoll erkennt den Zugriff auf eine einzelne Ressource durch das anfügen eines in einer Klammer '(' ')' eingeschlossenen Schlüsselwertes - in einfachen Ausführungszeichen - oder eines booleschen Ausdrucks:

https://[baseurl]/sdata/ol/apiKunden.Sage.API/OLDemo;123/eptKunden.Sage.API('RDEwMDAy;MQ')

Die obige Url adressiert von dem Ressourcentyp 'eptKunden.Sage.API' der API 'apiKunden.Sage.API' die Ressource, die durch den Schlüssel 'RDEwMDAy;MQ' eindeutig identifiziert ist.

Urls auf einzelne Ressourcen sind zu verwenden für:

  • Abrufen der Daten einer Ressource (GET)

  • Ändern der Daten einer Ressource (PUT/PATCH)

  • Entfernen einer Ressource (DELETE)

Encoding von Schlüsselangaben

Eindeutige Schlüssel einer Ressource sind in der Regel mit Werten aus mehreren Feldern zusammengesetzt.

  • Die Werte der Schlüsselfelder sind base64 encodiert und mit einem Semikolon ";" getrennt zusammengefasst.

  • Bei welchen Feldern es sich um ein Schlüsselfeld handelt und deren Reihenfolge ist der Referenzdokumentation zu entnehmen.

Beispiel:

|

Schlüsselfeld

|

Wert

|

Base64 encoded

|

Ergebnis

| | --- | --- | --- | --- |

|

Schlüsselfeld

|

Wert

|

Base64 encoded

|

Ergebnis

| | --- | --- | --- | --- | |

key1

|

"D10002"

|

"RDEwMDAy"

|

"RDEwMDAy;MQ"

| |

key2

|

1

|

"MQ"

|

Falls eine Ressource zuvor über eine Query gesucht wurde, ist im Ergebnis der bereits codierte Primärschlüssel im System-Property '$key' enthalten.

Template Url

Über die Template-Url kann ein leerer Datensatz, gefüllt mit Default-Werten abgerufen werden. Eine Template-Url setzt sich aus der Ressourcentyp-Url, gefolgt von dem Schlüsselwort $template als letztem Segment, zusammen.

Die folgende Url

https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemo;123/eptArtikel.Sage.API/$template

liefert bei einer Get-Operation beispielhaft folgendes Ergebnis:

{ "CustomFields": [], "Artikelnummer": "", "Steuerklasse": 1, "DezimalstellenVK": 0, "DezimalstellenBasis": 0, "DezimalstellenLager": 0, "UmrechnungsFaktorLME": 1.0, "Lagerfuehrung": -1, "Besteuerungsart": -1, "AuspraegungID": 0, "Herkunft": 0, "Erloescode": 0, "IstBestellartikel": -1, "IstRabattfaehig": -1, "IstSkontierfaehig": -1, "IstVerkaufsartikel": -1, "PreiseinheitVK": 1, "UmrechnungsfaktorVK": 1.0, "Gewicht": 0.0, "GewichtLME": 0.0, "KalkulatorischerEK": 0.0, "Meldebestand": 0.0 }

Intermediate Urls

Während die vorher beschriebene Urls zum Lesen und Bearbeiten von Daten dienen, ist es die Aufgabe von Intermediate Urls Informationen der Installation zur Verfügung zu stellen. Diese Informationen werden benötigt um

  • zu überprüfen, ob die adressierte Installation die gewünschte API in der benötigten Version zur Verfügung stellt (Contract) und

  • die vorhandene Datasets der Installation zu kennen (diese sind i.d.R. in jeder Installation unterschiedlich).

Contract

Ein GET Anfrage auf eine Application-Url liefert eine Liste der APIs, die diese Installation unterstützt.

https://[baseurl]/sdata/ol/

Liefert das Ergebnis in folgender Form:

{ "$url": "https://[baseurl]/sdata/ol/", "$descriptor": "Contracts", "$updated": "2022-04-07T13:30:59+02:00", "$resources": [ { "$url": "https://[baseurl]/sdata/ol/apiArtikel.Sage.API", "$key": "apiArtikel.Sage.API", "$descriptor": "Artikel", "$version": "1.0.0", "$updated": "2022-04-07T13:30:59+02:00" }, { "$url": "https://[baseurl]/sdata/ol/apiBelegerfassung.Sage.API", "$key": "apiBelegerfassung.Sage.API", "$descriptor": "Belegerfassung", "$version": "1.0.0", "$updated": "2022-04-07T13:30:59+02:00" }, { "$url": "https://[baseurl]/sdata/ol/apiKunden.Sage.API", "$key": "apiKunden.Sage.API", "$descriptor": "Kunden", "$version": "1.0.0", "$updated": "2022-04-07T13:30:59+02:00" }, { "$url": "https://[baseurl]/sdata/ol/apiLieferanten.Sage.API", "$key": "apiLieferanten.Sage.API", "$descriptor": "Lieferanten", "$version": "1.0.0", "$updated": "2022-04-07T13:30:59+02:00" } ] }

Dataset

Ein GET Anfrage auf eine Contract-Url liefert eine Liste der Datasets der angefragten Installation.

https://[baseurl]/sdata/ol/apiKunden.Sage.API

Liefert ein Ergebnis in folgender Form:

{ "$url": "[baseurl]/sdata/ol/apiKunden.Sage.API", "$descriptor": "Datasets", "$updated": "2022-04-07T13:35:18+02:00", "$resources": [ { "$url": "[baseurl]/sdata/ol/apiKunden.Sage.API/OLDemoReweAbfD;123", "$key": "OLDemoReweAbfD;123", "$descriptor": "OLDemoReweAbfD, Mandant: Mustermann & Söhne GmbH, Frankfurt", "$updated": "2022-04-07T13:35:18+02:00" }, { "$url": "[baseurl]/sdata/ol/apiKunden.Sage.API/OLDemoReweAbfD;999", "$key": "OLDemoReweAbfD;123", "$descriptor": "OLDemoReweAbfD, Mandant: Test OHG", "$updated": "2022-04-07T13:35:18+02:00" }, ] }

Für alle Contracts (APIs) werden dich gleichen Datasets zurückgeliefert. Es werden nur die Datasets zurückgeliefert, die in der Installation für die API freigegeben wurden. Bei einer direkten Anfrage gegen den Applikationsserver werden alle vorhandenen Datasets zurückgeliefert.

Collapse action bar

View all comments

Open Details Panel

Create page

Open Rovo Chat

Add a comment

Add a reaction