Caché での Web サービスおよび Web クライアントの作成
Web クライアントの作成
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Web クライアントは、Web サービスにアクセスするソフトウェアです。Web クライアントには、一連のプロキシ・メソッドが用意されています。各プロキシ・メソッドは、Web サービスのメソッドに対応しています。プロキシ・メソッドは、対応する Web サービス・メソッドと同じシグニチャを使用し、必要に応じて Web サービス・メソッドを呼び出します。この章では、Caché で Web クライアントを作成し、使用する方法を説明します。

Caché Web クライアントに対する SOAP 呼び出しをログに記録する方法については、このドキュメントで後述する Caché SOAP ログ を参照してください。
Note:
Caché Web サービスの場合、自動的に生成された WSDL には、SOAP ヘッダ要素に関する情報が含まれていないことがあります。
W3C 仕様では、生成された WSDL を Web サービスが提供することを要求していない点に注意してください。
SOAP ウィザードの概要
Caché Web クライアントを作成するには、スタジオの SOAP ウィザードを使用するか、Caché に用意された対応するクラス・メソッドを使用します。どちらの場合も、入力は WSDL ドキュメントです。このツールでは、Web クライアント・クラスおよびサポートするすべての必要なクラスが生成されます。
このツールは、ほぼすべての WSDL ドキュメントで使用できます。最初の章の Caché における WSDL のサポート も参照してください。
WSDL の URL またはファイル・パスのいずれかを指定できます。
Note:
WSDL が SOAP 1.1 および SOAP 1.2 の両方のサポートを示す場合は、SOAP ウィザードは必要に応じて 2 つのクラスのセットを生成します。
SOAP ウィザードの使用法
スタジオに提供される SOAP ウィザードでは、特定の Web サービス、そのサービスの特定の WSDL のクライアントを生成できます。
Note:
SOAP ウィザードなどのテンプレート使用すると、スタジオでプロキシ・サーバを使用できます (有効な場合)。プロキシ・サーバとポートの指定については、"Caché インターネット・ユーティリティの使用法" の プロキシ・サーバの使用法 を参照してください。
SOAP ウィザードを使用するには:
  1. WSDL を検証し、以下の項目を確認します。
    いずれの場合も、その回答がはいの場合、後述の手順で説明する [ドキュメントスタイルのウェブメソッドでラップしないメッセージフォーマットを使用] オプションを選択する必要があります。
  2. 最初の画面で、次の手順を実行します。
    1. WSDL の場所に応じて、[URL] または [FILE] のいずれかをクリックします。
    2. WSDL の場所を入力します。WSDL の完全な URL または完全パスとファイル名のいずれかを入力してください。
    3. WSDL が、SSL を使用する場所にある場合 (つまり、URL が https で始まっている場合)、[SSL 構成] ドロップダウン・リストから適切な SSL 構成を選択します。SSL/TLS 構成の作成と管理の詳細は、"Caché セキュリティ管理ガイド" の Caché での SSL/TLS の使用法 の章を参照してください。
      Important:
      このウィザードは、WSDL へのアクセスに使用する SSL 構成を指定します。このフィールドは、これ以外の方法では使用しません。
    4. WSDL が SSL を使用する場所にある場合、ウィザードは、証明書サーバ名がサーバへの接続に使用される DNS 名と一致するかどうかをチェックします (既定の動作)。これらの名前が一致していないと、接続は許可されません。この既定の動作は、“中間者” 攻撃を防止するもので、RFC 2818 のセクション 3.1 に説明があります。また、RFC 2595 のセクション 2.4 も参照してください。
      このチェックを無効にするには、[SSL 接続の確立にサーバ証明書のサーバ ID が接続先のシステムの名前と一致することを確認する] チェック・ボックスのチェックを外します。
  3. [次へ] をクリックします。
    次に、ウィザードは WSDL へのアクセスを試行して表示し、選択内容が正しいことをを確認できるようにします。
    ウィザードが WSDL にアクセスできない場合、エラーを示す画面が表示され、ユーザ名とパスワードの入力に使用できるオプションが示されます (多くの WSDL は、ユーザ名およびパスワードで保護されている URL にあり、これが WSDL へのアクセスに失敗する一般的な理由です)。このシナリオでは、最初に以下の手順の 1 つを実行します。
    [ユーザ名] フィールドと [ユーザ名] フィールドに値を入力して、[再試行] をクリックします。ウィザードでは、これらの項目の入力は保存されない点に注意してください。
  4. WSDL を表示する画面で、以下のようにオプションを指定します。
  5. Ensemble がインストールされている場合は、オプションで以下の追加フィールドに値を指定します。
    Ensemble の詳細は、Ensemble のドキュメントを参照してください。
  6. [次へ] をクリックします。ウィザードに次のような画面が表示されます。
  7. 以下のオプションを指定します。
  8. 必要に応じて、パッケージ名を編集します。ウィザードでは、パッケージ名に次の規則を使用します。
  9. [次へ] をクリックします。ウィザードによって、クラスが生成およびコンパイルされ、これらのクラスの一覧が表示されます。
  10. [完了] をクリックします。
Tip:
WSDL URL の使用中にウィザードに問題が発生した場合は、WSDL をファイルとして保存し、そのファイルを入力として使用して再試行してください。
外部で定義されたエンティティへの参照が WSDL に含まれている場合、ウィザードがそれらの解決を試行します。このタスクのタイムアウト期間は 10 秒です。
これらのクラスのプロパティについては、スキーマ内の対応する要素の名前がアンダースコア (_) で始まる場合、そのプロパティの名前はパーセント記号 (%) で始まります。
プログラムによるクライアント・クラスの生成
プログラムによってクライアント・クラスを生成することもできます。これには、%SOAP.WSDL.Reader クラスを使用します。
結果として生成されたクラスとそれらの構成は、SOAP ウィザードを使用した場合と異なることがあります。SOAP ウィザードでは、生成されたクラスのパッケージに対してより詳細な管理を行うことができます。
プログラムによってクライアント・クラスを生成する手順は以下のとおりです。
  1. %SOAP.WSDL.Reader のインスタンスを作成します。
  2. 必要に応じて、インスタンスの動作を制御するプロパティを設定します。詳細は、%SOAP.WSDL.Reader のクラス・ドキュメントを参照してください。
    WSDL が SSL を使用する場所にある場合、%SOAP.WSDL.Reader は、証明書サーバ名がサーバへの接続に使用される DNS 名と一致するかどうかをチェックする (既定の動作) 点に注意してください。これらの名前が一致していないと、接続は許可されません。この既定の動作は、“中間者” 攻撃を防止するもので、RFC 2818 のセクション 3.1 に説明があります。また、RFC 2595 のセクション 2.4 も参照してください。
    このチェックを無効にするには、インスタンスの SSLCheckServerIdentity プロパティを 0 に設定します。
  3. %SOAP.WSDL.Reader で直接サポートされていない方法で HTTP 要求を制御できるようにする必要がある場合は、以下の手順を実行します。
    1. %Net.HttpRequest のインスタンスを作成し、必要に応じてプロパティを設定します。
    2. %SOAP.WSDL.Reader のインスタンスに対して、作成した %Net.HttpRequest のインスタンスと同じ HttpRequest プロパティを設定します。
  4. インスタンスの Process() メソッドを呼び出します。
    method Process(pLocationURL As %String, pPackage As %String = "") as %Status 
ターミナル・セッションの例を以下に示します。
set r=##class(%SOAP.WSDL.Reader).%New() 
GSOAP>set url="http://localhost:57772/csp/gsop/GSOP.AddComplexWS.CLS?WSDL=1"
 
GSOAP>d r.Process(url) 
Compilation started on 11/09/2009 12:53:52 with qualifiers 'dk'
Compiling class AddComplex.ns2.ComplexNumber
Compiling routine AddComplex.ns2.ComplexNumber.1
Compilation finished successfully in 0.170s.
 
Compilation started on 11/09/2009 12:53:52 with qualifiers 'dk'
Compiling class AddComplex.AddComplexSoap
Compiling routine AddComplex.AddComplexSoap.1
Compiling class AddComplex.AddComplexSoap.Add
Compiling routine AddComplex.AddComplexSoap.Add.1
Compilation finished successfully in 0.363s.
WSDL URL は、Web アプリケーションの一部です。Web アプリケーションは、パスワード認証によって保護されている可能性があります。このような場合に WSDL を使用して Caché Web クライアントまたはサードパーティの Web クライアントを生成する方法の詳細は、このドキュメントで後述の パスワードで保護された WSDL URL の使用法 を参照してください。
どのような場合でも、必要なユーザ名とパスワードを指定した後、ブラウザから WSDL を取得して、これをファイルとして保存し、そのファイルを代わりに使用することもできます。
生成された Web クライアント・クラスの変更
通常は、Caché Web クライアント・クラスを生成した後で、そのクラスを編集することはありません。その代わりに、Web クライアントのインスタンスを作成するコードと、クライアント側のエラー処理を提供するコードを記述します。このセクションでは、生成されたクライアント・クラスに変更を加える際の主な例外について説明します。
生成されたクラスの Web メソッドに関するその他の注意事項 のセクションと、Caché Web クライアントの調整 の章も参照してください。
Note:
生成された Web クライアント・クラスのサブクラスは作成しないでください。コンパイラは、適切な実行に必要なサポート・クラスを生成しないため、そのサブクラスは使用できなくなります。
生成されたクラスを長い文字列に合わせて調整する方法
場合によっては、生成されたクライアント・クラスを、長い文字列または長いバイナリ値に対応できるように編集する必要があります。
SOAP ウィザードで WSDL を読み取る場合、Caché では文字列タイプの入出力を %String として表現できることが前提となっていますが、そのように表現できないこともあります。文字列によっては、Caché の 32 KB という文字列制限を超える可能性がありますが、WSDL 内には、このことを SOAP ウィザードに通知するための情報が含まれていません。
同様に、Caché では XML タイプ base64Binary の入出力をすべて %xsd.base64Binary として表現できることが前提となっていますが、長い文字列に関する同様の制限のため、そのように表現できないこともあります。WSDL 内には、この入出力が長い文字列に関する制限を超えている可能性があることを SOAP ウィザードに通知するための情報が含まれていません。
いずれの場合も、Caché で長い文字列演算を有効化している場合、Web クライアントは機能します。
一方、Caché で長い文字列演算を有効にしていない場合は、Web クライアントが長すぎる文字列またはバイナリ値を検出すると、次のエラーのいずれかが発生します。
ただし、この問題は簡単に修正できます。これらの入出力に長い値が存在すると予期される場合は、生成された Web クライアント・クラス (特に、%SOAP.WebClient から継承されたクラス) のメソッド・シグニチャを、適切なストリーム・クラスを使用するように調整します。
例えば、引数を取らず 32 KB を超える非常に長い文字列を返すメソッドが 1 つ (WriteIt) 含まれる Web サービス (MyGiantStringService) について考えてみます。SOAP ウィザードを使用して Web クライアント・クラスを生成すると、Web クライアント・クラスは最初は次のようになります。
Class GetGiantString.MyServiceSoap Extends %SOAP.WebClient
{

Method WriteIt() As %String 
[Final,SoapBindingStyle=document,SoapBodyUse=literal,WebMethod]
{
 Quit ..WebMethod("WriteIt").Invoke(##this,"http://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}

}
この場合、行う調整は 1 つだけです。WriteIt の返りタイプを次のように変更します。
Method WriteIt() As %GlobalCharacterStream 
[Final,SoapBindingStyle=document,SoapBodyUse=literal,WebMethod]
{
 Quit ..WebMethod("WriteIt").Invoke(##this,"http://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}
このクラスをコンパイルすると、関連するクラスが必要に応じて自動的に再生成されます。
生成されたタイプのクラス内のプロパティ・タイプの調整が必要な場合があります。例えば、タイプ文字列の要素 <ContainerPart> が組み込まれた <Container> という要素を Web サービスで使用しているとします。Caché Web クライアント・クラスを生成すると、Caché では、タイプ %StringContainerPart プロパティによって Container クラスが作成されます。Web サービスから <ContainerPart> 要素で 32 KB を超える長い文字列が送信され、長い文字列演算が有効化されていない場合は、Web クライアントでエラーが発生します。このエラーを回避するには、ContainerPart プロパティのタイプを %GlobalCharacterStream に変更します。
その他の調整
WSDL が Web サービスの場所を指定しない場合、SOAP ウィザードは Web クライアントの LOCATION パラメータを指定しません。これは一般的なケースではありません。このシナリオでは、Web クライアント・クラスを編集して LOCATION パラメータを含めるようにします。例えば以下のようになります。
Parameter LOCATION = "http://localhost:57772/csp/gsop/GSOP.AddComplexWS.cls";
または、Web クライアント・インスタンスの Location プロパティを、この章で後から示すように指定します。
Web クライアント・クラスの他のパラメータを調整して、その他の変更を加える必要がある場合があります。詳細は、Caché Web クライアントの調整 の章を参照してください。
生成された Web クライアント・クラスの使用法
前述のセクションで説明したように、通常は、Caché Web クライアント・クラスを生成した後で、そのクラスを編集することはありません。その代わりに、その Web クライアントのインスタンスを作成するコードと、クライアント側のエラー処理を提供するコードを記述します。このコードでは、以下の処理を実行します。
  1. Web クライアント・クラスのインスタンスを作成します。
  2. インスタンスのプロパティを設定します。ここでは、以下のような項目を制御できます。
  3. 必要に応じて、Web クライアントのメソッドを呼び出します。
  4. クライアント側のエラー処理を実行します。SOAP フォルトの処理 を参照してください。
  5. この章で後述するように、オプションで、Web クライアントが受け取る HTTP 応答を検証します。
ターミナルのセッションからの簡単な例を以下に示します。
GSOAP>set client=##class(Proxies.CustomerLookupServiceSoap).%New()

GSOAP>set resp=client.GetCustomerInfo("137")
 
GSOAP>w resp
 
11@Proxies.CustomerResponse

GSOAP>w resp.Name
Smith,Maria
例 1 : ラップされたメッセージを使用するクライアントの使用法
この例では、ラップされたメッセージを使用する Web クライアントのラッパ・クラスを作成します。前に示した GSOAPClient.AddComplex.AddComplexSoap の例を使用するために、次のようなクラスを作成します。
Class GSOAPClient.AddComplex.UseClient Extends %RegisteredObject
{

ClassMethod Add(arg1 As ComplexNumber, arg2 As ComplexNumber) As ComplexNumber
{
    Set client=##class(AddComplexSoap).%New()
    //uncomment the following to enable tracing
    //set client.Location="http://localhost:8080/csp/gsop/GSOP.AddComplexWS.cls"
    Set ans=client.Add(arg1,arg2)
    Quit ans 
}

}
クライアント・アプリケーションは、Web メソッドを実行するために、このメソッドを呼び出します。
例 2 : ラップされていないメッセージを使用するクライアントの使用法
この例では、ラップされていないメッセージを使用する Web クライアントのラッパ・クラスを作成します。前に示した GSOAPClient.AddComplex.AddComplexSoap の例を使用するために、次のようなクラスを作成します。
Class GSOAPClient.AddComplexUnwrapped.UseClient Extends %RegisteredObject
{

ClassMethod Add(arg1 As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber, 
arg2 As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber) 
As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber
{
    //create the Add message
    Set addmessage=##class(GSOAPClient.AddComplexUnwrapped.s0.Add).%New()
    Set addmessage.a = arg1
    Set addmessage.b = arg2

    Set client=##class(AddComplexSoap).%New()
    
    //send the Add message to client and get response
    Set addresponse=client.Add(addmessage)
    
    //get the result from the response message
    Set ans=addresponse.AddResult
    
    Quit ans
 
}

}
このメソッドには、普通に想定されるシグニチャがあります。つまり、このメソッドは 2 つの複素数を受け取り、1 つの複素数を返します。このメソッドは Web クライアントが必要とするメッセージを作成します。このメッセージの要素は 2 つの複素数です。
サンプル・コードを見るとわかるように、ラップされていないメッセージを Web クライアントで使用する場合は、ユーザにわかりやすい形式の引数を Web クライアントで使用するメッセージに変換する必要があるので、作成するコード量が若干多くなります。
Web クライアント・インスタンスのプロパティの調整
Web クライアント・クラスのインスタンスを使用するとき、そのインスタンスのプロパティを指定して動作を制御できます。このセクションでは、一般的に設定することが多いプロパティとその既定値について説明します。
Web クライアントのエンドポイントの変更
SOAP ウィザードでは、Web クライアントの LOCATION パラメータを設定することにより、Web クライアントにエンドポイントが自動的に設定されます。既定では、このパラメータは、通信する Web サービスの URL と同じに設定されます。
この設定を変更するには、Web クライアント・インスタンスの Location プロパティを設定します。Location が NULL の場合に、LOCATION パラメータが使用されます。
一般的な使用法の 1 つとして、トレースを有効にするために別のポートを使用するように Location プロパティを設定します。例えば、生成された Web クライアント・クラスでエンドポイントが次のように定義されているとします。
Parameter LOCATION = "http://localhost:57772/csp/gsop/GSOP.AddComplexWS.cls";
このクライアントを使用するときに、次の行を追加します。
   Set client.Location="http://localhost:8080/csp/gsop/GSOP.AddComplexWS.cls"
Note:
WSDL が Web サービスの場所を指定しない場合、SOAP ウィザードは Web クライアントの LOCATION パラメータを指定しません。これは一般的なケースではありません。このシナリオでは、Web クライアント・クラスを編集して LOCATION パラメータを含めるようにするか、または Web クライアント・インスタンスの Location プロパティをここに示すように指定します。
SSL を使用するようにクライアントを構成する方法
Web クライアントのエンドポイントで HTTPS プロトコルを使用する場合は、SSL を使用するようにその Web クライアントを構成する必要があります。具体的には以下のとおりです。
プロキシ・サーバ経由でクライアントを接続している場合は、Web クライアントで HttpProxySSLConnect プロパティを 1 に設定する必要もあります。プロキシ・サーバを使用するように Caché Web クライアントを構成する方法の詳細は、Web クライアントの調整 の章を参照してください。
SOAP バージョンの指定
SOAP ウィザードでは、Web サービスの WSDL で使用している SOAP バージョンに基づいて、要求メッセージで使用する SOAP バージョンが自動的に指定されます。具体的には、SOAPVERSION パラメータが設定されます。
この設定を変更するには、Web クライアント・インスタンスの SoapVersion プロパティを設定します。以下の値のいずれかを使用します。
SoapVersion が NULL の場合に、SOAPVERSION パラメータが使用されます。
その他の調整
Web クライアント・インスタンスの他のプロパティを設定して、その他の変更を加える必要がある場合があります。詳細は、Caché Web クライアントの調整 の章を参照してください。
HTTP 応答の使用法
既定では、Web クライアント・メソッドを呼び出す場合、HTTP 経由で呼び出されます。HTTP 応答は、Web クライアント・インスタンスの HttpResponse プロパティとして使用できるようになります。このプロパティは %Net.HttpResponse のインスタンスであり、以下のようなプロパティが含まれています。
詳細は、"Caché インターネット・ユーティリティの使用法" のドキュメントを参照してください。または、%Net.HttpResponse のクラス・ドキュメントを参照してください。