RESTful Web サービスの入力パラメータ¶

ここでは、Web サービスの URL に追加して結果のフィルタ処理と出力のカスタマイズができるパラメータのリストを示します。

ビューの場合、以下の形式で URL にパラメータを追加することで、条件「<field name> = <value>」を追加できます。

field_name1=value_1&...&fieldNameN=valueN

たとえば、 http://localhost:9090/denodo-restfulws/support/views/customer?name=Denodo のように指定します。

datetime フィールドを基準としてフィルタリングする場合、そのフィールドの値に応じて、以下の特定の形式で上記の URL の値を指定する必要があります。
- localdate: 「<yyyy>-<MM>-<dd>」形式で値を指定します (以下の表に示す各コンポーネントの意味を参照)。以下に例を示します。
  
  http://.../views/employee?hire_date=2018-05-30
- time: 「<HH>:<mm>:<ss>」形式で値を指定します。必要に応じてナノ秒まで指定します。以下に例を示します。
  
  http://.../views/rate_conversion?instant=23:31:59.1234
- timestamp: 「<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>」形式で値を指定します。必要に応じてナノ秒まで指定します。以下に例を示します。
  
  http://.../views/sale?sale_date=2017-12-30T18:59:59
- timestamptz: 「<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z」形式で値を指定します。必要に応じて秒とタイムゾーンの間にナノ秒を指定できます。以下に例を示します。
  
  http://.../views/sale?sale_date=2017-12-30T18:59:59.123456-0800
- date (廃止): 「<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z」形式で値を指定します。以下に例を示します。
  
  http://.../views/sale?sale_date=2017-12-30T18:58:59-0800

datetime 値のパターンの意味¶
パターン	パターンの意味
yyyy	年
MM	月
dd	日
HH	24 時間表記の時刻 (0 ～ 23)
mm	分
ss	秒
S	ナノ秒 (最大 6 桁)。必要に応じて指定。
Z	タイムゾーン: 符号 (+ または -)<時><分>。「-0800」など。

注釈

REST Web サービスでは、「No searchable」と指定されたフィールドは、結果をフィルタリングする基準フィールドとしては使用できません。

ビューのリソースの場合、行のプライマリキーを指定して行を取得できます。

たとえば、 http://.../support/views/customer/1 を指定すると、 customer ビューでプライマリキーの値が 1 である行が返されます。プライマリキーを複数のフィールドで構成している場合は、それぞれの値をカンマ区切りで指定する必要があります (たとえば http://.../support/views/viewA/1,value1)。

これら複数のフィールドの 1 つがいずれかの datetime 型である場合、条件「<field name> = <value>」の入力と同じ形式で値を指定します (上記を参照)。
ビューのリソースの場合、アソシエーションをたどるには、行のプライマリキーおよびアソシエーションのエンドポイントの名前を指定する必要があります (たとえば http://.../support/views/customer/1/orders)。

Denodo RESTful Web サービスおよび公開されている REST Web サービスでサポートされているパラメータ¶
RESTful Web サービスおよび REST Web サービスのパラメータ
$filter	任意の条件を使用してビューの行をフィルタリングします。VQL クエリの WHERE 句で使用できるあらゆる式を使用できます。つまり、このパラメータでは、VQL 関数や任意の演算子などを指定できます。 VQL クエリの場合と同様、パラメータ `$filter` では、非標準文字または大文字を使用したフィールド名を二重引用符で囲む必要があります (たとえば http://.../view?$filter=TRIM(%22fieldWithUpperCase%22)%3C%3E%27value%27)。 URL の最後の部分は、 `TRIM("fieldWithUpperCase")<>'value'` と同様ですが、URL エンコードとします。二重引用符が必要になるのはパラメータ $filter の内部のみであり、 `<field name>=<value>` のようなパラメータでは必要ありません。 Datetime 型のフィールドを基準としてフィルタリングするには、 TO_LOCALDATE 、 TO_TIMESTAMP 、 TO_TIME 、または TO_TIMESTAMPTZ 関数を使用して、適切な型の値を作成する必要があります。例: http://.../view?$filter=date_field%3C%3ETO_LOCALDATE%28%22yyyy-MM-dd%22,%222013-06-30%22%29 URL の最後の部分は、 `date_field <> TO_LOCALDATE('yyyy-MM-dd','2013-06-30')` と同様ですが、URL エンコードとします。注釈「No searchable」と指定されたフィールドは、このパラメータに追加できません。
$select	このパラメータで使用できる値は、[Process functions in $select parameter] チェックボックス (サービスの構成の [Advanced] タブ) に依存します。このチェックボックスをチェックしている場合 (デフォルト): 式のカンマ区切りリストを指定します。クエリの SELECT 句で使用できる式と同じです。例: http://.../views/customer?$select=concat(last_name, ', ' , first_name) AS full_name, upper(state) (わかりやすくするために、この URL はエスケープされていません。) 「AS」を指定して式の結果に別名を追加できます。このチェックボックスをチェックしていない場合: ビューのフィールドのカンマ区切りリストを指定します。例: http://.../support/views/customer?$select=cid,cname これによって、customer ビューの cid フィールドと cname フィールドが返されます。グローバル RESTful Web サービスの場合、パラメータ $select は、式のカンマ区切りリストです。ビューにアソシエーションが存在する場合、アソシエーションの相手側でビューのすべてのフィールドを投影できます。そのためには、$select に <role name> / * を追加して、パラメータ $expand=<role name> を追加します。たとえば、customer をロールとするアソシエーションが order ビューに存在する場合、以下のように <customer> / * を投影できます。 http://.../customer360/views/order?$select=id,date,customer%20/%20&$expand=customer ロール名 (customer) とスラッシュの間およびスラッシュとアスタリスクの間には、それぞれ空白文字 (%20) を記述する必要があります。アソシエーションの相手側でビューのフィールドの一部のみを投影することもできます。たとえば、http://.../customer360/views/order?$select=id,date,customer/firstname,customer/lastname&$expand=customer とします。注釈ビューにプライマリキーとアソシエーションが存在する場合、出力には各行のアソシエーションに関する情報が追加されます。この情報が不要な場合は、パラメータ `$displayRESTfulReferences=false` を URL に追加するか、サービスの構成で [Display RESTful links] チェックボックス ([Settings*] タブ) のチェックをはずします。
$groupby	グループ化に使用するフィールドのカンマ区切りリスト。例: http://.../view?$groupby=Name&$select=Name このパラメータにフィールドを追加することは、SQL ステートメントの GROUP BY 句にそのフィールドを追加することと等価です。したがって、このパラメータを追加する場合は、$select も追加して、$groupby パラメータに記述したフィールドのみを選択する必要があります。 GROUP BY の主な用途は、DISTINCT を実行できるようにすることです。これは、(SQL ステートメントに DISTINCT 句を追加する場合のように) 重複しない行のみを取得できるようにすることです。そのためには、ビューのすべてのフィールドをこのパラメータに追加します。
$having	クエリの HAVING 句に追加するフィールドのカンマ区切りリスト。例: http://.../customer?$select=state&$groupby=state&$having=%27CA%27 %27 はエンコードした一重引用符です。
$expand	目的のリクエストに応えるために Web サービスから Denodo サーバーに送信するクエリの EXPAND 句に追加するロール名のカンマ区切りリスト。展開したフィールド (関連付けられているビューのフィールド) を `$select` パラメータで参照する場合に、このパラメータが必要です。参照するすべてのロールをここで指定する必要があります。詳細については、「 Associations 」を参照してください。例: http://.../customer?$select=is_from/cityname&$expand=is_from
$start_index および $count	ビューへのクエリ実行時の改ページに使用します。たとえば、http://.../customer?$start_index=0&$count=10 を指定すると、結果の先頭から 10 件のエレメントが返されます (先頭のエレメントでは `start_index=0`)。改ページを使用する場合、リクエストされたページの行を取得する場合に実行する `OFFSET <rows offset> FETCH NEXT <rows> ROWS ONLY` 句が SQL クエリに追加されます。クライアントアプリケーションがリクエストするページごとにクエリが実行されることに注意してください。そのため、ビューのデータをすべて取得する予定のアプリケーションでは、改ページを使用しないか、大きな「$count」を使用することをお勧めします。これにより、サービスで実行するクエリの数が減り、Virtual DataPort の負荷が軽減されます。改ページでリクエストを実行しても、サービスが使用するメモリの量は減りません。これは、クエリの結果がストリーミングで処理されるためです。クライアントアプリケーション (この場合は REST Web サービスまたは RESTful Web サービス) がクエリを実行すると、Virtual DataPort では最初の行を生成するとすぐにクエリの結果の送信を開始します。クライアントへの結果の送信が終わるまでクエリ全体の終了を待機しません。Web サービスでも同様です。行を処理し、Virtual DataPort から行を受け取るとすぐにデータをクライアントに送信するため、クエリの結果をメモリに保存しません。
$orderby	1 つまたは複数のフィールドを基準として結果を並べ替えます。これらのフィールドをカンマ区切りで記述して、各フィールドの後に修飾子 ASC (昇順の場合) または DESC (降順の場合) を指定します。例: http://.../support/views/customer?$orderby=cid+ASC 注釈 REST Web サービスでは、「Do not output」と指定したフィールドは、このパラメータに追加できません。
$format	データの表現を選択します。このパラメータは、HTTP ヘッダー Accept を送信する操作の代替手段です。このパラメータの値は、Accept ヘッダーの値よりも優先されます。指定できる値は以下のとおりです。 json xml html rss (公開されている REST Web サービスが RSS 対応として構成されている場合のみ) REST Web サービスでは、[Create REST Web service] ダイアログの [Available representations] で選択した値のみを指定できます (「デフォルト表現と使用可能な表現の選択」を参照)。
$jsoncallback	JSON 表現では、接頭辞として関数名が付加されたデータをビューから返すことができます。このようなデータを JSONP (JSON with padding) と呼びます。この場合、ブラウザーで受け取る応答はデータではなく、スクリプトです。 JSONP を取得するには、関数名と共に `$jsoncallback` パラメータを URL に追加します。たとえば、http://localhost:9090/denodo-restfulws/support/views/incidents?$format=JSON&$jsoncallback=js_function を指定すると、以下の内容が返されます。 js_function( <result of the query> ) 結果セットの行数をリクエストする場合に、このパラメータを追加すると、関数のパラメータとして行数が返されます。以下に例を示します。 http://localhost:9090/denodo-restfulws/support/views/incidents/$count?state=California&$format=JSON&$jsoncallback=js_function これによって以下の応答が返されます。 `js_function(9382)`: 9382 は、incidents ビューの行のうち、条件 state = 'California' を満たす行の数です。 JSON 以外の表現をリクエストする場合、このパラメータは無視されます。
$displayRESTfulReferences	デフォルトでは、ビューをリクエストして得られた結果には、各行にその行自体へのリンクが記述され、ビューのアソシエーションごとに、そのアソシエーションをたどるためのリンクが記述されています。これらのリンクが結果に記述されないようにする場合は、パラメータ displayRESTfulReferences=false を追加します。 [Display RESTful links] オプションのチェックをはずして公開された REST Web サービスでは、このパラメータが無視されます (「 [Settings] タブ (REST) 」を参照)。
$noescapeHTML	HTML エスケープされない値が設定されたフィールドのカンマ区切りリスト。 HTML 表現では、 `text` 型の値がすべてデフォルトで HTML エスケープされます。たとえば、フィールドの値が `<a href="http://www.denodo.com">link</a>` である場合、http://www.denodo.com へのリンクではなく、このテキストそのものが記述されます。これを避けるには、パラメータ `$noescapeHTML=fieldname` を追加して、 `fieldname` フィールドの値がエスケープされないようにします。詳細については、「データの HTML エスケープ」を参照してください。

これらのオプションのうち、いくつかの使用例を以下に示します。

RESTful Web サービス: パラメータを指定した URL のサンプル¶
クエリ	結果
/customer?cname=RoadRunner	cname が RoadRunner である顧客が返されます。
/customer?$select=cid,cname&$filter= (cname = 'RoadRunner' or cname = 'Coyote')&$orderby=cid DESC'	cname が RoadRunner または Coyote である顧客の cid フィールドと cname フィールドが、cid の降順で返されます。
/customer?$format=json&$start_index =10&$count=10	customer ビューのエレメント 11 から 20 までが JSON 形式の表現で返されます。

カンマ文字のエンコード

フィールドのカンマ区切りリストを値とするパラメータ ($expand、$groupby、$having、$orderby、および $noescapeHTML) では、それぞれの値に使用されているカンマ「,」をエンコードする必要があります。具体的には、 , を %2C に置き換えて、カンマはフィールド名の区切りにのみ使用します。以下に例を示します。

http://.../viewA?$orderby=id,fieldname%2Cwith%2Ccommas

サービスの [Process functions in $select parameter] オプション (サービスの構成の [Advanced] タブ) を無効にしている場合、このルールはパラメータ $select にも適用されます。

これらのパラメータの値がその処理前にデコードされるように、すべての REST Web サービスを構成できます。その場合、それらの値では、その処理前に「%2C」が変換されて「,」に戻ります。このオプションを有効にするには、以下の手順に従います。

管理者ユーザーで Denodo にログインします。
VQL シェルから以下のコマンドを実行します。

SET 'com.denodo.wsgenerator.restws.decodeQueryParametersBeforeProcessing' = 'true';

Web サービスを再度デプロイします。

このプロパティを変更した後でデプロイしたすべての Web サービスでは、エンコードされている値がその処理前にデコードされます。このプロパティの変更を適用するために Virtual DataPort サーバーを再起動する必要はありません。

この動作を元に戻すには、以下のコマンドを実行して、REST Web サービスを再度デプロイします。

SET 'com.denodo.wsgenerator.restws.decodeQueryParametersBeforeProcessing' = NULL;

このオプションには、文字「,」を使用したフィールド名をこれらのパラメータに使用できないという欠点があります。

一般的に、このオプションを有効にする必要はありません。ただし、文字「,」が必ず「%2C」にエンコードされてクライアントアプリケーションから送信される場合は、有効にする必要があります。

HTTP メソッド内部で別の HTTP メソッドをトンネリングする方法 (X-HTTP-Method-Override)¶

RESTful Web サービスおよび公開されている REST Web サービスでは、HTTP ヘッダー X-HTTP-Method-Override をサポートしています。このヘッダーを使用すると、POST リクエストの内部で他の HTTP メソッドをアプリケーションで「トンネリング」できます。たとえば、 X-HTTP-Method-Override: GET ヘッダーを記述した POST リクエストは GET リクエストとして処理されます。また、クエリパラメータを、URL のクエリではなく、リクエストの本文に記述して送信できます。

これは以下の場合に便利です。

クライアントアプリケーションと Denodo サーバーの間にファイアウォールが置かれていて、そのファイアウォールでは GET メソッドと POST メソッドのみが許可され、PUT メソッドと DELETE メソッドが許可されていない場合。
アプリケーションから送信する入力パラメータがきわめて長く、URL が HTTP リクエストの最大長を超過する場合。この場合は、POST リクエストにこのヘッダーを追加し、URL ではなくそのリクエストの本文に入力パラメータを記述して送信します。

POST リクエスト内部では、GET、PUT、および DELETE の各メソッドをトンネリングできます。

X-HTTP-Method-Override ヘッダーがあるリクエストであっても、それが POST リクエストではない場合、そのヘッダーは無視され、リクエストは本来のリクエストとして処理されます。

POST リクエスト内部で PUT リクエストをトンネリングすると、その POST リクエストは PUT として処理されます。この場合、クライアントでは、PUT リクエストを送信する場合と同様の本文を送信する必要があります。

POST リクエスト内部で GET リクエストまたは DELETE リクエストをトンネリングする場合、URL の中ではなく、リクエストの本文にパラメータを記述できます。本文に記述できるパラメータは、URL に記述できるパラメータと同じで、フィールド名、$filter、$select、$orderby などがあります。XML ドキュメント、JSON、または HTML の各形式でパラメータを記述できますが、リクエストには Content-Type ヘッダーが必要です。このヘッダーは、リクエスト本文の処理にのみ使用されます。出力は通常どおり Accept ヘッダーまたは URL のパラメータ $format で指定します。

XML ドキュメントでの入力パラメータの送信

リクエストの本文で XML ドキュメントとして入力パラメータを送信するには、HTTP ヘッダー Content-Type: application/xml を追加します。ASCII 以外の文字が正しく処理されるように入力のエンコードを設定することが推奨されます。たとえば、 application/xml;charset=UTF-8 とします。

XML は以下の形式とする必要があります。

<request>
   <parameter name="name of parameter 1">value of parameter 1</parameter>
   <parameter name="name of parameter 2"> value of parameter 2</parameter>
   <!-- ... -->
   <!-- ... -->
</request>

例:

POST /server/customer360/customer HTTP/1.1
X-HTTP-Method-Override: GET
Content-Type: application/xml;charset=UTF-8
Accept: application/xml

<request>
   <parameter name="country">Mexico<parameter>
   <parameter name="$select">client_id,name,company_name</parameter>
   <parameter name="$orderby">client_id</parameter>
</request>

これは、以下への GET リクエストの送信と等価です。

/server/customer360/customer?country=Mexico&$select=client_id,name,company_name&order_by=client_id

メキシコの顧客に関する情報が client_id で並べ替えて返されます。

JSON ドキュメントでの入力パラメータの送信

リクエストの本文で JSON ドキュメントとした入力パラメータを送信するには、HTTP ヘッダー Content-Type: application/json を追加します。ASCII 以外の文字が正しく処理されるように入力のエンコードを設定することが推奨されます。たとえば、 application/json;charset=UTF-8 とします。

JSON は以下の形式とする必要があります。

{
     "name of parameter 1": "value of parameter 1"
   , "name of parameter 2": "value of parameter 2"
}

例:

POST /server/customer360/customer HTTP/1.1
X-HTTP-Method-Override: GET
Content-Type: application/json;charset=UTF-8
Accept: application/json

{
     "country": "Mexico"
   , "$select": "client_id,name,company_name"
   , "$orderby": "client_id"
}

これは、以下へのリクエストの送信と等価です。

/server/customer360/customer?country=Mexico&$select=client_id,name,company_name&order_by=client_id

HTML 形式での入力パラメータの送信

リクエストの本文で HTML 形式とした入力パラメータを送信するには、HTTP ヘッダー Content-Type: application/x-www-form-urlencoded を追加します。ASCII 以外の文字が正しく処理されるように入力のエンコードを設定することが推奨されます。たとえば、 application/x-www-form-urlencoded;charset=UTF-8 とします。

これらの値は、キーと値を「=」で連結したキーと値のタプルを「&」で区切ったリストとしてエンコードされます。英数字以外の文字はパーセント文字でエンコードします。たとえば、値に使用している文字「%」は「%25」に置き換えます。

例:

POST /server/customer360/customer HTTP/1.1
X-HTTP-Method-Override: GET
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept: text/html

state=New%20Jersey&$select=client_id,name,company_name&$orderby=client_id

これは、以下へのリクエストの送信と等価です。

/server/customer360/customer?country=New%20Jersey&$select=client_id,name,company_name&order_by=client_id

Accept ヘッダーがあるので、データの HTML 表現が返されます。

USER MANUALS

RESTful Web サービスの入力パラメータ¶

HTTP メソッド内部で別の HTTP メソッドをトンネリングする方法 (X-HTTP-Method-Override)¶