SOAP Web サービスの作成
この章では、Caché における Web サービスの作成方法の基本について説明します。ここでは、以下のトピックについて説明します。
Web サービスに関連する URL の一覧表については、最初の付録を参照してください。
Caché Web サービスの概要
Caché で Web サービスを作成するには、%SOAP.WebServiceOpens in a new tab を拡張するクラスを作成します。このクラスによって、SOAP プロトコル経由で呼び出し可能な 1 つ以上のメソッドの作成に必要なすべての機能が提供されます。さらに、このクラスは SOAP に関連するブックキーピング (サービスを記述している WSDL ドキュメントの管理など) の管理を自動化します。
このクラスは、%CSP.PageOpens in a new tab クラスから派生します。したがって、すべての Web サービス・クラスは HTTP 要求に応答できます。%SOAP.WebServiceOpens in a new tab クラスは、以下を実行するための HTTP イベントに応答するメソッドを実装します。
-
Web サービスの WSDL ドキュメントを、XML ドキュメントとして発行します。
-
Web サービスとそのメソッドについて説明するカタログ・ページを、(HTML を使用して) 人が読める形式で発行します。このページの説明では、クラス定義に含まれるコメントが示されます。
基本要件
Caché で Web サービスを作成および発行するには、次の基本要件を満たす Caché クラスを作成してコンパイルします。
-
クラスは %SOAP.WebServiceOpens in a new tab を拡張したものである必要があります。
-
クラスによって SERVICENAME パラメータを定義する必要があります。このパラメータが定義されていないクラスは、Caché でコンパイルされません。
-
このクラスによって、WebMethod キーワードを使用してマークを付けるメソッドまたはクラス・クエリを定義する必要があります。
Important:ほとんどの場合、Web メソッドはインスタンス・メソッドにする必要があります。通常、Web メソッドでは、Web サービス・インスタンスのプロパティを設定し、そのインスタンスのメソッドを呼び出して (詳細はこの後の章で説明)、メソッドの動作を調整する必要があります。クラス・メソッドではこれらのタスクを実行できないので、クラス・メソッドは一般に Web メソッドとしては適していません。
-
Web メソッドの場合、メソッド・シグニチャ内の各値に XML プロジェクションがあることを確認してください。例えば、メソッドに以下のシグニチャがあったとします。
Method MyWebMethod(myarg as ClassA) as ClassB [ WebMethod ]
この場合、ClassA と ClassB の両方に XML 表現が含まれている必要があります。つまり、ほとんどの場合、これらのスーパークラス・リストに %XML.AdaptorOpens in a new tab が含まれていなければなりません。詳細は、"オブジェクトの XML への投影" を参照してください。Caché SOAP サポートは、このリストの後に示すように、コレクションおよびストリームに対して特別な処理を行います。
Web メソッドは、一般メソッドと同じ方法で ByRef キーワードと Output キーワードを指定できます (これらのキーワードの詳細は、"Caché オブジェクトの使用法" の “メソッド” の章を参照してください)。
-
これらの引数および返り値内に含まれる可能性のある値について考えてみましょう。XML では、印字不能文字、特に ASCII 32 未満の文字は許可されません (キャリッジ・リターン、改行、およびタブは XML で許可されるので例外です)。
許可されない印字不能文字を含める必要がある場合、タイプを %BinaryOpens in a new tab、(同等の) %xsd.base64BinaryOpens in a new tab、またはサブクラスとして指定します。この値は、XML にエクスポートされるときに、Base 64 のエンコードに自動的に変換されます (またはインポートされるときに、Base 64 のエンコードから自動的に変換されます)。
-
引数の既定の値を指定する場合に、メソッド・シグニチャを利用しないでください。メソッド・シグニチャを利用すると、既定値は無視され、代わりに NULL 文字列が使用されます。例えば、以下のメソッドを考えてみます。
Method TestDefaults(val As %String = "Default String") As %String [ WebMethod ]
このメソッドを Web メソッドとして呼び出す場合に、引数を指定しないと NULL 文字列が使用され、値 "Default String" は無視されます。
その代わりに、メソッドの実装の最初に、値をテストし、必要に応じて目的の既定を使用します。1 つの手法は、以下のとおりです。
if arg="" { set arg="Default String" }
通常通り、メソッド・シグニチャで既定値を示すことができますが、これは情報を提供することのみを目的とし、SOAP メッセージには影響を与えません。
-
Web メソッドで必要なすべての引数に対し、メソッド・シグニチャ内で REQUIRED プロパティ・パラメータを指定します。以下はその例です。
Method MyWebMethod(myarg as ClassA(REQUIRED=1)) as ClassB [ WebMethod ]
既定では、継承されたメソッドはすべて、スーパークラスによって Web メソッドとしてマーク付けされていても、一般メソッドとして扱われます (ただし、この章で後述する “既存の Caché Web サービスのサブクラスの作成” を参照してください)。
%XML.Adaptor を必要としない入力オブジェクトと出力オブジェクト
ほとんどの場合、Web メソッドへの入力または出力としてオブジェクトを使用するときは、そのオブジェクトは %XML.AdaptorOpens in a new tab を拡張したものでなければなりません。例外は以下のとおりです。
-
オブジェクトが、%ListOfDataTypesOpens in a new tab、%ListOfObjectsOpens in a new tab、%ArrayOfDataTypesOpens in a new tab、%ArrayOfObjectsOpens in a new tab、またはサブクラスの場合、Caché SOAP サポートは、そのオブジェクトを %XML.AdaptorOpens in a new tab が含まれているものとして暗黙的に扱います。これらのクラスのサブクラスを作成する必要はありません。ただし、以下の条件があります。
-
メソッド・シグニチャ内で、以下のように ELEMENTTYPE を指定する必要があります。
Method MyMethod() As %ListOfObjects(ELEMENTTYPE="MyApp.MyXMLType") [WebMethod] { //method implementation }
または、入力引数の場合は以下のとおりです。
Method MyMethod(input As %ListOfObjects(ELEMENTTYPE="MyApp.MyXMLType")) [WebMethod] { //method implementation }
-
ELEMENTTYPE で名前を指定したクラスがオブジェクト・クラスの場合、そのクラスは %XML.AdaptorOpens in a new tab から継承される必要があります。
-
-
オブジェクトがいずれかのストリーム・クラスの場合、Caché SOAP サポートは、そのオブジェクトを %XML.AdaptorOpens in a new tab が含まれているものとして暗黙的に扱います。そのストリーム・クラスのサブクラスを作成する必要はありません。
オブジェクトが文字ストリームの場合、Caché SOAP ツールは、そのタイプが文字列であると見なします。また、オブジェクトがバイナリ・ストリームの場合、ツールはそれを Base 64 でエンコードされたデータとして扱います。したがって、タイプ情報を指定する必要はありません。
入力または出力としての結果セットの使用法
結果セットは入力または出力として使用できますが、その方法は対象の Web クライアントによって異なります。
-
Web サービスと Web クライアントの両方が Caché を基盤とする場合や、いずれかが .NET を基盤とする場合、特殊な結果セット・クラスである %XML.DataSetOpens in a new tab を使用できます。これについては、“SOAP メッセージでのデータセットの使用” を参照してください。または、クラス・クエリを Web メソッドとして使用することもできます。XML 表現は自動的に %XML.DataSetOpens in a new tab と同じになります。
-
Java ベースの Web クライアントで使用できるようにクエリの結果を出力するには、%ListOfObjectsOpens in a new tab サブクラスを使用します。SAMPLES ネームスペースの SOAP.DemoOpens in a new tab に例があります。
簡単な例
このセクションでは、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 サービス・ウィザードでは、簡単なスタブが生成されます。
-
[ファイル]→[新規作成] をクリックします。
[新規作成] ダイアログ・ボックスが表示されます。
-
[一般] タブをクリックします。
-
[新規 Web サービス] をクリックしてから [OK] をクリックします。
ウィザードが表示されます。
-
パッケージ名、クラス名、および Web サービス名の値を入力します。これらの入力は必須です。
-
オプションで、ネームスペースの URI を編集します (またはこの初期値を後で変更します)。これは、Caché ネームスペースではなく、XML ネームスペースです。
-
オプションで、別の行にメソッド名のリストを入力します。
-
[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 つの手順でこの開発を行います。
-
SOAP ウィザードを使用して、WSDL を読み取り、Web サービス・クラスおよびサポートするすべてのクラスを生成します。
このウィザードでは、Web クライアント・クラスも生成できます (こちらのほうがより一般的です)。
このウィザードの使用の詳細は、このドキュメントで後述の “SOAP ウィザードの使用法” を参照してください。そのセクションで説明する手順に従い、さらにウィザード内の [ウェブ・サービスの作成] オプションを選択してください。
または、“%SOAP.WSDL.Reader クラスの使用法” の説明に従って、%SOAP.WSDL.ReaderOpens in a new tab クラスを使用します。
-
生成されたクラスを検証して、メソッド・シグニチャ内の %StringOpens in a new tab の値のいずれかに変更を加える必要があるかどうかを確認します。
ウィザードで WSDL を読み取る場合、Caché では文字列タイプの入出力を %StringOpens in a new tab として表現できることが前提となっていますが、そのように表現できないこともあります。文字列によっては、Caché の 32 KB という文字列の制限を超える可能性があります。
このドキュメントで後述する “生成されたクラスを長い文字列に合わせて調整する方法” を参照してください。
-
生成された 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 サービス・クラスで以下のパラメータに適切な値を使用していることを確認します。
SOAP ウィザードを使用して既存の WSDL から Web サービスを生成する場合、これらのパラメータはいずれも変更しないでください。
Web サービスの名前。この名前は、文字から開始し、英数字のみを使用する必要があります。
このパラメータが定義されていないクラスは、Caché でコンパイルされません。
Web サービスとそのコンテンツが他のサービスと競合しないように、Web サービスにターゲットのネームスペースを定義する URI。初期設定では、"http://tempuri.org" に設定されています。これは、SOAP 開発者が開発中に一時的なネームスペースとしてよく使用する URI です。
このパラメータを指定しないと、ターゲットのネームスペースは、"http://tempuri.org" となります。
Caché Web サービスには、要求メッセージを別のネームスペースに配置する方法は用意されていません。ただし、Caché Web クライアントにはこのような制限はありません。このドキュメントで後述する “メッセージのネームスペース” を参照してください。
応答メッセージのネームスペースを定義する URI。既定では、NAMESPACE パラメータで指定されるネームスペースと同じです。
Caché Web サービスには、応答メッセージを別のネームスペースに配置する方法は用意されていません。ただし、Caché Web クライアントにはこのような制限はありません。このドキュメントで後述する “メッセージのネームスペース” を参照してください。
Web サービスによって定義されたタイプのスキーマのネームスペース。このパラメータを指定しない場合、スキーマは Web サービスのターゲットのネームスペース (NAMESPACE、または既定の "http://tempuri.org") に配置されます。
Caché Web サービスには、要求メッセージのタイプを別のネームスペースに配置する方法は用意されていません。Caché Web クライアントにはこのような制限はありません。このドキュメントで後述する “タイプのネームスペース” を参照してください。
応答メッセージで使用されるタイプのネームスペースを定義する URI。既定では、TYPENAMESPACE パラメータで指定されるネームスペースと同じです。
このパラメータは、SoapBindingStyle が "document" (既定) の場合にのみ使用されます。
Caché Web サービス、または Caché Web クライアントのいずれも、応答メッセージのタイプのすべてが同一のネームスペースに属している必要があります。
Web サービスの WSDL で通知される SOAP のバージョン (複数可) を指定します。以下の値のいずれかを使用します。
-
"" — SOAP 1.1 または 1.2 の場合はこの値を使用します。
-
"1.1" — SOAP 1.1 の場合はこの値を使用します。これが既定値です。
-
"1.2" — SOAP 1.2 の場合はこの値を使用します。
Web サービスが SOAP 要求を受け取ると、Web サービスの SoapVersion プロパティは、その要求の SOAP バージョンと等しくなるよう更新されます。
また、このドキュメントで後述する “Web サービスで処理する SOAP バージョンの制限” の章も参照してください。
これらの値が WSDL に及ぼす影響の詳細は、付録 “生成された WSDL の詳細” を参照してください。
カタログおよびテスト・ページについて
Web サービス・クラスをコンパイルすると、クラス・コンパイラによって便利なカタログ・ページが作成されます。そのカタログ・ページを使用して、Web サービスを検証することができます。このカタログ・ページは簡易テストのページにリンクしています。
これらの CSP ページを表示するには、以下の操作を実行します。
-
スタジオで、Web サービス・クラスを表示します。
-
[ビュー]→[ブラウザで表示] をクリックします。
カタログ・ページがすぐに表示されます。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 メソッドがリンクと共に表示されます (適切な許可がある場合)。指定されたメソッドのリンクにテスト・ページが表示され、そこから限られた方法でメソッドをテストできます。
テスト・ページに関する注記
-
SOAP 要求は表示できません。
-
このテスト・ページは、SOAP 経路を完全にテストするわけではありません。つまり、この章の後述部分で説明される SOAP ログなどは作成されません。
-
簡単なリテラル入力のみを受け付けるので、引数がオブジェクト、コレクション、またはデータセットとなっているメソッドの呼び出しには使用できません。
このドキュメントでは、このページについてこれ以上は説明しません。Web サービスをより完全にテストするには、このドキュメントで後述するとおり、Web クライアントを生成して使用します。
WSDL の表示
Web サービスの定義に %SOAP.WebServiceOpens in a new tab を使用すると、その Web サービスを記述した WSDL ドキュメントが作成されて発行されます。Web サービスを変更してリコンパイルするたびに、それに応じて WSDL が自動的に更新されます。このセクションでは、以下の項目について説明します。
最初の章の “Caché における WSDL のサポート” も参照してください。
定義により、Web サービスとその Web クライアントは、それぞれの実装にかかわらず (また、テクノロジの根本的な変更にかかわらず)、共通インタフェースに準拠する必要があります。WSDL とは、このインタフェースに関する標準準拠の記述のことです。次に示す事項に注意してください。
-
実際には、わずかに異なる複数の WSDL ドキュメントで、1 つの SOAP インタフェースを正しく記述できることが多くあります。
そのため、Caché で生成した WSDL は、Caché のバージョンごとに、わずかに異なることがあります。このような相違点については、このドキュメントでは説明していません。インターシステムズでは、W3C 仕様で要求されている Web サービスと、そのサービスに対応するクライアントとの相互運用性のみを保証しています。
-
W3C 仕様では、適合するインタフェースを記述する WSDL を生成できることを、Web サービスまたは Web クライアントのどちらに対しても要求していません。
利便性のために、WSDL ドキュメントが生成され、特定の URL で提供されます。ただし、WSDL を収容している Web アプリケーションが、パスワード認証や SSL 接続を要求する場合、この方法で WSDL にアクセスすることは実用的とはいえません。このような場合は、WSDL をファイルにダウンロードして、このファイルを代わりに使用する必要があります。また、前述したように、生成された WSDL には、実行時に追加される SOAP ヘッダに関する情報が含まれていません。実行時に追加される SOAP ヘッダに関する情報を WSDL ドキュメントに含める必要がある場合は、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 です)。
クラス名内のパーセント記号 (%) は、この URL ではアンダースコア文字 (_) に置き換えられます。
以下はその例です。
http://localhost:57772/csp/samples/MyApp.StockService.cls?WSDL
ブラウザに WSDL ドキュメントが表示されます。以下に例を示します。
すべてのブラウザでスキーマが正しく表示されるわけではありません。実際のスキーマを確認するには、ページのソースの表示が必要になることもあります。例えば、Firefox では右クリックして [ページのソースを表示] を選択します。
WSDL の生成
WSDL は静的ドキュメントとしても生成できます。%SOAP.WebServiceOpens in a new tab クラスには、そのために使用できるメソッドがあります。
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 に含まれないようにすることができます。これを実行するには、以下のいずれかを実行します。
-
Web サービスの FileWSDL() メソッドを使用して WSDL を生成します。前のセクションを参照してください。このメソッドは、WSDL に内部 Web メソッドが含まれるかどうかを制御する引数を提供します。
-
Web サービス・クラスの SOAPINTERNALWSDL クラス・パラメータを 0 に指定してください (このクラス・パラメータの既定値は 1 です)。