3.5. Steuerung der Anfrage

Owned by Frank Sprenger
Last updated: Mar 11, 2024
4 min read

 

Neben Url und Payload spielen Http-Header und Query-Parameter eine wichtige Rolle in der Sage 100 API. Insbesondere Query-Parameter bieten die Möglichkeit, die zu lesenden Daten einzugrenzen.

Je weniger Daten zwischen Client und Provider übertragen werden, desto besser wird die Performance einer Abfrage sein.

Http-Header

Die in der Sage 100 API verwendeten Http-Header, die Client bei einer Anfrage angeben muss oder kann, sind der nachfolgenden Tabelle mit ihrer Bedeutung aufgelistet.

Header

Pflicht

Bedeutung

Beispielwert

Header

Pflicht

Bedeutung

Beispielwert

Authorization

Authorization Bearer Token ausgestellt von Sage Konto

Bearer HHNE8589...

Accept

Die externe API unterstützt ausschließlich Json formatierte Inhalte. Es muss in allen Requests "application/json" gesetzt werden.

application/json

Content-Type

Bei Aktionen, bei denen der Client einen Body überträgt (PUT/PATCH/POST), muss dies im JSON Format erfolgen.

application/json

Accept-encoding

 

Über den Accept-Encoding Header kann der Client gepackten Payload anfordern. Es werden sowohl gzip als auch deflate unterstützt.

gzip,deflate

Prefer
(mehrere Werte des Headers werden mit Kommata separiert)

 

  • Compact
    Ist diese Angabe im Header gesetzt, werden verschiedene System-Properties nicht übertragen: $url, $updated, $descriptor

  • Shrinked
    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

compact,shrinked

  • lowercasenaming
    Ist diese Angabe im Header gesetzt, werden die Namen von Properties und Objekten im Payload in Kleinbuchstaben zurückgeliefert.

lowercasenaming

  • return=minimal
    Ist dieser Header gesetzt, wird bei einer erfolgreichen PUT/PATCH/POST Anfrage keine Daten zum Client zurückgeschickt

return=minimal

If-Match


(bei PUT, und PATCH)

Bei einer Update-Operation muss der ETag des zu ändernden Datensatz in diesem Header vorhanden sein. Der Etag ist ein Base64 encodierter Hashwert des Datensatzes.

STFtZgHEkPz7TyH98YEmWA==

X-ApiEndpoint


bei Anfrage gegen Datenreferenzen

Für Abfragen gegen Datareferenzen (dtr..) muss der Name des zugehörigen Datensatz (ept..) mitgegeben werden.

eptKunden.Sage.API

X-Sage-ConnectivityVersion

Muss immer mit dem Wert “1.3” gefüllt sein!

1.3

Query-Parameter

Query-Parameter können Bestandteil einer Url sein. Sie folgen auf das letzte Segment und beginnen mit dem Zeichen ‘?'. Sie bestehen aus Name-Wert Paaren, wiederum getrennt durch das Zeichen '&’. Query-Parameter werden hauptsächlich zum Sortieren und Filtern verwendet. Zusätzlich kann noch der Inhalt des Payloads der Nutzdaten gesteuert werden.

Regeln der Abfragesprache

  • String-Literale müssen mit einfachen Hochkommata umschlossen sein; numerische Werte dagegen nicht.

  • Feldnamen sind nicht Case-sensitiv

  • Ausdrücke können mit Klammern versehen werden.

  • System-Properties (solche, die mit '$' beginnen) können nicht in Ausdrücken verwendet werden

Folgendes Beispiel verwendet sämtliche zur Verfügung stehende Optionen zur Steuerung des Payload einer Query.

Die Url (zu Veranschaulichung jede Anweisung in einer eigenen Zeile)

https://[baseurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/eptArtikel.Sage.API ?where=Basismengeneinheit eq 'Stk' &startindex=2 &count=2 &select=Artikelnummer,Matchcode,KalkulatorischerEK,Basismengeneinheit &orderby=Matchcode ASC

führt zur folgenden Abfrage:

  • Lese die Datensätze der Ressource ‘eptArtikel.Sage.API’

  • deren Feld ‘Basismengeneinheit' gleich 'Stk’ ist (where=Basismengeneinheit eq 'Stk')

  • liefere ab dem 2ten Satz die folgenden 2 Sätze zurück (startindex=2&count=2)

  • aber nur die Felder “Artikelnummer,Matchcode,KalkulatorischerEK,Basismengeneinheit” (select=Artikelnummer,Matchcode,KalkulatorischerEK,Basismengeneinheit)

  • aufsteigend sortiert nach dem Inhalt des Feldes 'Matchcode' (orderby=Matchcode ASC)

Filterung von Daten

Queries, also Abfragen von einer Liste von Ressourcen, erfolgen über eine Url auf den Ressourcentyp. Zur Einschränkung der gefunden Sätze dient der “where”-Parameter.

where=[Audruck]

Dabei muss der Ausdruck ein boolsches Ergebnis liefern. Zur Definition des Ausdrucks dienen die im Folgenden beschriebenen Operatoren und Funktionen.

Operatoren

X und y können Feldnamen oder Literale sein.

Typ

Operator

Erklärung

Beispiel

Typ

Operator

Erklärung

Beispiel

Vergleich

x eq y

Gleich

Menge eq 1
Einheit eq 'Stk'

x ne y

Ungleich
(nur für numerische Felder)

Menge neq 1
Einheit neq 'Stk'

x lt y

Kleiner als
(nur für numerische Felder)

Menge lt 5

x le y

Kleiner oder gleich
(nur für numerische Felder)

Menge le 5

x gt y

Größer als
(nur für numerische Felder)

Menge gt 5

x ge y

Größer oder gleich
(nur für numerische Felder)

Menge ge 5

x between y and z

Zwischen
(nur für numerische Felder)

Menge between 1 and 10

x in (y, z)

Enthalten in
(nur für Textfelder)

Einheit in ('Stk','m')

x like y

Wie, ähnlich einem Sql-Like. Der in einem Feld zu suchende Ausdruck kann mit '%' Zeichen für eine beliebige Zeichenfolge umschlossen sein.
(nur für Textfelder)

Bitte beachten Sie, dass das Zeichen ‘%' im Like-Operator in der Url encodiert als '%25’ anzugeben ist.

Ort like ‘%stadt’
( in der Url encodiert als '%25stadt')
findet alle Orte, die mit 'stadt' enden.

Name like ‘%grau%'
( in der Url encodiert als '%25grau%25')
findet alle Namen, bei denen die Zeichenfolge 'grau' enthalten ist

Logisch

x and y

Logisches und

Menge gt 1 and Menge lt 5

x or y

Logisches oder

Menge gt 1 or Einheit eq 'm'

not x

Unäres not
der folgende Ausdruck muss in Klammern stehen.

not (Menge gt 1)

Literale

Datums-Literale in der Form mit Maskierung über das ‘@'-Zeichen (Z.B. '@2023-05-12T07:30:00+01:00@' oder '@2023-05-12T07:30:00@'), werden Server-seitig immer in das Datum mit der Uhrzeit 0:00 Uhr umgewandelt. Das heißt, dass beide Werte des Beispiels als '2023-05-12T00:00:00’ interpretiert werden.

Um z.B. nach einem Zeitpunkt in einer Where-Anweisung zu filtern, muss dies mit der String-Repräsentation im ISO 8601 Standard erfolgen ('YYYY-MM-DDThh:mm:ss'). D.h. um nach dem Zeitpunkt “31.01.2024 15.00 Uhr“ zu filtern, ist dieser Wert in '2024-01-31T15:00:00' umzuwandeln. Die Angabe einer Zeitzone ist nicht zulässig.

Funktionen

Die folgenden verfügbaren Funktionen beziehen sich alle auf Felder vom Typ 'String', also Textfelder des Payloads.

Als Beispiel wird das Feld ‘Ort’ verwendet. Sein Inhalt ist 'Frankfurt'.

Funktion

Beschreibung

Beispiel

Funktion

Beschreibung

Beispiel

left(Feldname,Länge)

Liefert die linken ‘Länge’ Zeichen des Inhalts des Felds ‘Feldname’

left(Ort,5) ergibt 'Frank'

right(Feldname,Länge)

Liefert die rechten ‘Länge’ Zeichen des Inhalts des Felds ‘Feldname’

right(Ort,4) ergibt 'furt'

substring(Feldname,Start,Länge)

Liefert einen Teilstring ab der Position ‘Start' die folgenden ‘Länge’ Zeichen. 1-basiert, d.h. das erste Zeichen steht an Position 1.

substring(Ort,2,3) ergibt ‘ran’

length(Feldname)

Liefert die Anzahl der Zeichen des Inhalts des Felds 'Feldname'

length(Ort) ergibt 9

Sortierung bei Queries

Die Sortieranweisung als Queryparameter hat folgende Syntax

orderby=Feld1 ASC|DESC[,Feld2 ASC|DESC]

  • ASC - Aufsteigende Sortierung

  • DESC - Absteigende Sortierung

Steuerung der Nutzlast

Paging

Paging ist ein Mechanismus um Chunk-weise Daten zu lesen. Paging ist nur auf Queries möglich.

Die oben definierten Parameter werden folgendermaßen interpretiert

  • Ab dem Datensatz 1 (startindex=1)

  • gib die folgende 10 Datensätze zurück (count=10)

Folgende Regeln sind zu beachten:

  • Der Parameter “startindex” ist 1-basiert. D.h. 1 = der erste Satz.

  • “count” ohne gleichzeitige Verwendung von “startindex” ist nicht erlaubt

Es ist nicht sichergestellt, dass bei fortlaufendem Paging alle Sätze genau einmal geliefert werden.

Felder beschränken

Über die “select”-Anweisung können die vom Provider zurück zuliefernden Felder eingeschränkt werden. Die Anweisung kann bei Queries aber auch beim Lesen einer einzelnen Ressource angewendet werden.

Mehrere Felder sind mit Kommata zu trennen.

Hat eine Ressource Unterressourcen (z.B. Beleg mit Positionen), so kann dieser Mechanismus auch für Unterressourcen verwendet werden. Z.B.

Die Einschränkung liefert aus der Ressource das Feld ‘A0Konto' und aus Positionen jeweils das Feld 'Gesamtpreis’.

Benutzer-definierte Felder können nur als Einheit bei einer “select”-Anweisung ausgewählt werden.

Bei dieser Anweisung sind alle Benutzer-definierten Felder im Ergebnis der Anfrage enthalten. Eine Einschränkung auf einzelne Benutzer-definierte Felder ist nicht möglich.