Anforderungsfilter

Nach oben zu DataSnap-REST

In DataSnap gibt es ein Konzept zum Filtern von Ergebnissen mithilfe von Anforderungsfiltern. Diese vordefinierten Konverter verbinden in eine API, mit der in dem URL festgelegt werden kann, welche Filter für den jeweiligen Parameter verwendet und welche Werte an diesen Filter übergeben werden sollen. Eine Serverfunktion gibt z.B. einen sehr großen String zurück, Sie benötigen aber nur die ersten Zeichen davon. In diesem Fall können Sie den SubString-Filter verwenden und den Bereich des Strings festlegen, an dem Sie interessiert sind. Im Folgenden finden Sie ein Beispiel des URL für eine Serverfunktion mit einem einzelnen Eingabeparameter und einem String-Ergebnis:

http://localhost:8080/datasnap/rest/ClassName/FunctionName/ParamValue?ss.r=1,3

Der als Teil des URL übergebene Parameter legt fest, dass die Range-Funktion (r) des SubString-Anforderungsfilters (ss) mit einem Offset bei 1 (mit dem zweiten Zeichen beginnen) und einer Länge von 3 (oder Länge(Ergebnis) - Offset, was kleiner ist) verwendet werden soll.

Liste der Anforderungsfilter

SubString (ss)

Der Konverter SubString kann für Strings und Streams verwendet werden. Er verfügt über drei unterschiedliche Funktionen: count (c), offset (o) und range(r). Diese Funktionen arbeiten sowohl mit Strings als auch mit Streams, also entweder mit Zeichen eines Strings oder Bytes eines Streams.

Count übernimmt einen einzelnen Parameter, der die Länge des gewünschten Teilstrings (Offset bei Null) angibt.

Beispiel, das das erste Zeichen des Ergebnis-Strings übernimmt: ss.c=1

Offset übernimmt auch einen einzelnen Parameter, der die Anzahl der im Teilstring zu überspringenden Zeichen angibt.

Beispiel, das alles außer dem ersten Zeichen des Ergebnis-Strings übernimmt: ss.o=1

Range übernimmt zwei Parameter, den Offset und die Anzahl, und verhält sich wie eine reguläre SubString-Funktion.

Beispiel, das das zweite und dritte Zeichen des Ergebnis-Strings übernimmt: ss.r=1,2

Table (t)

Der Filter Table kann für Tabellen eingesetzt werden. Er verwendet dieselben Funktionen wie SubString: count (c), offset (o) und range(r).

Count legt fest, wie viele Zeilen zurückgegeben, und Offset, wie viele Zeilen übersprungen werden sollen. Range kombiniert genau wie bei SubString einfach Offset und Count. Im Folgenden finden Sie ein Beispiel, in dem mit Range nur die zweite und dritte Zeile der Ergebnistabelle zurückgegeben werden soll:

http://localhost:8080/datasnap/rest/ClassName/FunctionName/ParamValue?t.r=1,3

Verwendung von Anforderungsfiltern

In den vorherigen Beispielen wurde die URL-Parametersyntax von Filtern für die Anwendung einer Umwandlung (Filter) auf einen zurückgegebenen Wert gezeigt; Umwandlungen können aber auch auf in/out- und Ausgabeparameter angewendet werden. Dazu geben Sie den Index des umzuwandelnden Parameters an.

Es gibt z.B. eine Serverfunktion mit der folgenden Signatur:

function Echo( var Value: String ): String;

Wenn nur das zweite und dritte Zeichen im Eingabestring angezeigt werden soll, wandeln Sie das Ergebnis folgendermaßen um:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello?ss.r=1,3	(Ergebnis: ell)

Sie können stattdessen die Umwandlung auch für den var-Parameter vornehmen:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello?ss0.r=1,3 	(Ergebnis: Hello)

Hinweis: Anforderungsfilter für Parameter werden nach dem Funktionsaufruf ausgeführt, daher müssen Sie, um das umgewandelte Ergebnis in diesem Beispiel zu ermitteln, das JSON-Ergebnis übernehmen und das Objekt am Array-Index 0 abrufen. (Im Gegensatz zum Abrufen des Ergebnisses, das immer der letzte Wert im Array ist.)

Der Unterschied zwischen diesen beiden Vorgehensweisen ist, dass im ersten Beispiel mit ss festgelegt wird, dass der Anforderungsfilter für das Funktionsergebnis verwendet werden soll, während im zweiten Beispiel mit ss0 angegeben wird, dass der Filter für den Parameter am Index 0 der Funktionssignatur verwendet werden soll.

Sie können mehrere URL-Parameter angeben, um mehrere Anforderungsfilter zu verwenden. Zum Beispiel:

Function ClassName.Echo( var Value1, Value2: String ): String
begin
   Result := Value1 + Value2;
end;

Die folgende Funktion übernimmt zwei Parameter, hängt sie an und gibt das Ergebnis zurück. Der Aufruf dieser Funktion ohne Anforderungsfilter lautet folgendermaßen:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World		(Ergebnis: HelloWorld)

Sie können für beide Parameter Anforderungsfilter verwenden. Beachten Sie bitte, dass das Ergebnis immer gleich (“HelloWorld”) bleibt:

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World?ss0,1.c=1
http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World?ss0-1.c=1
http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World?ss0.c=1& ss1.c=1

Bei allen obigen Beispielen enthält das JSON-Ergebnis ein Array mit drei Werten. Der erste Wert ist “H”, der zweite “W” und der dritte ist das Ergebnis: “HelloWorld.”