Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

REST サービスの作成

この章では、%CSP.RESTOpens in a new tab クラスを使用して、Caché REST サービスを構築する方法について説明します。このクラスを使用すると、REST サービスの作成が可能になります。

この章には、以下のセクションが含まれます。

%CSP.REST クラス

%CSP.RESTOpens in a new tab クラス (%CSP.PageOpens in a new tab のサブクラス) を使用すると、REST サービスを実装できるようになります。これにより、以下の操作が可能になります。

  • REST URL と HTTP メソッドに対して実行される Caché のメソッドを指定する URL マップを定義できます。

  • 各 REST 呼び出しを独自の CSP セッションで実行するか、1 つのセッションを他の REST 呼び出しと共有するかを指定できます。

  • 必要な場合は、エラー処理のメソッドをオーバーライドできます。

REST サービスを実装するには、%CSP.RESTOpens in a new tab クラスを拡張します。クラスの拡張は、URLMap を提供し、UseSession パラメータを必要に応じて設定でき、REST 操作を実行するクラス・メソッドを提供します。1 つのネームスペース内に %CSP.RESTOpens in a new tab のサブクラスを複数定義できます。独自のエントリ・ポイントを有する各サブクラスには、それらに専用の CSP アプリケーションが必要になります。CSP Web アプリケーションの定義と、そのアプリケーションのセキュリティの指定は、管理ポータルの システム, セキュリティ管理, ウェブ・アプリケーション ページで行います。このページにアクセスするには、[システム管理]→[セキュリティ]→[アプリケーション]→[ウェブ・アプリケーション] の順にクリックします。CSP Web アプリケーションを定義するときには、%CSP.RESTOpens in a new tab のカスタム・サブクラスの名前に [ディスパッチ・クラス] を設定し、そのアプリケーションの名前として、REST 呼び出しの URL の最初の部分を指定します。

REST の URL マップの作成

XDATA URLMap では、サービスを実装するメソッドを REST 呼び出しと関連付けます。呼び出しを URL のコンテンツに基づくメソッドに直接送信することも、呼び出しをURL に基づく %CSP.RESTOpens in a new tab の別のサブクラスに転送することもできます。Web アプリケーションが処理している関連するサービスが少数の場合、実装メソッドに呼び出しを直接送信することができます。しかし、Web アプリケーションが処理している種々のサービスが多数ある場合、関連する一連のサービスを処理する %CSP.RESTOpens in a new tab のサブクラスを個別に定義できます。次に、Web アプリケーションを処理する %CSP.RESTOpens in a new tab のサブクラスは REST 呼び出しを適切なサブクラスにそのまま転送します。

%CSP.RESTOpens in a new tab のサブクラスがメソッドに呼び出しを直接送信している場合、URLMap には一連の Route 要素を含む Routes 定義が含まれます。各 Route により、指定された URL と HTTP 操作に対して呼び出されるクラス・メソッドが指定されます。一般的に、REST は GET、POST、PUT、または DELETE 操作を使用しますが、任意の HTTP 操作を指定することができます。URL には必要に応じてパラメータを含めることができます。このパラメータは、REST URL の一部として指定され、指定のメソッドにパラメータとして渡されます。

%CSP.RESTOpens in a new tab のサブクラスが他の %CSP.RESTOpens in a new tab のサブクラスに呼び出しを転送している場合、URLMap には一連の Map 要素を含む Routes 定義が含まれます。指定された接頭語を有するすべての呼び出しを Map 文は関連 %CSP.RESTOpens in a new tab サブクラスに転送し、サブクラスは動作を実装します。呼び出しをメソッドに直接送信する、または別のサブクラスに転送することで動作を実装できます。

Caché は受信する REST URL を Route URL のプロパティまたは Map Prefix のプロパティと比較します。最初の Route 要素または Map 要素から開始し、一致するものを見つけるまで、続く各要素をテストし続けます。一致するものを見つけると、Route で指定された呼び出しへ受信呼び出しを送信するか、または Map で指定されたクラスへ URL を転送します。いずれの場合でも、Caché は Routes 中で一致する要素より後の要素を無視します。そのため、Routes 中の要素の順序が重要です。受信する URL が Routes の複数の要素と一致した場合、Caché は最初の一致する要素を使用し、それ以降の一致を無視します。

Route 要素を用いた URLMap

Caché は受信する URL および HTTP 要求メソッドを Routes 中の各 Route 要素と比較します。そして最初の一致する Route 要素で指定されたメソッドを呼び出します。Route 要素は、以下の 3 つの部分で構成されます。

  • Url — REST サービスを呼び出す REST URL の末尾部分の書式を指定します。Url は : (コロン) で始まるテキスト要素とパラメータから構成されます。Url は正規表現に変換されるため、Url 内で正規表現構文を使用できます。

  • Method — REST 呼び出しの HTTP 要求メソッドを指定します。一般的には GET、POST、PUT、または DELETE ですが、任意の HTTP 要求メソッドを使用できます。要求メソッドには、サービスで実行される機能に適したものを選択する必要がありますが、%CSP.RESTOpens in a new tab クラスはそれぞれのメソッドに関する特別な処理を実行しません。HTTP 要求メソッドはすべて大文字で指定する必要があります。

  • Call — REST サービスを実行するために呼び出すクラス・メソッドを指定します。既定では、このクラス・メソッドは、%CSP.RESTOpens in a new tab をサブクラスとして持つクラスに定義されますが、任意の Caché クラス内のクラス・メソッドを明示的に指定することもできます。

例えば、DocServer サンプルでは以下のルーティングを定義しています。

XData UrlMap
{
<Routes>
  <Route Url="/echo" Method="POST" Call="Echo" Cors="false" />

これは、REST 呼び出しの最後が /echo になることと、POST メソッドを使用することを指定しています。これにより、REST サービスを定義する REST.DocServer クラスの Echo クラス・メソッドを呼び出します。Cors プロパティはオプションであり、"true" または "false" の値を有し、CORS ヘッダ処理を制御します。CORS 使用の詳細は、“CORS 使用のための REST サービスの構成” を参照してください。

完全な REST URL は、以下の部分で構成されます。

  • Caché サーバのサーバ名とポート。この章の例では、サーバ名およびポート http://localhost:57772/ を使用しています。

  • システム, セキュリティ管理, ウェブ・アプリケーション ページで定義された Web アプリケーションの名前。DocServer サンプルの場合、この名前は /csp/samples/docserver ですが、URL として許容される任意のテキストを指定できます。

  • REST URL の残りの部分は、Route Url 要素で定義されます。Url 要素のセグメントの先頭が : (コロン) の場合は、そのセグメントがパラメータであることを意味します。パラメータはその URL セグメントのどの値とも一致します。この値は、パラメータとしてメソッドに渡されます。

前述の例の場合、TCP トレース・ユーティリティで以下のように完全な REST 呼び出しが示されます。

POST /csp/samples/docserver/echo HTTP/1.1
Host: localhost:57772

以下のルーティング定義では、URL 内で 2 つのパラメータ (ネームスペースとクラス) を定義しています。

<Route Url="/class/:namespace/:classname" Method="GET" Call="GetClass" />

REST 呼び出しの URL は /csp/samples/docserver/class/ で始まり、それに続く 2 つの URL の要素では 2 つのパラメータを指定します。GetClass メソッドは、クエリしているネームスペースおよびクラス名としてこれらのパラメータを使用します。例えば、以下の REST 呼び出しがあるとします。

http://localhost:57772/csp/samples/docserver/class/samples/Cinema.Review

これは、GetClass メソッドを呼び出し、パラメータ値として “samples“ と “Cinema.Review“ を指定しています。以下に GetClass メソッドの定義の冒頭部分を示します。

/// This method returns the class text for the named cache class
ClassMethod GetClass(
  pNamespace As %String,
  pClassname As %String) As %Status
{

単一の URL に対して、HTTP 要求メソッドごとに異なるメソッドを定義できます。例えば、以下のように定義できます。

<Route Url="/request" Method="GET" Call="GetRequest" />
<Route Url="/request" Method="POST" Call="PostRequest" />

このようなルーティングにより、HTTP GET メソッドで URL /csp/samples/docserver/request を呼び出したときには、GetRequest() メソッドが起動されます。HTTP POST メソッドで呼び出すと、PostRequest() メソッドが起動されます。DocServer サンプルでは、どちらの HTTP 要求メソッドも 1 つの Call メソッドで処理されます。このサンプルの、ルーティング定義を以下に示します。

<Route Url="/request" Method="GET" Call="Request" />
<Route Url="/request" Method="POST" Call="Request" />

この場合は、Request() メソッドにより、GET または POST のいずれかの呼び出しが処理されます。このメソッドで GET 操作と POST 操作を区別する必要がある場合は、URL のテキストが格納されている CSP 要求オブジェクトを調べます。

REST サービスを実装するコードを %CSP.RESTOpens in a new tab ディスパッチ・コードと区別する場合、REST サービスを実装するメソッドを別のクラスで定義し、Call 要素内でクラスとメソッドを指定できます。

Note:

URL 内でパラメータを定義する :parameter-name 構文は、正規表現を使用して実装されます。:parameter-name として指定される各セグメントは、正規表現内で一致するグループに変換されます。ほとんどの場合、この形式で REST URL の指定に十分な柔軟性を提供しますが、上級ユーザはルート定義に正規表現形式を直接使用することができます。この URL は、正規表現およびそれぞれの一致グループに合致している必要があります。これは、1 組の括弧によって指定され、メソッドに渡されるパラメータを定義します。:parameter-name 構文は、正規表現内で “([^/]+)” に変換されます。この構文は、/ (スラッシュ) を除くすべての文字と一致します。したがって、GetClass サンプル Url="/class/:namespace/:classname" は、以下と同等です。

<Route Url="/class/([^/]+)/([^/]+)" Method="GET" Call="GetClass" />

ここでは、2 つのパラメータを指定する 2 つの一致グループがあります。URL のコンポーネントが値 “Direction_Up” または “Direction_Down” を持つようにするには、以下のようにルート・マップを定義します。

<Route Url="/controlVehicle/Direction_(Up|Down)" Method="POST" Call="Move" />

この定義では、一致グループの値であるため、パラメータは “Up” または “Down” のいずれかの値を持ちます。

Map 要素を用いた URLMap

Caché は受信する URL を Routes 中の各 Map 要素中の接頭語と比較します。そして最初の一致する Map 要素で指定された %CSP.RESTOpens in a new tab サブクラスへ受信 REST 呼び出しを転送します。そのクラスは URL の残りの部分を処理し、サービスを実装するメソッドを通常呼び出します。Map 要素は、以下の 2 つの部分で構成されます。

  • Prefix — 一致させる URL のセグメントを指定します。受信 URL には通常、一致するセグメントの後に他のセグメントがあります。

  • Forward — 一致するセグメントに続く URL セグメントを処理する %CSP.RESTOpens in a new tab の別のサブクラスを指定します。

3 つの Map 要素を含む以下の URLMap を考えてみます。

XData UrlMap
{
  <Routes>
    <Map Prefix="/coffee/sales" Forward="MyLib.coffee.SalesREST"/>
    <Map Prefix="/coffee/repairs" Forward="MyLib.coffee.RepairsREST"/>
    <Map Prefix="/coffee" Forward="MyLib.coffee.MiscREST"/>
  </Routes>
}

この UrlMap は 3 つの %CSP.RESTOpens in a new tab サブクラス (MyLib.coffee.SalesRESTMyLib.coffee.RepairsREST または MyLib.coffee.MiscREST) の 1 つに REST 呼び出しを転送します。

これらの REST サービスの 1 つを呼び出す完全な REST URL は、以下の部分で構成されます。

  • Caché サーバのサーバ名とポート (例えば、http://localhost:57772/)。

  • システム, セキュリティ管理, ウェブ・アプリケーション ページで定義された Web アプリケーションの名前。例えば、上記 REST 呼び出しの Web アプリケーションは /coffeeRESTSvr と命名できます。

  • Map 要素内で定義された接頭語の 1 つ。

  • REST URL の残りの部分。これは転送された REST 要求を受信する %CSP.RESTOpens in a new tab サブクラスで処理される URL です。

例えば、以下の REST 呼び出しがあるとします。

http://localhost:57772/coffeeRESTSvr/coffee/sales/reports/id/875

これは Prefix /coffee/sales を有する 1 つ目のマップと一致し、REST 呼び出しを MyLib.coffee.SalesREST クラスへ転送します。そのクラスは URL の残りの部分 "/reports/id/875" で一致するものを探します。

別の例として、以下の REST 呼び出しがあるとします。

http://localhost:57772/coffeeRESTSvr/coffee/inventory/machinetype/drip

これは Prefix /coffee を有する 3 つ目のマップと一致し、REST 呼び出しを MyLib.coffee.MiscREST クラスへ転送します。そのクラスは URL の残りの部分 "/inventory/machinetype/drip" で一致するものを探します。

Note:

この URLMap の例で、Prefix="/coffee" の Map が最初のマップである場合、/coffee を有するすべての REST 呼び出しは、それ以降の Map 要素の 1 つに一致した場合でも、MyLib.coffee.MiscREST クラスへ転送されます。Routes 中の Map 要素の順序が重要です。

データ形式の指定

REST サービスは、さまざまな形式のデータ (JSON、XML、テキスト、CSV など) を処理するように定義できます。REST 呼び出しでは、HTTP 要求に ContentType 要素を指定することで、送信するデータに期待するフォームを指定できます。また、HTTP 要求に Accept 要素を指定することで返されるデータの形式を要求できます。

DocServer サンプルでは、REST 呼び出しが JSON データを要求したかどうかを以下のようにして GetNamespaces() メソッドで確認しています。

If $Get(%request.CgiEnvs("HTTP_ACCEPT"))="application/json"

REST での CSP セッションの使用

UseSession パラメータは、Caché が REST サービス呼び出しごとに新しい CSP セッションを使用するか、複数の REST サービスの呼び出しを通して 1 つの CSP セッションを保持するかを制御します。REST の目的の 1 つは、ステートレスにすることです。つまり、ある REST 呼び出しから次の呼び出しまでの間、サーバに情報を保存しないということです。複数の REST 呼び出しを通して 1 つの CSP セッションを保持することは、ステートレス・パラダイムを崩すことになりますが、1 つの CSP セッションを保持する理由が 2 つあります。

  • Caché のライセンス使用量を最小化する — 各 REST 呼び出しで新しい CSP セッションを作成する場合は、個別の Caché ライセンスが必要になります。Caché は、短いタイムアウト期間の経過後にライセンスを解放します。ほとんど発生しない REST 呼び出しを行う場合、これが問題になることは通常ありませんが、短期間のうちに多数の REST 呼び出しを行うと、システムで利用可能なライセンス数を超過してしまうことがあります。複数の REST 呼び出しに同一の CSP セッションを使用する場合、そのセッションが消費するライセンスは 1 つのみになります。

  • 複数の REST 呼び出し間でデータを保持する — 場合によっては、複数の REST 呼び出し間でデータを保持することが、ビジネス要件を効率的に満たすために必要になることがあります。

複数の REST 呼び出し間で 1 つの CSP セッションを使用できるようにするには、CSP Web アプリケーションのディスパッチ・クラスとして定義された %CSP.RESTOpens in a new tab のサブクラスで UseSession パラメータを 1 に設定します。例えば、以下のようになります。

Class REST.MyServices Extends %CSP.REST { 
Parameter UseSession As Integer = 1

REST での認証

REST サービスで機密データにアクセスする場合は、認証を使用する必要があります。以下に示す 2 つの認証形式のどちらかを使用できます。

  • HTTP 認証ヘッダ — これは、REST サービスに推奨されている認証形式です。

  • CSP セッション認証 — URL の後に続く疑問符でユーザ名とパスワードを指定します。

FeedbackOpens in a new tab