プロダクション内での Web サービスの作成

全般的な動作

プロダクション 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 メソッドの基本的な要件を説明します。

• “基本要件 ” で説明されているとおり、EnsLib.SOAP.ServiceOpens in a new tab のサブクラスでメソッドを定義します。

• メソッドに WebMethod キーワードでマーキングします。

• すべての引数および戻り値が XML に対応していることを確認します。

  • メソッドが引数または戻り値としてオブジェクトを使用している場合は、そのオブジェクトが XML に対応していることを確認します。つまり、タイプに対するクラス定義が %XML.AdaptorOpens in a new tab を拡張している必要があります。このクラスのデフォルト設定で通常は適切ですが、そうでない場合は、"オブジェクトの XML への投影" を参照してください。

  • メソッドが引数または戻り値としてデータ・セットを使用している場合は、データ・セットのタイプが %XML.DataSetOpens in a new tab であることを確認する必要があります。

  • 引数または戻り値としてコレクション (%ListOfObjectsOpens in a new tab または %ArrayOfObjectsOpens in a new tab) を使用するには、コレクションの ELEMENTTYPE パラメータが設定され、XML に対応するクラスを参照することを確認する必要があります。

その他の注意事項は、“Web サービスの作成” の “基本要件” を参照してください。

呼び出し側へのフォールトの返信

デフォルトでは、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)

ここで、

• pCode は、SOAP フォールトの <faultcode> 要素で使用する、エラー・コードを表す文字列です。ReturnMethodStatusFault() メソッドは、汎用エラー・コード SOAP-ENV:Method を使用します。

• pStatus は、返される SOAP フォールトで使用するステータスです。これは、SOAP フォールトの詳細を作成するために使用されます。

また、これらのメソッドは 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 サービスは InterSystems IRIS Web アプリケーション内で実行されます。その Web アプリケーションは、ユーザが選択した Web サーバ (管理ポータルを処理するのと同じ Web サーバ) により処理されます。

InterSystems IRIS は、Web サービスについて記述する WSDL ドキュメントを自動的に作成および発行します。Web サービスの修正やリコンパイルを行うたびに、InterSystems IRIS は対応する WSDL を自動的に更新します。

URL の形式は以下のとおりです。<baseURL> はインスタンスのベース URL です。

https:<baseURL>/csp/app/web_serv.cls?WSDL

/csp/app は Web サービスが存在する Web アプリケーションの名前、web_serv は Web サービスのクラス名です。(一般的に、/csp/app は /csp/namespace です。namespace は、Web アプリケーションとプロダクションが存在するネームスペースです。)

以下に例を示します。

https://devsys/csp/mysamples/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 サービス (ビジネス・サービス) を追加するには、管理ポータルを使用して以下の操作を行います。

1. カスタム・クラスのインスタンスをプロダクションに追加します。

   Important:

   構成名が、パッケージを含む完全なクラス名と同じであることを確認します。これは、プロダクション Web サービスを実行するための要件です。

2. ビジネス・サービスを有効化します。

3. プール・サイズの設定を 0 にします。

   その他の設定については、"プロダクションの構成" を参照してください。

4. プロダクションを実行します。