Ensemble Web サービスの作成
この章では、Ensemble プロダクションの Web サービスである、Ensemble Web サービスを作成する方法について説明します。この操作を行うと、プロダクションに SOAP 対応のインタフェースが提供されます。この章では、以下について説明します。
このドキュメントに記載されていない設定は、"Ensemble プロダクションの管理" の “すべてのプロダクションに含まれる設定” を参照してください。
代替方法については、付録 “SOAP 受信アダプタの使用法” を参照してください。
Ensemble では、SOAP を使用する特殊なビジネス・サービス・クラスとユーザのニーズに適したビジネス・サービス・クラスの 1 つも提供されます。そのため、プログラミングの必要がありません。"Ensemble の紹介" の “接続オプション” を参照してください。
全般的な動作
Ensemble Web サービスは、EnsLib.SOAP.ServiceOpens in a new tab クラスまたはサブクラスを基本クラスとしています。このクラスは、Ens.BusinessServiceOpens in a new tab と %SOAP.WebServiceOpens in a new tab の両方を拡張します。前者を拡張することで、このクラスは Ensemble ビジネス・サービスとなり、後者を拡張することで、このクラスは Web サービスとしても機能できるようになります。Ensemble Web サービスは、以下のように動作します。
-
これは Web サービスであるため、その中で使用できる Web メソッドを記述している WSDL ドキュメント (自動的に生成されます) を保持しています。このサービスは、WSDL に準拠する任意の SOAP メッセージを受信し、これに応じて SOAP 応答を送信できます。
-
これは Ensemble ビジネス・サービスなので、このサービスを追加する Ensemble プロダクションの不可欠な要素となります。監視、エラー・ログ、実行時パラメータ、およびその他のすべての Ensemble 機能が通常どおりに使用できます。
Note:Ensemble Web サービスは、プロダクションが実行中でないと (また、ビジネス・サービスが有効化されていないと) 使用できません。
外部とのやり取りは、SOAP 要求メッセージおよび応答メッセージによって行われます。Ensemble 要求メッセージおよび応答メッセージは、プロダクション内で使用されます。
基本要件
Ensemble プロダクション内に Web サービスを作成するには、ここに記載されているように新しいビジネス・サービス・クラスを作成します。後で、それをプロダクションに追加して、構成します。
存在しなければ、適切なメッセージ・クラスを作成する必要もあります。"Ensemble プロファクションの開発" の “Ensemble メッセージの定義” を参照してください。
ビジネス・サービス・クラスの基本要件を以下に列挙します。
-
このクラスは EnsLib.SOAP.ServiceOpens in a new tab を拡張します。このクラスは、Ens.BusinessServiceOpens in a new tab と %SOAP.WebServiceOpens in a new tab の両方を拡張します。前者を拡張することで、このクラスは Ensemble ビジネス・サービスとなり、後者を拡張することで、このクラスは Web サービスとしても機能できるようになります。
-
このクラスは ADAPTER パラメータを NULL ("") として定義します。以下に例を示します。
Parameter ADAPTER = "";
または、以下も同じ意味です。
Parameter ADAPTER;
-
このクラスは、その他のパラメータを次の値に指定します。
パラメータ 説明 SERVICENAME Web サービスの名前。文字から始まり、英数字のみを含む名前でなければなりません。デフォルトのサービス名は "MyEnsembleRequestWebService" です。 NAMESPACE サービスおよびそのコンテンツが別のサービスと競合しないように、Web サービスのターゲットの XML ネームスペースを定義する URI。最初は http://tempuri.org に設定されています。これは、SOAP 開発者が開発中に使用した暫定的な URI です。 TYPENAMESPACE Web サービスによって定義されるタイプにおけるスキーマの XML ネームスペース。このパラメータを指定しない場合、スキーマは、NAMESPACE で指定されるネームスペースにあります。 RESPONSENAMESPACE 応答メッセージの XML ネームスペースを定義する URI。デフォルトでは、これは NAMESPACE パラメータで指定されるネームスペースと同じです。 -
このクラスは、“Web メソッドの定義” で説明するように、Web メソッドを定義します。
-
その他のオプションと一般情報は、"Ensemble プロダクションの開発" の “ビジネス・サービス・クラスの定義” を参照してください。
以下は、一般的なクラスの例です。
Class Hospital.MyService Extends EnsLib.SOAP.Service
{
///For this business service, ADAPTER should be "" so that we use the normal SOAP processing
Parameter ADAPTER = "";
Parameter SERVICENAME = "MyService";
Parameter NAMESPACE = "http://www.myhospital.org";
Parameter USECLASSNAMESPACES = 1;
Method GetAuthorization(patientID As %Integer, RequestedOperation As %String,
LikelyOutcome As %String) As %Status [ WebMethod ]
{
set request = ##class(Hospital.OperateRequest).%New()
set request.PatientID = patientID
set request.RequestedOperation = RequestedOperation
set request.LikelyOutcome = LikelyOutcome
set tSC=..SendRequestSync("Hospital.PermissionToOperateProcess",request,.response)
// Create the SOAP response, set its properties, and return it.
}
}
Ensemble で使用する Web メソッドの定義
この節では、Ensemble Web メソッドの基本的な要件を説明します。
-
“基本要件 ”で説明されているとおり、EnsLib.SOAP.ServiceOpens in a new tab のサブクラスでメソッドを定義します。
-
メソッドに WebMethod キーワードでマーキングします。
-
すべての引数および戻り値が XML に対応していることを確認します。
-
メソッドが引数または戻り値としてオブジェクトを使用している場合は、そのオブジェクトが XML に対応していることを確認します。つまり、タイプに対するクラス定義が %XML.AdaptorOpens in a new tab を拡張している必要があります。このクラスのデフォルト設定で通常は適切ですが、そうでない場合は、"オブジェクトの XML への投影" を参照してください。
-
メソッドが引数または戻り値としてデータ・セットを使用している場合は、データ・セットのタイプが %XML.DataSetOpens in a new tab であることを確認する必要があります。これは、標準の %ResultSetOpens in a new tab の XML に対応するサブクラスです。
-
引数または戻り値としてコレクション (%ListOfObjectsOpens in a new tab または %ArrayOfObjectsOpens in a new tab) を使用するには、コレクションの ELEMENTTYPE パラメータが設定され、XML に対応するクラスを参照することを確認する必要があります。
-
多くの場合、Web メソッドはインスタンス・メソッドにする必要があります。Web メソッド内では、メソッドの動作を調整するために、しばしば Web サービス・インスタンスのプロパティを設定してからメソッドを呼び出すことが必要となります。クラス・メソッドでは、これらの作業をできないため、多くの場合クラス・メソッドは Web メソッドに適していません。
関連する説明については、"Caché での Web サービスおよび Web クライアントの作成" の “Web サービスの作成” の章の “基本要件” を参照してください。
Ensemble Web メソッドの基本的な手順
Ensemble Web サービス内で、Web メソッドは一般的に以下のことを行います。
-
受信 SOAP メッセージの情報を使って、Ensemble 要求メッセージを作成し、プロパティを設定します。
-
ビジネス・サービスの適切なメソッドを呼び出して、要求をプロダクション内の宛先に送信します。具体的には、SendRequestSync()、SendRequestAsync()、または (あまり一般的ではない) SendDeferredResponse() を呼び出します。詳細は、"Ensemble プロダクションの送信" の “要求メッセージの定義” を参照してください。
これらの各メソッドは、ステータス (具体的には、%StatusOpens in a new tab のインスタンス) を返します。
-
前の手順で返されたステータスを確認して、適切に対応します。
-
次に、以下の手順を実行します。
-
成功した場合は、参照によって返された Ensemble 応答メッセージを調べ、そのメッセージを使用して Web メソッドの戻り値を作成します。以前説明したように、戻り値を SOAP 応答としてパッケージ化するには、戻り値が XML に対応していなければなりません。
-
失敗した場合は、Web サービスの ReturnMethodStatusFault() または ReturnStatusFault() メソッドを呼び出し、SOAP フォールトを返して、Ens.Alert を生成できるようにします。詳細は次の節を参照してください。
-
呼び出し側へのフォールトの返信
デフォルトでは、Web メソッドの実行中にエラーが発生すると、Web サービスは呼び出し側に SOAP メッセージを返しますが、このメッセージにはフォールトが発生した正確な場所が示されません。以下に例を示します。
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Server Application Error</faultstring>
<detail>
<error xmlns='http://www.myapp.org' >
<text>ERROR #5002: Cache error: <INVALID OREF>
zGetCustomerInfo+10^ESOAP.WebService.1</text>
</error>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Web メソッドでエラーを確認し、ReturnMethodStatusFault() または ReturnStatusFault() を使用します。以下のように、エラーが発生した場合には、メッセージに含まれる情報が多くなります。
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Method</faultcode>
<faultstring>Server Application Error</faultstring>
<faultactor>ESOAP.WebService</faultactor>
<detail>
<error xmlns='http://www.myapp.org' >
<text>ERROR <Ens>ErrException:
<DIVIDE>zGetCustomerRequest+8^ESOAP.MyOperation.1 -
logged as '13 Jul 2007' number 4 @' set x=100/0'</text>
</error>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
ReturnMethodStatusFault() および ReturnStatusFault() メソッドは、呼び出し側に SOAP フォールトを返信し、(設定に応じて) Ensemble アラートを作成する例外を生成します。これらのメソッドには、以下のシグニチャがあります。
ClassMethod ReturnStatusFault(pCode As %String,
pStatus As %Status)
ClassMethod ReturnMethodStatusFault(pStatus As %Status)
ここで、
-
pCode は、SOAP フォールトの <faultcode> 要素で使用する、エラー・コードを表す文字列です。ReturnMethodStatusFault() メソッドは、汎用エラー・コード SOAP-ENV:Method を使用します。
-
pStatus は、返される SOAP フォールトで使用するステータスです。これは、SOAP フォールトの詳細を作成するために使用されます。
また、これらのメソッドは SOAP フォールトの <faultactor> 要素も設定します。
例
簡単な例を以下に示します。
Method GetCustomerInfo(ID As %Numeric) As ESOAP.SOAPResponse [WebMethod]
{
//create Ensemble request message with given ID
set request=##class(ESOAP.CustomerRequest).%New()
set request.CustomerID=ID
//send Ensemble request message
set sc= ..SendRequestSync("GetCustomerInfoBO",request,.response)
if $$$ISERR(sc) do ..ReturnMethodStatusFault(sc)
//use info from Ensemble response to create SOAP response
set soapresponse=##class(ESOAP.SOAPResponse).%New()
set soapresponse.CustomerID=response.CustomerID
set soapresponse.Name=response.Name
set soapresponse.Street=response.Street
set soapresponse.City=response.City
set soapresponse.State=response.State
set soapresponse.Zip=response.Zip
quit soapresponse
}
WSDL の表示
Ensemble は、Ensemble Web サービスについて記述する WSDL ドキュメントを自動的に作成および発行します。Web サービスの修正やリコンパイルを行うたびに、Ensemble は対応する WSDL を自動的に更新します。
Web サービスの WSDL を表示するには、以下の URL を使用します。
base/app-name/web_serv.cls?WSDL
ここで base は Web サーバのベース URL (必要な場合はポートを含む)、/csp/app は Web サービスがある CSP アプリケーションの名前、web_serv は Web サービスのクラス名です。(一般的に、/csp/app は /csp/namespace です。ここで namespace は CSP アプリケーションを含む Ensemble ネームスペースです。)
以下に例を示します。
http://localhost:57772/csp/samples/MyApp.StockService.cls?WSDL
ブラウザに WSDL ドキュメントが XML ドキュメントとして表示されます。以下に例を示します。
Web サービス例
以下の例は、顧客 ID から顧客情報を検索するために使用する Ensemble Web サービスを示しています。
Class ESOAP.WebService Extends EnsLib.SOAP.Service
{
Parameter ADAPTER;
Parameter NAMESPACE = "http://www.myapp.org";
Parameter SERVICENAME = "CustomerLookupService";
Method GetCustomerInfo(ID As %Numeric) As ESOAP.SOAPResponse [WebMethod]
{
//create Ensemble request message with given ID
set request=##class(ESOAP.CustomerRequest).%New()
set request.CustomerID=ID
//send Ensemble request message
set sc= ..SendRequestSync("GetCustomerInfoBO",request,.response)
if $$$ISERR(sc) do ..ReturnMethodStatusFault(sc)
//use info from Ensemble response to create SOAP response
set soapresponse=##class(ESOAP.SOAPResponse).%New()
set soapresponse.CustomerID=response.CustomerID
set soapresponse.Name=response.Name
set soapresponse.Street=response.Street
set soapresponse.City=response.City
set soapresponse.State=response.State
set soapresponse.Zip=response.Zip
quit soapresponse
}
}
SOAP 応答クラスは以下のとおりです。
///
Class ESOAP.SOAPResponse Extends (%RegisteredObject, %XML.Adaptor)
{
Property CustomerID As %Numeric;
Property Name As %String;
Property Street As %String;
Property City As %String;
Property State As %String;
Property Zip As %Numeric;
}
以下の点に注意してください。
-
例の Web メソッド (GetCustomerInfo) は SendRequestSync() を使用して、プロダクションの別の場所にあるビジネス・オペレーションと通信します。このメソッドは Ensemble 応答メッセージを受信し、それを使用して SOAP 応答メッセージを作成します。
-
SOAP 応答クラスは、対応する Ensemble 応答クラスと同じプロパティを持ちます。ただし、Ensemble 応答と異なり、SOAP 応答クラスは XML 対応であり非永続的です。
SOAP セッションの有効化
SOAP 仕様には、セッション・サポートは含まれていません。ただし、Web クライアントと使用する Web サービスとの間でセッションを維持することが有用な場合がよくあります。Ensemble Web サービスを使用して、これを行うことができます。Web サービスがセッションを使用する場合、セッション ID が確立され、クライアントからの呼び出しが一度正しく認証されると、その後はサービスに対する繰り返しの呼び出しが許可されます。
SOAP セッションのサポートは、SOAPSESSION クラス・パラメータによって制御されます。デフォルトは 0 です。これは、Web サービスがセッションを使用しないことを意味します。
SOAP セッションを有効化するには、EnsLib.SOAP.ServiceOpens in a new tab のサブクラスを作成し、このサブクラスで SOAPSESSION を 1 に設定します。このサブクラスを Ensemble Web サービスの基本クラスにします。
SOAP セッションの詳細は、Caché ドキュメントの "Caché での Web サービスおよび Web クライアントの作成" を参照してください。
その他のオプション
Ensemble Web サービスは %SOAP.WebServiceOpens in a new tab を拡張するので、そのクラスによって提供されるすべての SOAP サポートを使用できます。このサポートには、以下のカスタマイズ・オプションが含まれます。
-
SOAP ヘッダのカスタマイズ
-
SOAP メッセージにおけるアタッチメントの受け渡し
-
SOAP メッセージのバインディング・スタイルをドキュメント・スタイル (デフォルト) から RPC スタイルに変更
-
メッセージのエンコーディング・スタイルをリテラル・エンコーディング (デフォルト) から SOAP エンコーディングに変更
-
SOAP メッセージで使用される XML タイプのカスタマイズ
-
Web メソッドの呼び出しに使用される SOAPAction ヘッダのカスタマイズ
-
要素が限定要素かどうかの制御 (Web サービスの elementFormDefault 属性の制御)
-
NULL 引数のフォームの制御 (省略要素ではなく空の要素とする)
-
戻り値ではなく出力パラメータを持つ Web メソッドの記述
これらのオプションおよびその他のオプションについては、Caché ドキュメント・セットの "Caché での Web サービスおよび Web クライアントの作成" を参照してください。
Web サービスの追加と構成
Ensemble プロダクションに Ensemble Web サービス (ビジネス・サービス) を追加するには、管理ポータルを使用して以下の操作を行います。
-
カスタム・クラスのインスタンスを Ensemble プロダクションに追加します。
Important:構成名が、パッケージを含む完全なクラス名と同じであることを確認します。これは、Ensemble Web サービスを実行するための要件です。
-
ビジネス・サービスを有効化します。
-
プール・サイズの設定を 0 にします。
その他の設定については、"Ensemble プロダクションの構成" を参照してください。
-
プロダクションを実行します。