プロダクション内での Web サービスの作成
この章では、プロダクションの Web サービスである、プロダクション Web サービスを作成する方法について説明します。この操作を行うと、プロダクションに SOAP 対応のインタフェースが提供されます。
このドキュメントに記載されていない設定は、"プロダクションの管理" の “すべてのプロダクションに含まれる設定” を参照してください。
代替方法については、付録 “SOAP 受信アダプタの使用法” を参照してください。
Tip:
InterSystems IRIS® では、SOAP を使用する特殊なビジネス・サービス・クラスとユーザのニーズに適したビジネス・サービス・クラスの 1 つも提供されます。そのため、プログラミングの必要がありません。"相互運用プロダクションの概要" の “接続オプション” を参照してください。
全般的な動作
プロダクション Web サービスは、EnsLib.SOAP.ServiceOpens in a new tab またはサブクラスを基本としています。このクラスは、Ens.BusinessServiceOpens in a new tab と %SOAP.WebServiceOpens in a new tab の両方を拡張します。前者を拡張することで、このクラスはビジネス・サービスとなり、後者を拡張することで、このクラスは Web サービスとしても機能できるようになります。プロダクション Web サービスは、以下のように動作します。
-
これは Web サービスであるため、その中で使用できる Web メソッドを記述している WSDL ドキュメント (自動的に生成されます) を保持しています。このサービスは、WSDL に準拠する任意の SOAP メッセージを受信し、これに応じて SOAP 応答を送信できます。
-
これはビジネス・サービスなので、このサービスを追加するプロダクションの不可欠な要素となります。監視、エラー・ログ、実行時パラメータ、およびその他のすべてのプロダクション機能が通常どおりに使用できます。
Note:
プロダクション Web サービスは、プロダクションが実行中でないと (また、ビジネス・サービスが有効化されていないと) 使用できません。
外部とのやり取りは、SOAP 要求メッセージおよび応答メッセージによって行われます。InterSystems IRIS Interoperability 要求メッセージおよび応答メッセージは、プロダクション内で使用されます。
基本要件
プロダクション内に Web サービスを作成するには、ここに記載されているように新しいビジネス・サービス・クラスを作成します。後で、それをプロダクションに追加して、構成します。
存在しなければ、適切なメッセージ・クラスを作成する必要もあります。"プロダクションの開発" の “メッセージの定義” を参照してください。
ビジネス・サービス・クラスの基本要件を以下に列挙します。
-
このクラスは EnsLib.SOAP.ServiceOpens in a new tab を拡張します。このクラスは、Ens.BusinessServiceOpens in a new tab と %SOAP.WebServiceOpens in a new tab の両方を拡張します。前者を拡張することで、このクラスはビジネス・サービスとなり、後者を拡張することで、このクラスは Web サービスとしても機能できるようになります。
-
このクラスは ADAPTER パラメータを NULL ("") として定義します。以下に例を示します。
Parameter ADAPTER = "";
または、以下も同じ意味です。
Parameter ADAPTER;
-
このクラスは、その他のパラメータを次の値に指定します。
パラメータ |
説明 |
SERVICENAME |
Web サービスの名前。文字から始まり、英数字のみを含む名前でなければなりません。デフォルトのサービス名は "MyProductionRequestWebService" です。 |
NAMESPACE |
サービスおよびそのコンテンツが別のサービスと競合しないように、Web サービスのターゲットの XML ネームスペースを定義する URI。最初は http://tempuri.org に設定されています。これは、SOAP 開発者が開発中に使用した暫定的な URI です。 |
TYPENAMESPACE |
Web サービスによって定義されるタイプにおけるスキーマの XML ネームスペース。このパラメータを指定しない場合、スキーマは、NAMESPACE で指定されるネームスペースにあります。 |
RESPONSENAMESPACE |
応答メッセージの XML ネームスペースを定義する URI。デフォルトでは、これは NAMESPACE パラメータで指定されるネームスペースと同じです。 |
-
このクラスは、“Web メソッドの定義” で説明するように、Web メソッドを定義します。
-
その他のオプションと一般情報は、"プロダクションの開発" の “ビジネス・サービス・クラスの定義” を参照してください。
以下は、一般的なクラスの例です。
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.
}
}
InterSystems IRIS で使用する Web メソッドの定義
この節では、InterSystems IRIS Web メソッドの基本的な要件を説明します。
Important:
多くの場合、Web メソッドはインスタンス・メソッドにする必要があります。Web メソッド内では、メソッドの動作を調整するために、しばしば Web サービス・インスタンスのプロパティを設定してからメソッドを呼び出すことが必要となります。クラス・メソッドでは、これらの作業をできないため、多くの場合クラス・メソッドは Web メソッドに適していません。
関連する説明については、"Web サービスおよび Web クライアントの作成" の “Web サービスの作成” の章の “基本要件” を参照してください。
InterSystems IRIS Interoperability Web メソッドの基本的な手順
プロダクション Web サービス内で、Web メソッドは一般的に以下のことを行います。
-
受信 SOAP メッセージの情報を使って、要求メッセージを作成し、プロパティを設定します。
-
ビジネス・サービスの適切なメソッドを呼び出して、要求をプロダクション内の宛先に送信します。具体的には、SendRequestSync()、SendRequestAsync()、または (あまり一般的ではない) SendDeferredResponse() を呼び出します。詳細は、"プロダクションの開発" の “要求メッセージの送信” を参照してください。
これらの各メソッドは、ステータス (具体的には、%StatusOpens in a new tab のインスタンス) を返します。
-
前の手順で返されたステータスを確認して、適切に対応します。
-
次に、以下の手順を実行します。
-
成功した場合は、参照によって返された応答メッセージを調べ、そのメッセージを使用して 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: ObjectScript 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 フォールトを返信し、(設定に応じて) アラートを作成する例外を生成します。これらのメソッドには、以下のシグニチャがあります。
ClassMethod ReturnStatusFault(pCode As %String,
pStatus As %Status)
ClassMethod ReturnMethodStatusFault(pStatus As %Status)
ここで、
また、これらのメソッドは SOAP フォールトの <faultactor> 要素も設定します。
例
簡単な例を以下に示します。
Method GetCustomerInfo(ID As %Numeric) As ESOAP.SOAPResponse [WebMethod]
{
//create request message with given ID
set request=##class(ESOAP.CustomerRequest).%New()
set request.CustomerID=ID
//send request message
set sc= ..SendRequestSync("GetCustomerInfoBO",request,.response)
if $$$ISERR(sc) do ..ReturnMethodStatusFault(sc)
//use info from InterSystems IRIS 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 の表示
InterSystems IRIS は、プロダクション Web サービスについて記述する WSDL ドキュメントを自動的に作成および発行します。Web サービスの修正やリコンパイルを行うたびに、InterSystems IRIS は対応する WSDL を自動的に更新します。
Web サービスの WSDL を表示するには、以下の URL を使用します。
base/app-name/web_serv.cls?WSDL
ここで base は Web サーバのベース URL (必要に応じてポートを指定)、/csp/app は Web サービスが存在する Web アプリケーションの名前、web_serv は Web サービスのクラス名です。(一般的に、/csp/app は /csp/namespace です。namespace は、Web アプリケーションとプロダクションが存在するネームスペースです。)
以下に例を示します。
http://localhost:52773/csp/samples/MyApp.StockService.cls?WSDL
ブラウザに WSDL ドキュメントが XML ドキュメントとして表示されます。以下に例を示します。
Web サービス例
以下の例は、顧客 ID から顧客情報を検索するために使用するプロダクション 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 request message with given ID
set request=##class(ESOAP.CustomerRequest).%New()
set request.CustomerID=ID
//send request message
set sc= ..SendRequestSync("GetCustomerInfoBO",request,.response)
if $$$ISERR(sc) do ..ReturnMethodStatusFault(sc)
//use info from InterSystems IRIS 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() を使用して、プロダクションの別の場所にあるビジネス・オペレーションと通信します。このメソッドは応答メッセージを受信し、それを使用して SOAP 応答メッセージを作成します。
-
SOAP 応答クラスは、対応するプロダクション・メッセージ応答クラスと同じプロパティを持ちます。ただし、プロダクション・メッセージ応答と異なり、SOAP 応答クラスは XML 対応であり非永続的です。
SOAP セッションの有効化
SOAP 仕様には、セッション・サポートは含まれていません。ただし、Web クライアントと使用する Web サービスとの間でセッションを維持することが有用な場合がよくあります。プロダクション Web サービスを使用して、これを行うことができます。Web サービスがセッションを使用する場合、セッション ID が確立され、クライアントからの呼び出しが一度正しく認証されると、その後はサービスに対する繰り返しの呼び出しが許可されます。
SOAP セッションのサポートは、SOAPSESSION クラス・パラメータによって制御されます。デフォルトは 0 です。これは、Web サービスがセッションを使用しないことを意味します。
SOAP セッションを有効化するには、EnsLib.SOAP.ServiceOpens in a new tab のサブクラスを作成し、このサブクラスで SOAPSESSION を 1 に設定します。このサブクラスをプロダクション Web サービスの基本クラスにします。
SOAP セッションの詳細は、ドキュメントの "Web サービスおよび Web クライアントの作成" を参照してください。
その他のオプション
プロダクション Web サービスは %SOAP.WebServiceOpens in a new tab を拡張するので、そのクラスによって提供されるすべての SOAP サポートを使用できます。このサポートには、以下のカスタマイズ・オプションが含まれます。
-
SOAP ヘッダのカスタマイズ
-
SOAP メッセージにおけるアタッチメントの受け渡し
-
SOAP メッセージのバインディング・スタイルをドキュメント・スタイル (デフォルト) から RPC スタイルに変更
-
メッセージのエンコーディング・スタイルをリテラル・エンコーディング (デフォルト) から SOAP エンコーディングに変更
-
SOAP メッセージで使用される XML タイプのカスタマイズ
-
Web メソッドの呼び出しに使用される SOAPAction ヘッダのカスタマイズ
-
要素が限定要素かどうかの制御 (Web サービスの elementFormDefault 属性の制御)
-
NULL 引数のフォームの制御 (省略要素ではなく空の要素とする)
-
戻り値ではなく出力パラメータを持つ Web メソッドの記述
これらのオプションおよびその他のオプションについては、ドキュメント・セットの "Web サービスおよび Web クライアントの作成" を参照してください。
Web サービスの追加と構成
プロダクションにプロダクション Web サービス (ビジネス・サービス) を追加するには、管理ポータルを使用して以下の操作を行います。
-
カスタム・クラスのインスタンスをプロダクションに追加します。
Important:
構成名が、パッケージを含む完全なクラス名と同じであることを確認します。これは、プロダクション Web サービスを実行するための要件です。
-
ビジネス・サービスを有効化します。
-
プール・サイズの設定を 0 にします。
その他の設定については、"プロダクションの構成" を参照してください。
-
プロダクションを実行します。