wiki-spaces-s1-pages-2629173275-3-dot-4-dot-plus-aufbau-plus-des-plus-payloads.md
By Frank Sprenger
3 min
Add a reaction
Der im Body einer Anfrage (oder der einer Antwort einer Anfrage) enthaltene Payload ist eine strukturierte Menge von Eigenschaften (Property) Namen und der dazugehörigen Werten. Die Struktur wird in JSON ausgedrückt. Zusätzlich, zu den eigentlichen Daten einer Ressource, sind Sage 100 API-spezifische Properties enthalten. Diese beginnen immer mit dem '$'-Zeichen. Je nach Art und Ergebnis der Anfrage können dies unterschiedliche sein.
Beispiel: Lesen eines Artikels
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API('MDAxMDAwNDA=;MA==') HTTP/1.1 Accept: application/json Authorization: Bearer xxxxxx
Liefert exemplarisch folgendes Ergebnis:
{ "$key": "MDAxMDAwNDA=;MA==", "$url": "https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API('MDAxMDAwNDA=;MA==')", "$updated": "2022-04-10T16:09:31+02:00", "$descriptor": "Artikel MDAxMDAwNDA=;MA==", "$etag": "AAAAAAADckk=;AAAAAAADtJ4=", "CustomFields": [], "Artikelnummer": "00100040", "Bezeichnung1": "Sani-HDR-CX 200 Full HD Camera (Auslaufartikel)", "Matchcode": "Sani-HDR-CX 200 Full HD Camera (Auslaufartikel)", "Artikelgruppe": "042", "Steuerklasse": 1, ... }
Der Body enthält die Daten als JSON Struktur. Sie beginnt immer mit ‘{' und endet immer mit ‘}’. Die Klammern umschließen immer ein zusammengehöriges Objekt. In dem Objekt stehen dann die Properties als Name-Wert Paare im Format “Name”: “Wert”, getrennt jeweils mit einem Komma. Je nach Datentyp (String, DateTime ) ist auch der Wert mit dopelten Hochkommata umschlossen. Bei Zahlen ist dies nicht der Fall (siehe oben: "STEUERKLASSE": 1 ). Datumsfelder werden immer im ISO 8601 Format erwartet und geliefert.
Ein Objekt (mit ‘{' und '}’ umschlossen) kann Unterobjekte beinhalten. Unterobjekte besitzen einen Namen und sind ebenfalls mit ‘{' und '}’ umschlossen.
In dem Payload sind einige System-Felder enthalten. Sie beginnen i.d.R. mit '$'. Ausnahme bildet hier “CustomFields”. Sie haben folgende Bedeutung:
|
Name
|
Beispiel
|
Bedeutung
| | --- | --- | --- |
|
Name
|
Beispiel
|
Bedeutung
| | --- | --- | --- | |
$key
|
"MDAxMDAwNDA=;MA=="
|
Base64 encodierter eindeutiger Schlüssel der Ressource.
| |
$url
|
"https://[baseurl]/sdata/ol/apiArtikel…”
|
Die Url, die diese Ressource eindeutig identifiziert.
| |
$updated
|
"2022-04-10T16:09:31+02:00"
|
Zeitstempel für Zeit, an dem die Ressource gelesen wurde. Es ist nicht die Zeit, an dem die Ressource zuletzt geändert wurde. Dieser Wert kann nicht als Etag verwendet werden.
| |
$descriptor
|
"Artikel MDAxMDAwNDA=;MA=="
|
Kurzbeschreibung der Ressource
| |
$etag
|
"AAAAAAADckk=;AAAAAAADtJ4="
|
Ein ETag ist eine Art Fingerabdruck für eine Ressource, anhand derer sich Änderungen ablesen lassen. Dieser Wert wird für das Concurrency-Handling verwendet. Er muss immer im “if-match” Header bei PUT oder PATCH-Operation mit geschickt werden.
| |
"CustomFields"
|
"CustomFields": [
{ “Name”: “Wert”},
{ “Name”: “Wert”}
]
|
Ist der Name einer Collection, die Installations-spezifisch hinzugefügte zusätzliche Felder als Name-Wert-Paare transportiert. (In Sage 100 Nomenklatur: “Benutzer-definierte Felder”)
|
Um nicht verwendet System-Felder auszublenden lesen sie “Komprimierung des Payloads”.
Eine Query ist immer eine Anfrage mit einer Url auf den Ressourcentyp. Eine Query liefert immer eine Liste von Ressourcen als Ergebnis im Payload.
Die Anfrage
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API HTTP/1.1 Accept: application/json Authorization: Bearer xxxxxx
Liefert exemplarische folgendes Ergebnis im Payload:
{ "$url": "https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API/", "$descriptor": "ol eptArtikel.Sage.API", "$resources": [ { "$key": "MDAxMDAwNDA=;MA==", "$etag": "AAAAAAADckk=;AAAAAAADtJ4=", ... "Matchcode": "Sani-HDR-CX 200 Full HD Camera (Auslaufartikel)" ... }, { "$key": "MDAxMDAwNDE=;MA==", "$etag": "AAAAAAADcko=;AAAAAAADtJ8=", ... "Matchcode": "T-Shirt (Variante)" ... } ] }
Das Objekt auf oberster Ebene enthält System-Properties und ein Property mit dem Namen “$resources”. Ihm folgt ein Array von Ressourcen des angefragten Typs. Dieses sind wie eine einzelne Ressource aufgebaut. Ein Array beginnt immer mit “[“ und endet immer mit “]“.
Wird kein Datensatz als Ergebnis der Anfrage gefunden, wird ein leeres Array aber kein Fehler zurückgeliefert:
{ "$url": "https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API/", "$descriptor": "ol eptArtikel.Sage.API", "$resources": [] }
Im Fehlerfall wird in der Regel eine Struktur im Body zurück geliefert, die Informationen zum Fehler enthält.
Im Falle des Http-Statuscodes 401 (Unauthorized) wird kein Payload geliefert.
Beispiel: Die Anfrage an einen unbekannten Ressourcentyp (das letzte Segment in der Url):
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/XXXX HTTP/1.1 Accept: application/json Authorization: Bearer xxxxxx
antwortet der Provider mit dem Http-Statuscode 404 (Not Found) und folgendem Payload:
{ "$diagnoses": [ { "severity": "error", "sdataCode": "ResourceKindNotFound", "applicationCode": "", "message": "Die Resource 'KeinEndpunkt' ist nicht definiert.", "stackTrace": null, "payloadPath": null } ] }
Das dem “$diagnoses” Schlüsselwort folgende Array kann mehrere Einträge beinhalten. Die wichtigsten Felder sind:
|
Feld
|
Bedeutung
| | --- | --- |
|
Feld
|
Bedeutung
| | --- | --- | |
severity
|
Der Schweregrad des Fehlers.
| |
message
|
Information über den Fehler.
|
Ein $diagnoses-Element kann auch bei einer erfolgreichen Anfrage im Payload (in der Ergebnis-Struktur) enthalten sein. Z.B. für Warnungen.
Insbesondere bei geringer Bandbreite, ist es von Vorteil, immer nur die absolut notwendigen Daten zu übermitteln. Dazu können auch System-Felder ausgeblendet werden. Lernen Sie in diesem Abschnitt, welche Möglichkeiten die Sage 100 API bietet.
Die "compact"-Einstellung erfolgt über den "Prefer" Header im Request. Ist diese Angabe im Header gesetzt, werden verschiedene System-Properties nicht übertragen:
$url
$updated
$descriptor
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API('MDAxMDAwNDA=;MA==') HTTP/1.1 Accept: application/json ... Prefer: compact
Die "shrinked"-Anweisung erfolgt über den "Prefer" Header im Request. Ist diese Angabe im Header gesetzt, werden Default-Werte nicht zurückgeliefert:
Leerstrings
0 bei int und float Datentypen
false bei boolean
Collections ohne enthaltene Elemente
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API('MDAxMDAwNDA=;MA==') HTTP/1.1 Accept: application/json ... Prefer: shrinked
Null und DBNull-Werte werden immer übertragen.
“Compact” und “Shrinked” können kombiniert werden:
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API('MDAxMDAwNDA=;MA==') HTTP/1.1 Accept: application/json ... Prefer: compact,shrinked
Shrinked und Compact werden bei Intermediate-Requests nicht beachtet!
Über die Accept-Encoding Header kann der Payload gepackt werden, Es werden sowohl gzip als auch deflate unterstützt:
GET https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API('MDAxMDAwNDA=;MA==') HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate ...
Der Einsatz von gzip / deflate muss bewusst gewählt werden:
Die (De-)Komprimierung kostet Rechenzeit
Je nach Größe und Inhalt kann die Komprimierung zu größeren Payloads führen.
Collapse action bar
View all comments
Open Details Panel
Create page
Open Rovo Chat
Add a comment
Add a reaction