Caché での Web サービスおよび Web クライアントの作成
SOAP Web サービスの作成
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

この章では、Caché における Web サービスの作成方法の基本について説明します。ここでは、以下のトピックについて説明します。

Web サービスに関連する URL の一覧表については、最初の付録を参照してください。
Caché Web サービスの概要
Caché で Web サービスを作成するには、%SOAP.WebService を拡張するクラスを作成します。このクラスによって、SOAP プロトコル経由で呼び出し可能な 1 つ以上のメソッドの作成に必要なすべての機能が提供されます。さらに、このクラスは SOAP に関連するブックキーピング (サービスを記述している WSDL ドキュメントの管理など) の管理を自動化します。
このクラスは、%CSP.Page クラスから派生します。したがって、すべての Web サービス・クラスは HTTP 要求に応答できます。%SOAP.WebService クラスは、以下を実行するための HTTP イベントに応答するメソッドを実装します。
基本要件
Caché で Web サービスを作成および発行するには、次の基本要件を満たす Caché クラスを作成してコンパイルします。
既定では、継承されたメソッドはすべて、スーパークラスによって Web メソッドとしてマーク付けされていても、一般メソッドとして扱われます (ただし、この章で後述する 既存の Caché Web サービスのサブクラスの作成 を参照してください)。
%XML.Adaptor を必要としない入力オブジェクトと出力オブジェクト
ほとんどの場合、Web メソッドへの入力または出力としてオブジェクトを使用するときは、そのオブジェクトは %XML.Adaptor を拡張したものでなければなりません。例外は以下のとおりです。
入力または出力としての結果セットの使用法
結果セットは入力または出力として使用できますが、その方法は対象の Web クライアントによって異なります。
簡単な例
このセクションでは、Web サービスの例、および Web サービスが認識できる要求メッセージと対応する応答メッセージの例を示します。
まず、Web サービスは以下のとおりです。
/// MyApp.StockService
Class MyApp.StockService Extends %SOAP.WebService 
{

/// Name of the WebService.
Parameter SERVICENAME = "StockService";

/// TODO: change this to actual SOAP namespace.
/// SOAP Namespace for the WebService
Parameter NAMESPACE = "http://tempuri.org";

/// Namespaces of referenced classes will be used in the WSDL.
Parameter USECLASSNAMESPACES = 1;

/// This method returns tomorrow's price for the requested stock
Method Forecast(StockName As %String) As %Integer [WebMethod]
{
    // apply patented, nonlinear, heuristic to find new price
    Set price = $Random(1000)
    Quit price
}
}
Web クライアントからこのメソッドを呼び出すと、クライアントによって SOAP メッセージが Web サービスに送信されます。この SOAP メッセージは以下のようになります (改行とスペースが、読みやすいように追加してあります)。
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope 
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
  <SOAP-ENV:Body>
    <Forecast xmlns="http://tempuri.org">
     <StockName xsi:type="s:string">GZP</StockName>
    </Forecast>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
メッセージ本文 (<SOAP-ENV:Body> 要素) には、<Forecast> という名前の要素が含まれています。これは、クライアントが呼び出しているメソッドの名前です。<Forecast> には、<StockName> という 1 つの要素が含まれています。この要素の名前は、呼び出している Web メソッドの引数の名前に基づいています。この要素には、その引数の実際の値が含まれます。
Web サービスでは、要求されたアクションを実行し、SOAP メッセージを応答として送信します。応答メッセージは、以下のようになります。
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope 
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' 
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
xmlns:s='http://www.w3.org/2001/XMLSchema'>
  <SOAP-ENV:Body>
    <ForecastResponse xmlns="http://www.myapp.org">
      <ForecastResult>799</ForecastResult>
    </ForecastResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
これらの例には、SOAP メッセージ自体の前に置かれる HTTP ヘッダは含まれていません。
Web サービスの生成
Web サービスは以下のいずれかの方法で作成できます。
Web サービス・ウィザードの使用法
Web サービス・ウィザードでは、簡単なスタブが生成されます。
  1. [ファイル]→[新規作成] をクリックします。
    [新規作成] ダイアログ・ボックスが表示されます。
  2. [一般] タブをクリックします。
  3. [新規 Web サービス] をクリックしてから [OK] をクリックします。
    ウィザードが表示されます。
  4. パッケージ名、クラス名、および Web サービス名の値を入力します。これらの入力は必須です。
  5. オプションで、ネームスペースの URI を編集します (またはこの初期値を後で変更します)。これは、Caché ネームスペースではなく、XML ネームスペースです。
  6. オプションで、別の行にメソッド名のリストを入力します。
  7. [OK] をクリックします。
Web メソッドのスタブを含む新しい Web サービス・クラスが作成されました。以下はその例です。
/// MyApp.StockService
Class MyApp.StockService Extends %SOAP.WebService 
{

/// Name of the WebService.
Parameter SERVICENAME = "StockService";

/// TODO: change this to actual SOAP namespace.
/// SOAP Namespace for the WebService
Parameter NAMESPACE = "http://tempuri.org";

/// Namespaces of referenced classes will be used in the WSDL.
Parameter USECLASSNAMESPACES = 1;

/// TODO: add arguments and implementation.
/// Forecast
Method Forecast() As %String [ WebMethod ]
{
   ;Quit "Forecast"
}

}
SOAP ウィザードと既存の WSDL の併用
WSDL が設計済みで、その WSDL に合わせて Web サービスを作成する必要がある場合もあります。これは、“WSDL-first の開発” と呼ばれています。Caché では、3 つの手順でこの開発を行います。
  1. SOAP ウィザードを使用して、WSDL を読み取り、Web サービス・クラスおよびサポートするすべてのクラスを生成します。
    このウィザードでは、Web クライアント・クラスも生成できます (こちらのほうがより一般的です)。
    このウィザードの使用の詳細は、このドキュメントで後述の SOAP ウィザードの使用法 を参照してください。そのセクションで説明する手順に従い、さらにウィザード内の [ウェブ・サービスの作成] オプションを選択してください。
    または、%SOAP.WSDL.Reader クラスの使用法 の説明に従って、%SOAP.WSDL.Reader クラスを使用します。
  2. 生成されたクラスを検証して、メソッド・シグニチャ内の %String の値のいずれかに変更を加える必要があるかどうかを確認します。
    ウィザードで WSDL を読み取る場合、Caché では文字列タイプの入出力を %String として表現できることが前提となっていますが、そのように表現できないこともあります。文字列によっては、Caché の 32 KB という文字列の制限を超える可能性があります。
    このドキュメントで後述する 生成されたクラスを長い文字列に合わせて調整する方法 を参照してください。
  3. 生成された Web サービスで、必要なアクションを実行するようにメソッドを編集します。
    当初、各メソッドは次の例のようなスタブです。
    Method Add(a As Test.ns2.ComplexNumber, b As Test.ns2.ComplexNumber) As Test.ns2.ComplexNumber 
    [ Final, SoapAction = "http://www.mynamespace.org/GSOAP.AddComplexWS.Add", 
    SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
    {
     // Web Service Method Implementation Goes Here.
    }
    ウィザードには、Final や SoapBindingStyle などのコンパイラ・キーワードが含まれます。これらのキーワードの値は変更しないでください。
WSDL に WS-Policy 要素が含まれている場合、ウィザードでは、Web サービスの構成クラスも生成されます。既定の構成クラス名は、Web サービス名に Config を追加したものです。WS-Policy については、"Caché Web サービスの保護" を参照してください。
既存の Caché Web サービスのサブクラスの作成
Web サービスを作成するには、既存の Caché Web サービス・クラスのサブクラスを作成してから、以下のようにクラスに SOAPMETHODINHERITANCE パラメータを追加します。
PARAMETER SOAPMETHODINHERITANCE = 1;
このパラメータの既定値は 0 です。このパラメータが 0 の場合、クラスは Web メソッドを Web メソッドとして継承しません。つまり、それらのメソッドは、一般メソッドとしては使用可能ですが、サブクラスによって定義された Web サービス内の Web メソッドとしてアクセスすることはできません。
このパラメータを 1 に設定した場合、クラスは、Web サービスであるスーパークラスで定義された Web メソッドを使用することができます。
Web サービスのパラメータの指定
Web サービス・クラスで以下のパラメータに適切な値を使用していることを確認します。
Note:
SOAP ウィザードを使用して既存の WSDL から Web サービスを生成する場合、これらのパラメータはいずれも変更しないでください。
SERVICENAME
Web サービスの名前。この名前は、文字から開始し、英数字のみを使用する必要があります。
このパラメータが定義されていないクラスは、Caché でコンパイルされません。
NAMESPACE
Web サービスとそのコンテンツが他のサービスと競合しないように、Web サービスにターゲットのネームスペースを定義する URI。初期設定では、"http://tempuri.org" に設定されています。これは、SOAP 開発者が開発中に一時的なネームスペースとしてよく使用する URI です。
このパラメータを指定しないと、ターゲットのネームスペースは、"http://tempuri.org" となります。
Caché Web サービスには、要求メッセージを別のネームスペースに配置する方法は用意されていません。ただし、Caché Web クライアントにはこのような制限はありません。このドキュメントで後述する メッセージのネームスペース を参照してください。
RESPONSENAMESPACE
応答メッセージのネームスペースを定義する URI。既定では、NAMESPACE パラメータで指定されるネームスペースと同じです。
Caché Web サービスには、応答メッセージを別のネームスペースに配置する方法は用意されていません。ただし、Caché Web クライアントにはこのような制限はありません。このドキュメントで後述する メッセージのネームスペース を参照してください。
TYPENAMESPACE
Web サービスによって定義されたタイプのスキーマのネームスペース。このパラメータを指定しない場合、スキーマは Web サービスのターゲットのネームスペース (NAMESPACE、または既定の "http://tempuri.org") に配置されます。
Caché Web サービスには、要求メッセージのタイプを別のネームスペースに配置する方法は用意されていません。Caché Web クライアントにはこのような制限はありません。このドキュメントで後述する タイプのネームスペース を参照してください。
RESPONSETYPENAMESPACE
応答メッセージで使用されるタイプのネームスペースを定義する URI。既定では、TYPENAMESPACE パラメータで指定されるネームスペースと同じです。
このパラメータは、SoapBindingStyle が "document" (既定) の場合にのみ使用されます。
Caché Web サービス、または Caché Web クライアントのいずれも、応答メッセージのタイプのすべてが同一のネームスペースに属している必要があります。
SOAPVERSION
Web サービスの WSDL で通知される SOAP のバージョン (複数可) を指定します。以下の値のいずれかを使用します。
Web サービスが SOAP 要求を受け取ると、Web サービスの SoapVersion プロパティは、その要求の SOAP バージョンと等しくなるよう更新されます。
また、このドキュメントで後述する Web サービスで処理する SOAP バージョンの制限 の章も参照してください。
これらの値が WSDL に及ぼす影響の詳細は、付録 生成された WSDL の詳細 を参照してください。
カタログおよびテスト・ページについて
Web サービス・クラスをコンパイルすると、クラス・コンパイラによって便利なカタログ・ページが作成されます。そのカタログ・ページを使用して、Web サービスを検証することができます。このカタログ・ページは簡易テストのページにリンクしています。
これらの CSP ページを表示するには、以下の操作を実行します。
  1. スタジオで、Web サービス・クラスを表示します。
  2. [ビュー]→[ブラウザで表示] をクリックします。
カタログ・ページがすぐに表示されます。URL は以下のような構造になっています。
base/csp/app/web_serv.cls
ここで、base は Web サーバのベース URL です (必要に応じてポートを含む)。/csp/app は Web サービスが格納されている Web アプリケーションの名前です。web_serv は Web サービスのクラス名です (通常、/csp/app/csp/namespace です)。以下はその例です。
http://localhost:57772/csp/samples/MyApp.StockService.cls
これらのページへのアクセス
これらの CSP ページは、前の章で説明したように、Caché Web アプリケーションの一部になります。現在使用しているネームスペースに Web アプリケーションが存在しない場合は、これらのページにアクセスできません。また、既定ではこれらのページにはアクセスできません。これらのページにアクセスできるようにするには、ターミナルを開いて %SYS ネームスペースに移動し、次のコマンドを入力します。
set ^SYS("Security","CSP","AllowClass",webapplicationname,"%SOAP.WebServiceInfo")=1
set ^SYS("Security","CSP","AllowClass",webapplicationname,"%SOAP.WebServiceInvoke")=1
webapplicationname は、末尾にスラッシュを付けた Web アプリケーションの名前です。例えば、"/csp/mynamespace/" のようになります。これにより、既定で、/csp/samples Web アプリケーションにアクセスできます。
また、これらのページは、%Development リソースに対する USE 特権を持つユーザとしてログインした場合にのみ使用できます。
これらのページに関する注意事項
カタログ・ページには、クラス名、ネームスペース、サービス名、およびクラスと Web メソッドについてのコメントが表示されます。[サービス記述] リンクでは、WSDL が表示されます。詳細は、この章で後述する WSDL の表示 のセクションを参照してください。次にページに Web メソッドがリンクと共に表示されます (適切な許可がある場合)。指定されたメソッドのリンクにテスト・ページが表示され、そこから限られた方法でメソッドをテストできます。
テスト・ページに関する注記
このドキュメントでは、このページについてこれ以上は説明しません。Web サービスをより完全にテストするには、このドキュメントで後述するとおり、Web クライアントを生成して使用します。
WSDL の表示
Web サービスの定義に %SOAP.WebService を使用すると、Caché によって、その Web サービスを記述した WSDL ドキュメントが作成されて発行されます。Web サービスを変更および再コンパイルするたびに、WSDL が自動的に更新されます。このセクションでは、以下の項目について説明します。
最初の章の Caché における WSDL のサポート も参照してください。
Important:
定義により、Web サービスとその Web クライアントは、それぞれの実装にかかわらず (また、テクノロジの根本的な変更にかかわらず)、共通インタフェースに準拠する必要があります。WSDL とは、このインタフェースに関する標準準拠の記述のことです。次に示す事項に注意してください。
WSDL の表示
Web サービスの WSDL を表示するには、次の URL を使用します。
base/csp/app/web_serv.cls?WSDL
ここで、base は Web サーバのベース URL です (必要に応じてポートを含む)。/csp/app は Web サービスが格納されている Web アプリケーションの名前です。web_serv は Web サービスのクラス名です (通常、/csp/app/csp/namespace です)。
Note:
クラス名内のパーセント記号 (%) は、この URL ではアンダースコア文字 (_) に置き換えられます。
以下はその例です。
http://localhost:57772/csp/samples/MyApp.StockService.cls?WSDL
ブラウザに WSDL ドキュメントが表示されます。以下に例を示します。
Important:
すべてのブラウザでスキーマが正しく表示されるわけではありません。実際のスキーマを確認するには、ページのソースの表示が必要になることもあります。例えば、Firefox では右クリックして [ページのソースを表示] を選択します。
WSDL の生成
WSDL は静的ドキュメントとしても生成できます。%SOAP.WebService クラスには、そのために使用できるメソッドがあります。
FileWSDL()
ClassMethod FileWSDL(fileName As %String, includeInternalMethods As %Boolean = 1) As %Status 
ここで、fileName はファイルの名前で、includeInternalMethods は、生成された WSDL に Internal としてマークされた Web メソッドが含まれるかどうかを指定します。
WSDL からの Internal Web メソッドの抑制
Web サービスに Internal とマークされている Web メソッドがある場合、既定では WSDL にこれらの Web メソッドが含まれます。これらのメソッドが WSDL に含まれないようにすることができます。これを実行するには、以下のいずれかを実行します。