Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

Ensemble Web クライアントの作成

この章では、Ensemble Web クライアントの作成方法を説明します。高レベルで、Ensemble Web クライアントはプロダクション内の他の場所から Ensemble 要求を受信し、SOAP 要求に変換して適切な Web サービスに送信します。同様に、SOAP 応答を受信して Ensemble 応答に変換し、プロダクション内の場所に送信します。この章では、以下のトピックについて説明します。

Tip:

Ensemble では、SOAP を使用する特殊なビジネス・サービス・クラスとユーザのニーズに適したビジネス・サービス・クラスの 1 つも提供されます。そのため、プログラミングの必要がありません。"Ensemble の紹介" の “接続オプション” を参照してください。

概要

Ensemble Web クライアントは、以下の要素で構成されます。

  • プロキシ・クライアント・クラス。Web サービスによって定義される各メソッドに対してプロキシ・メソッドを定義します。各プロキシ・メソッドは、対応する Web サービス・メソッドが使用するものと同じシグニチャを使用し、要求に応じてそのメソッドを呼び出します。

  • ビジネス・オペレーション。Ensemble SOAP 送信アダプタを使用して、プロキシ・クライアントを呼び出します。

  • サポート・クラス。XML タイプおよび Ensemble メッセージの定義に必要となります。

以下の図は、ビジネス・オペレーション、アダプタ、およびプロキシ・クライアント・クラスが連携して機能するしくみについて示しています。サポート・クラスはここには示されていません。

generated description: outbound

上の図で、点線で示されたすべての項目は、スタジオの SOAP クライアント・ウィザードで生成できます。このコードは、必要に応じて編集することができます。

これらの要素の詳細は、このドキュメントの “Ensemble による Web クライアントのサポート” を参照してください。

基本的な手順

この節では、Ensemble Web クライアントを作成するための基本的な手順を説明します。

Ensemble Web クライアントを作成するには、スタジオで以下の操作を行います。

  1. SOAP ウィザードを使用して、ビジネス・オペレーション・クラス、プロキシ・クライアント・クラス、およびサポート・クラスを生成します。このツールについては、この章の “SOAP ウィザードの使用法” で説明します。

  2. メソッドの入力および出力のタイプを調整する必要があるかどうかを確認します。特に、Web サービスのいずれかのメソッドの入力または出力の長さが 32KB を超える可能性がある場合、および Ensemble で長い文字列のサポートが有効でない場合は、その入力または出力のタイプを適切なストリーム・クラスに変更する必要があります。

SOAP ウィザードの使用法

SOAP ウィザードを使用して Ensemble Web クライアントを生成するには、以下の操作を行います。

  1. スタジオで、適切な Ensemble ネームスペースにいることを確認します。

  2. [ツール]→[アドイン]→[SOAP ウィザード] の順にクリックします。

  3. 最初の画面で、使用する Web サービスの WSDL ドキュメントの URL 全体を入力します。

  4. [次へ] をクリックします。

  5. [パッケージでビジネス・オペレーションを作成] の左側のチェックボックスにチェックを付けます。このオプションは、ウィザードで、プロキシ・クライアントを呼び出すビジネス・オペレーションクラス、およびそのビジネス・オペレーションと共に使用するメッセージ・クラスを定義するためのものです。

  6. [パッケージでビジネス・オペレーションを作成] で、必要に応じて、サブパッケージ名を BusOp から別の名前に変更します。

  7. [オプションのパッケージ名] に、プロキシ・クライアントおよび関連するクラスのパッケージ名を入力します。デフォルトのパッケージ名は、サービス名です。“生成されるクラスと XMLKEEPCLASS” も参照してください。

  8. [クラスの種類] で、プロキシ・クライアント・クラスの一般的なタイプ、つまり永続またはシリアル (デフォルト) を選択します。

  9. [次へ] をクリックします。ウィザードによってクラスが生成およびコンパイルされ、これらのクラスのリストが表示されます。

  10. [終了] をクリックします。

生成されるクラスと XMLKEEPCLASS

SOAP ウィザードによって、一連のクラスが生成されます。これらのクラスの詳細は、この章で後から説明します。

ツールがプロキシ・クライアント・クラスおよびサポート・クラスを作成する、パッケージを指定します。このパッケージが既存のパッケージと同じ場合、デフォルトでは、ツールは既存の同じ名前のクラスを上書きします。ウィザードによってクラス定義が上書きされないようにするには、そのクラスに XMLKEEPCLASS パラメータを追加し、このパラメータの値を 1 に設定します。

Process() メソッドの使用法

ウィザードを使用する代わりに、%SOAP.WSDL.ReaderOpens in a new tab クラスの Process() メソッドを使用できます。このメソッドを使用するには、以下を実行します。

  1. %SOAP.WSDL.ReaderOpens in a new tab のインスタンスを作成します。

  2. 必要に応じて、インスタンスの動作を制御するプロパティを設定します。

    プロパティ 目的
    CompileFlags 生成されたクラスをコンパイルするときに使用するフラグを指定します。最初の式は "dk" で、$System.OBJ.ShowFlags() を使用して利用可能なフラグに関する情報を取得します。
    MakePersistent このプロパティが 1 の場合、プロキシ・クライアントは永続オブジェクトです。それ以外の場合は登録オブジェクトです。最初の式は 0 です。
    MakeSerial このプロパティが 1 で、MakePersistent が 1 の場合、プロキシ・クライアントはシリアル・クラスです。最初の式は 0 です。
    OutputTypeAttribute WSDL リーダが、生成するプロキシ・クライアントの OUTPUTTYPEATTRIBUTE パラメータをどのように設定するかを制御します。これは、SOAP メッセージの xsi:type 属性の使用を制御します。Caché ドキュメント・セットの "Caché での Web サービスおよび Web クライアントの作成" を参照してください。
    MakeBusinessOperation Ensemble ビジネス・オペレーション、および関連する要求オブジェクトおよび応答オブジェクトを生成するかどうかを指定します。このビジネス・オペレーションの ADAPTER 設定は、EnsLib.SOAP.OutboundAdapterOpens in a new tab です。このオプションは、Ensemble 対応のネームスペース内で操作している場合のみ機能します。

    その他のプロパティについては、%SOAP.WSDL.ReaderOpens in a new tab のクラスに関するドキュメントを参照してください。

  3. Process() メソッドを呼び出し、以下の引数を提供します。

    • 最初の引数は、Web サービスの WSDL の URL または WSDL ファイルの名前 (完全なパスを含む) でなければなりません。Web サービスの構成によっては、適切なユーザ名とパスワードを提供する文字列を追加しなければならない場合があります。以下の例を参照してください。

    • オプションの 2 つ目の引数は、リーダが生成されたクラスを配置するパッケージの名前です。パッケージを指定しない場合、Caché はサービス名をパッケージ名として使用します。

Ensemble Web クライアントに対して生成されるクラス

この節では、SOAP ウィザードによって生成されるクラスについての情報を提供します。

例として、以下の条件を満たす MyService という名前の Web サービスについて考えてみましょう。

  • ホストは http://localhost:57772/csp/gsop/MyApp.AddService.CLS

  • この Web サービスのターゲット XML ネームスペースは http://www.myapp.org

  • この Web サービスは AddService という名前の Web メソッドを定義します。このメソッドは、引数として 2 つの複素数を受け取り、結果を返します。

ここでは、SOAP ウィザードを使用して、この Web サービスの Ensemble Web クライアントを生成すると想定します。このクライアントのクラスのパッケージを MyClient として指定すると、SOAP ウィザードは以下のクラスを生成し、これらすべてを現在のプロジェクトに追加します。

  • ビジネス・オペレーションを定義する、MyClient.BusOp.MyServiceSoap クラスを生成します。

    Class MyClient.BusOp.MyServiceSoap Extends Ens.BusinessOperation
    {
    
    Parameter ADAPTER = "EnsLib.SOAP.OutboundAdapter";
    
    Method Add(pRequest As MyClient.BusOp.AddRequest,
    Output pResponse As MyClient.BusOp.AddResponse) As %Library.Status
    {
       Set ..Adapter.WebServiceClientClass = "MyClient.MyServiceSoap"
       Set tSC = ..Adapter.InvokeMethod("Add",.AddResult,
    pRequest.a,pRequest.b) Quit:$$$ISERR(tSC) tSC
    
       Set tSC = pRequest.NewResponse(.pResponse) Quit:$$$ISERR(tSC) tSC
       Set pResponse.AddResult=AddResult
       Quit $$$OK
    }
    
    XData MessageMap
    {
    <MapItems>
        <MapItem MessageType="MyClient.BusOp.AddRequest">
            <Method>Add</Method>
        </MapItem>
    </MapItems>
    }
    
    }
    
  • プロキシ・クライアント・クラス、MyClient.AddServiceSOAP クラスを生成します。

    Class MyClient.AddServiceSoap Extends %SOAP.WebClient
    {
    
    /// This is the URL used to access the web service.
    Parameter LOCATION = "http://localhost:57772/csp/gsop/MyApp.AddService.cls";
    
    /// This is the namespace used by the Service
    Parameter NAMESPACE = "http://www.myapp.org";
    
    /// Use xsi:type attribute for literal types.
    Parameter OUTPUTTYPEATTRIBUTE = 1;
    
    /// This is the name of the Service
    Parameter SERVICENAME = "AddService";
    
    Method Add(a As MyClient.ComplexNumber, b As MyClient.ComplexNumber)
       As MyClient.ComplexNumber [ Final, 
       SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
    {
     Quit ..WebMethod("Add").Invoke($this,
          "http://www.myapp.org/MyApp.AddService.Add",.a,.b)
    }
    
    }
  • ビジネス・オペレーションに必要な要求および応答メッセージ・クラスを生成します。要求クラスは以下のとおりです。

    Class MyClient.BusOp.AddRequest Extends Ens.Request
    {
    
    Parameter RESPONSECLASSNAME = "MyClient.BusOp.AddResponse";
    
    Property a As MyClient.ComplexNumber;
    
    Property b As MyClient.ComplexNumber;
    
    }

    応答クラスは以下のとおりです。

    Class MyClient.BusOp.AddResponse Extends Ens.Response
    {
    
    Property AddResult As MyClient.ComplexNumber;
    
    }
    
  • 最後に、MyClient.ComplexNumber クラスを生成します。このクラスは複素数を定義し、その他のクラスによって使用されます。

    /// Created from: http://localhost:57772/csp/gsop/MyApp.AddService.CLS?WSDL=1
    Class MyClient.ComplexNumber Extends (%RegisteredObject, %XML.Adaptor)
    {
    Parameter XMLNAME = "ComplexNumber";
    
    Parameter XMLSEQUENCE = 1;
    
    Property Real As %xsd.double(XMLNAME = "Real") [ SqlFieldName = _Real ];
    
    Property Imaginary As %xsd.double(XMLNAME = "Imaginary");
    
    }

これらのクラスをコンパイルすると、コンパイラは、Web サービスで定義される各メソッドに対するクラスも生成します。これらのクラスはプロジェクトに自動的には追加されず、内容は変更される可能性があります。これらのクラスは %SOAP.ProxyDescriptorOpens in a new tab を拡張します。ユーザは、このクラスに対して自分でサブクラスを作成しないでください。

手動でのビジネス・オペレーション・クラスの作成

SOAP ウィザードによって生成されるビジネス・オペレーション・クラスを使用する代わりに、独自のクラスを作成できます。この節では、その方法について説明します。以下について説明します。

クラスの基本要件

ビジネス・オペレーション・クラスの基本要件を以下に列挙します。

  • ビジネス・オペレーション・クラスは、Ens.BusinessOperationOpens in a new tab を拡張するものでなければなりません。

  • クラスの ADAPTER パラメータは EnsLib.SOAP.OutboundAdapterOpens in a new tab である必要があります。

  • クラスの INVOCATION パラメータは、使用する呼び出しスタイルを指定する必要があります。以下のいずれかを使用します。

    • Queue は、メッセージが 1 つのバックグラウンド・ジョブ内で作成され、元のジョブが解放された段階でキューに配置されることを意味します。その後、メッセージが処理された段階で、別のバックグラウンド・ジョブがそのタスクに割り当てられます。これは最も一般的な設定です。

    • InProc は、メッセージが、作成されたジョブと同じジョブで生成、送信、および配信されることを意味します。このジョブは、メッセージが対象に配信されるまで送信者のプールに解放されません。これは特殊なケースのみに該当します。

  • 以下の節で説明するように、クラスでは、プロキシ・クライアントの各メソッドに対して 1 つのメソッドを定義します。

  • クラスでは、各メソッドに対して 1 つのエントリを含むメッセージ・マップを定義します。メッセージ・マップは、以下の構造を持つ XData ブロック・エントリです。

    XData MessageMap
    {
    <MapItems>
      <MapItem MessageType="messageclass">
        <Method>methodname</Method>
      </MapItem>
      ...
    </MapItems>
    }
    
    

また、ビジネス・オペレーションが使用する Ensemble メッセージ・クラスも定義する必要があります。

メソッドの基本要件

ビジネス・オペレーション・クラスにおいて、メソッドがプロキシ・メソッドを呼び出す必要があります。一般的な要件は以下のとおりです。

  1. このメソッドは、呼び出しているプロキシ・メソッドと同じシグニチャを持つ必要があります。

  2. このメソッドには、WebMethod キーワードでマーキングする必要があります。

  3. このメソッドは、プロキシ・クライアントによって期待される、SoapBindingStyle キーワードおよび SoapBodyUse キーワードを設定する必要があります。(つまり、対応するプロキシ・メソッドのシグニチャと同じ値を使用します。)

  4. このメソッドは、アダプタの WebServiceClientClass プロパティを設定する必要があります。このプロパティが設定されている場合、プロキシ・クライアントのインスタンスが作成され、アダプタの %Client プロパティ内に配置されます。

  5. このメソッドは、次の節で説明するいずれかの方法で、対応するプロキシ・メソッドを呼び出す必要があります。

  6. このメソッドは、ステータスを確認する必要があります。

  7. 次に、以下の手順を実行します。

    • 成功した場合は、(要求の NewResponse() メソッドを介して) 新しい応答メッセージを作成し、適切にプロパティを設定します。

    • 失敗した場合は、エラーが表示されて停止します。

プロキシ・メソッドを実行する方法

ビジネス・オペレーションにおいて、メソッドが、プロキシ・クライアント・クラスのプロキシ・メソッドを実行する必要があります。これには何通りかの方法があるので、例を使用して説明します。この節では、GetStock という名前の Web メソッドを持つサンプル Web サービスを使用します。このメソッドは、ストック・シンボル (文字列) を受け取り、数値を返します。SOAP ウィザードを使用して、GetStock という名前のメソッドを含むプロキシ・クライアント (GetStock.StockServiceSoap) を生成済みであると想定します。

また、以下のようにメッセージ・クラスを作成したものとします。

Class GetStock.BusOp.GetQuoteRequest Extends Ens.Request
{

Parameter RESPONSECLASSNAME = "GetStock.BusOp.GetQuoteResponse";

Property StockName As %String;

}

および

Class GetStock.BusOp.GetQuoteRequest Extends Ens.Request 
{

Parameter RESPONSECLASSNAME = "GetStock.BusOp.GetQuoteResponse";

Property StockName As %String;

}

プロキシ・メソッド GetStock を実行するために、ビジネス・オペレーション・クラスは、以下のいずれかを行うことができます。

  • アダプタの InvokeMethod() メソッドを呼び出し、実行するプロキシ・メソッドの名前、および任意の数の引数を指定します。この場合、引数は 1 つだけ (pRequest.StockName) です。以下に例を示します。

    Method GetQuote1(pRequest As GetStock.BusOp.GetQuoteRequest,
    Output pResponse As GetStock.BusOp.GetQuoteResponse) As %Status
    {
     set ..Adapter.WebServiceClientClass = "GetStock.StockServiceSoap"
    
     set status = ..Adapter.InvokeMethod("GetQuote",.answer,pRequest.StockName)
     if $$$ISERR(status) quit status
    
     set pResponse=##class(GetStock.BusOp.GetQuoteResponse).%New()
     set pResponse.GetQuoteResult=answer
     quit $$$OK
    }
    

    SOAP ウィザードを使用してビジネス・オペレーションを生成すると、そのビジネス・オペレーションではこのメソッドが使用されます。

  • アダプタの %Client プロパティにアクセスします。このプロパティによってプロキシ・クライアント・クラスのインスタンスが与えられ、そのプロパティのプロキシ・メソッドが実行されます。%Client プロパティは、WebServiceClientClass プロパティの設定時に設定されます。この場合、%Client には、文字列ストック・シンボルを受け取る、GetQuote という名前のメソッドがあります。以下に例を示します。

    Method GetQuote2(pRequest As GetStock.BusOp.GetQuoteRequest,
    Output pResponse As GetStock.BusOp.GetQuoteResponse) As %Status
    {
     set ..Adapter.WebServiceClientClass = "GetStock.StockServiceSoap"
    
     set client=..Adapter.%Client
     set answer=client.GetQuote("GRPQ")
    
     set pResponse=##class(GetStock.BusOp.GetQuoteResponse).%New()
     set pResponse.GetQuoteResult=answer
     quit $$$OK
    }

    この方法を使用する場合、Ensemble の再試行ロジックにはアクセスできません。

  • アダプタの WebMethod() メソッドを呼び出すことによって、プロキシ・メソッド・オブジェクトを作成します。このオブジェクトのプロパティを適切に設定します (名前のある引数ごとに 1 つのプロパティ)。ここでは、WebMethod() は、1 つのプロパティ (StockName) を持つオブジェクトを返します。必要に応じてプロパティを設定した後、オブジェクトの Invoke() メソッドを呼び出します。以下に例を示します。

    Method GetQuote3(pRequest As GetStock.BusOp.GetQuoteRequest,
    Output pResponse As GetStock.BusOp.GetQuoteResponse) As %Status
    {
     set ..Adapter.WebServiceClientClass = "GetStock.StockServiceSoap"
    
    
     set proxymethod=..Adapter.WebMethod("GetQuote")
     set proxymethod.StockName=pRequest.StockName
    
    
     set status=..Adapter.Invoke(proxymethod)
     if $$$ISERR(status) quit status
    
    
     set pResponse=##class(GetStock.BusOp.GetQuoteResponse).%New()
     set pResponse.GetQuoteResult=proxymethod.%Result
     quit $$$OK
    }
    

    この場合、任意の数だけ引数を提供できます。

参照情報

この節では、これまでに説明したアダプタ・プロパティおよびメソッドについての参照情報を提供します。

%Client プロパティ
%SOAP.WebClient 

プロキシ・クライアントの関連するインスタンス (%SOAP.WebClientOpens in a new tab のインスタンス)。このプロパティは、アダプタの WebServiceClientClass プロパティの設定時に設定されます。

InvokeMethod() メソッド
Method InvokeMethod(pMethodName As %String,
       Output pResult As %RegisteredObject,
       pArgs...) As %Status

すべての引数を渡してプロキシ・クライアント・クラスの指定されたメソッドを呼び出して、ステータスを返します。出力は、2 番目の引数として参照によって返されます。

WebMethod() メソッド
Method WebMethod(pMethodName As %String) As %SOAP.ProxyDescriptor

指定されたメソッドに対応するオブジェクトを返します。このオブジェクトには、各メソッド引数に対応する 1 つのプロパティがあります。Invoke() メソッドを使用する前に、このプロパティを設定します。%SOAP.ProxyDescriptorOpens in a new tab の詳細は、クラス参照を参照してください。

Invoke() メソッド
Method Invoke(pWebMethod As %SOAP.ProxyDescriptor) As %Status

指定されたメソッドを呼び出し、ステータスを返します。

Web クライアントの追加と構成

Ensemble プロダクションに Ensemble Web クライアントを追加するには、管理ポータルを使用して以下の操作を行います。

  1. カスタム・ビジネス・オペレーション・クラス、具体的には SOAP ウィザードによって生成されるビジネス・オペレーション・クラスのインスタンスを、Ensemble プロダクションに追加します。

  2. ビジネス・オペレーションを有効化します。

  3. 以下の説明に従って、関連するアダプタの実行時設定に適切な値を指定します。

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

以降の節では、Ensemble Web クライアントの実行時設定について説明します。実行時設定は、次のように複数の一般的なグループに分けられます。

このドキュメントに記載されていない設定は、"Ensemble プロダクションの管理" の “すべてのプロダクションに含まれる設定” を参照してください。

基本設定の指定

以下の設定は、Ensemble Web クライアントの基本的な情報を指定します。

資格情報の指定

Web サービスにアクセスするのに、ユーザ名とパスワードが必要な場合があります。通常、Ensemble SOAP クライアントは、以下のいずれかの方法で Web サービスにログインできます。

  • WS-Security ユーザ認証を使用できます。この場合、SOAP 要求に WS-Security ヘッダを含めます。このヘッダに、ユーザ名とパスワードを含めます。[SOAP認証情報] 設定の値を指定すると、プロキシ・クライアントによってこの操作が自動的に行われます。

    Caution:

    Web クライアントと Web サービスとの間で SSL を使用していることを確認します。WS-Security ヘッダはクリア・テキストで送信されるので、SSL が使用されていない場合、この方法は安全ではありません。

  • 基本的な HTTP ユーザ認証を使用することができます。WS-Security ほど安全性は高くありませんが、この方法が必要な場合もあります。この場合、SOAP 要求の HTTP ヘッダにユーザ名とパスワードを含めます。[認証情報] 設定の値を指定すると、プロキシ・クライアントによってこの操作が自動的に行われます。

使用する Web サービスに適した方法を使用してください。

SSL 構成の指定

Web サーバが SSL をサポートしている場合、これを使用して接続できます。そのためには、[SSL構成] 設定に対して値を指定します。

Note:

また、Web サービスが https:// を使用する URL にあることを確認する必要があります。Web サービスの場所は [ウェブサービスURL] 設定によって決まります。この設定が指定されていない場合、Ensemble Web クライアントは、プロキシ・クライアント・クラスの LOCATION パラメータによって指定される URL に Web サービスがあると仮定します。

プロキシ・サーバの指定

プロキシ・サーバを介して Web サービスと通信できます。これを設定するには、[プロキシ設定] グループの Proxy Server およびその他の設定を使用します。

FeedbackOpens in a new tab