Filtres de requêtes

Remonter à DataSnap REST

DataSnap inclut le concept de filtrage des résultats par le biais des filtres de requêtes. Ces filtres prédéfinis se connectent à une API, qui vous permet de spécifier dans l'URL le filtre à utiliser pour chaque paramètre et les valeurs à passer dans le filtre spécifique. Par exemple, une fonction serveur peut renvoyer une très grande chaîne, dont seuls les premiers caractères vous intéressent. Pour ce faire, vous pouvez utiliser le filtre SubString, en spécifiant la partie de la chaîne qui vous intéresse. Voici un exemple d'une URL pour une fonction serveur avec un seul paramètre d'entrée et un résultat de type chaîne :

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

Le paramètre passé dans l'URL indique d'utiliser la fonction range (r) du filtre de requêtes SubString (ss), avec un décalage de 1 (commencer par le deuxième caractère) et une longueur de 3 (ou Length(Result) - Offset, le plus petit des deux).

Liste des filtres de requêtes

SubString (ss)

Le filtre SubString peut être utilisé pour les chaînes ainsi que les flux, et a trois fonctions différentes : count (c), offset (o) et range(r). Ces fonctions fonctionnent à la fois sur les chaînes et les flux, où elles opèrent sur les caractères d'une chaîne ou les octets d'un flux.

Count prend un seul paramètre, la longueur de la sous-chaîne souhaitée (décalage à zéro).

Exemple prenant le premier caractère de la chaîne de résultat : ss.c=1

Offset prend aussi un seul paramètre, le nombre de caractères à sauter dans la sous-chaîne.

Exemple prenant tout, excepté le premier caractère de la chaîne de résultat : ss.o=1

Range prend deux paramètres, le décalage et le compteur, et agit comme une fonction sous-chaîne régulière.

Exemple prenant le deuxième et le troisième caractères de la chaîne de résultat : ss.r=1,2

Table (t)

Le filtre Table peut être utilisé sur les tables et il utilise les mêmes fonctions que SubString : count (c), offset (o) et range(r).

Count représente le nombre de lignes à renvoyer, tandis que Offset spécifie le nombre de lignes à sauter. Range, comme avec SubString, combine simplement Offset et Count. Voici un exemple d'utilisation de Range qui ne renvoie que la deuxième et la troisième lignes de la table de résultat :

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

Utilisation des filtres de requêtes

Les exemples précédents présentent la syntaxe des paramètres URL des filtres pour l'application d'une conversion (filtre) en une valeur renvoyée. Toutefois, vous pouvez aussi appliquer des conversions sur les paramètres in/out et les paramètres de sortie. Pour ce faire, spécifiez l'indice du paramètre à transformer.

Prenons, par exemple, une fonction serveur avec la signature suivante :

function Echo( var Value: String ): String;

Si vous souhaitez ne renvoyer en écho que le deuxième et le troisième caractères de la chaîne d'entrée, vous pouvez le faire comme dans l'exemple précédent, en convertissant le résultat comme suit :

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

A la place, vous pouvez appliquer la conversion sur le paramètre var à renvoyer en écho :

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

Remarque : Les filtres de requêtes pour les paramètres sont exécutés après l'appel de la fonction. Ainsi, pour récupérer le résultat converti dans cet exemple, vous devez prendre le résultat JSON et obtenir l'objet à l'indice de tableau 0 (contrairement à l'obtention du résultat, qui est toujours la dernière valeur du tableau.

La différence entre les deux exemples est que le premier exemple utilise ss, qui indique l'emploi du filtre de requêtes sur le résultat de la fonction, tandis que le deuxième exemple utilise ss0, qui indique l'emploi du filtre sur le paramètre de la signature de la fonction à l'indice 0.

Vous pouvez spécifier plusieurs paramètres URL afin d'utiliser plusieurs filtres de requêtes. Prenons, par exemple, cette fonction serveur :

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

La fonction suivante prend deux paramètres, les ajoute et renvoie le résultat. Voici l'appel de cette fonction sans convertisseur de données :

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World		(Résultat : HelloWorld)

Vous pouvez utiliser les filtres de requêtes sur les paramètres, de l'une des façons suivantes. Notez que le résultat est le même -- "HelloWorld" :

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

Pour chacun des exemples précédents, le résultat JSON contiendra un tableau de trois valeurs. La première valeur est "H", la deuxième valeur est "W" et la troisième valeur est le résultat : "HelloWorld".