要求フィルタ

DataSnap REST への移動

DataSnap には、要求フィルタを使って結果をフィルタリングするという概念があります。 あらかじめ定義されたフィルタが API に接続されていて、各パラメータについてどのフィルタを使用するか、そのフィルタにどのような値を渡すかを、URL 中に指定することができます。 たとえば、サーバー関数から非常に長い文字列が返されるけれども、必要なのは最初の数文字だけだとします。 この場合には、SubString フィルタを使用して、文字列の中の必要な範囲を指定します。 次に示すのは、1 つの入力パラメータを受け取り、結果として文字列を返す、サーバー関数の URL の例です。

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

URL の一部として渡されるパラメータには、SubString（ss）要求フィルタの range（r）関数を使用すること、そのオフセットは 1（2 文字目から開始）であり、長さは 3（または Length(結果) - オフセットの小さい方）であることが指定されています。

要求フィルタ一覧

SubString（ss）

SubString フィルタは、文字列やストリームに対して適用可能であり、count（c）、offset（o）、range（r）という 3 つの関数を備えています。 これらの関数はいずれも文字列とストリームの両方を処理することができ、文字列では文字単位の、ストリームではバイト単位の操作を行います。

count はパラメータを 1 つ取ります。このパラメータは、必要な部分文字列の長さ（オフセットは 0）を表します。

結果文字列の最初の文字を取り出す場合には、ss.c=1 のように使用します。

offset もパラメータを 1 つ取ります。このパラメータは、部分文字列に含めたくない読み飛ばす文字数を示します。

結果文字列の最初の文字以外のすべてを取り出す場合には、ss.o=1 のように使用します。

range は、offset および count という 2 つのパラメータを取り、通常の SubString 関数と同様の動きをします。

結果文字列の 2 文字目と 3 文字目を取り出す場合には、ss.r=1,2 のように使用します。

Table（t）

Table フィルタはテーブルに対して適用可能であり、SubString と同じ count（c）、offset（o）、range（r）の関数を使用することができます。

count では返される行数を、offset では読み飛ばす行数を指定します。 range は、SubString の場合と同様に、offset と count を組み合わせただけのものです。 range を使って結果テーブルの 2 行目と 3 行目だけを返す例は、次のようになります。

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

要求フィルタの使い方

ここまでの例では、戻り値に変換（フィルタ）を適用するためのフィルタ URL パラメータを示してきましたが、入出力パラメータや出力パラメータに対して変換を適用したい場合もあるでしょう。 その場合には、変換対象のパラメータのインデックスを指定することができます。

たとえば、次のシグニチャを持つサーバー関数があるとします。

function Echo( var Value: String ): String;

入力文字列の 2 文字目と 3 文字目だけを返送させたい場合には、先の例に示したように、結果を変換することができます。

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello?ss.r=1,3	（結果：ell）

あるいは、返送する対象の var パラメータに対して変換を適用することもできます。

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello?ss0.r=1,3 	（結果：Hello）

メモ： パラメータ用の要求フィルタは関数呼び出しの後に実行されます。そのため、この例で変換結果を取得するには、JSON 形式の結果から配列インデックスが 0 のオブジェクトを取り出す必要があります。 （結果を取得する場合とは異なります。結果は必ず配列の最後の値になっています。）

この 2 つの違いは、最初の例では単純に ss を使用している（関数の結果に要求フィルタを適用することを示す）のに対し、後の例では ss0 を使用している（関数シグニチャのインデックスが 0 のパラメータにフィルタを適用することを示す）ことです。

複数の要求フィルタを使用するために、複数の URL パラメータを指定することができます。 たとえば、次のようなサーバー関数があるとします。

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

この関数は、2 つのパラメータを受け取り、つなぎ合わせて、結果を返します。 要求フィルタを使わずにこの関数を呼び出すには、次のようにします。

http://localhost:8080/datasnap/rest/ClassName/Echo/Hello/World		（結果：HelloWorld）

次のいずれの方法でも、両方のパラメータに要求フィルタを適用することができます。 ただし、結果は "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

このいずれを使った場合にも、JSON 形式の結果には 3 つの値を持つ配列が含まれます。 最初の値は "H"、2 番目の値は "W"、最後の値（結果）は "HelloWorld" です。