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

通常は、Caché Web クライアント・クラスを生成した後で、そのクラスを編集することはありません。その代わりに、そのクラスのインスタンスを作成するコードと、クライアント側のエラー処理を提供するコードを記述します。この章では、Caché Web クライアントを調整するさまざまな方法について説明します。この調整方法は、Web クライアントのインスタンスを変更するか、一般的ではありませんが生成されたクラスを変更するかのどちらかになります。項目は以下のとおりです。

Web クライアントの作成 の章の Caché Web クライアントの基本設定 のセクションも参照してください。このセクションでは、ネームスペース、タイプのネームスペース、および Web クライアントのその他の基本事項を制御するパラメータについて説明します。
注意:
生成された Web クライアント・クラスのサブクラスは作成しないでください。コンパイラは、適切な実行に必要なサポート・クラスを生成しないため、そのサブクラスは使用できなくなります。
Web クライアントのキープ・アライブを無効にする方法
既定では、Caché Web クライアント・インスタンスを再利用して複数の要求メッセージを送信すると、Caché は (HTTP 1.1 キープ・アライブ接続を使用して) 1 つの HTTP 転送ですべてのメッセージを送信します。具体的には、Caché は TCP/IP ソケットを閉じてから再び開く必要がないように、開いたままにします。このキープ・アライブ動作を無効にするには、以下のいずれかを実行します。
注意:
WS-ReliableMessaging メッセージを使用し、SSL/TLS を使用して Web サーバと通信するには、キープ・アライブを無効にしないでください。WS-ReliableMessaging については、"Caché Web サービスの保護" を参照してください。
NULL 文字列の引数が持つ形式の制御
通常、引数を省略すると、Caché Web クライアントから送信する SOAP メッセージでは、対応する要素が省略されます。これを変更するには、Web クライアント・クラスで XMLIGNORENULL パラメータを 1 に設定します。この場合、SOAP メッセージには空の要素が含まれます。
注意:
このパラメータは、タイプが %String の Web メソッド引数にのみ作用します。
クライアントのタイムアウトの制御
Caché Web クライアントに対して、2 つの異なるタイムアウト期間を制御できます。
プロキシ・サーバの使用法
Caché Web クライアントは、プロキシ・サーバ経由で Web サービスと通信できます。これを設定するために、使用するプロキシ・サーバを示すように Web クライアント・インスタンスのプロパティを指定します。これらのプロパティは、以下のとおりです。
HttpProxyServer
使用するプロキシ・サーバのホスト名を指定します。このプロパティが NULL でない場合、HTTP 要求はこのマシンに向けられます。
既定のプロキシ・サーバの指定については、"Caché インターネット・ユーティリティの使用法" の プロキシ・サーバの使用法 を参照してください。
HttpProxyPort
プロキシ・サーバ上の接続先ポートを指定します。
既定のプロキシ・ポートの指定については、"Caché インターネット・ユーティリティの使用法" の プロキシ・サーバの使用法 を参照してください。
HttpProxyHTTPS
プロキシ・サーバを使用している場合、およびそのプロキシ・サーバで HTTPS がサポートされる場合は、これを True に指定します。
HTTPS を使用している場合は、クライアントの SSLConfiguration プロパティを SSL/TLS 構成の名前に設定する必要もあります。セキュリティの詳細は、このドキュメントで前述の SSL を使用するようにクライアントを構成する方法 のセクションを参照してください。
HttpProxyAuthorization
Web クライアントがそのクライアント自体をプロキシ・サーバで認証する必要がある場合は、これを必須の Proxy-Authorization ヘッダ・フィールドとして指定します。
HttpProxyTunnel
Web クライアントが、ターゲットの HTTP サーバへのプロキシ経由のトンネルを確立する必要がある場合は、これを True に指定します。True の場合、要求は HTTP CONNECT コマンドを使用してトンネルを確立します。プロキシ・サーバのアドレスは、HttpProxyServer プロパティと HttpProxyPort プロパティから取得されます。エンドポイントの URL で https: プロトコルを使用している場合は、トンネルが確立されたときに Caché が SSL 接続をネゴシエートします。この場合、トンネルによってターゲット・システムとの直接接続が確立されるため、HttpProxyHTTPS プロパティは無視されます。
HTTP ヘッダの設定
Web クライアントによって送信される HTTP ヘッダをさらに制御する必要がある場合は、%SOAP.WebClient の次のメソッドを使用できます。
SetHttpHeader()
HTTP 要求にヘッダを追加します。Content-TypeContent-Encoding、および Content-Length の各ヘッダは、HTTP のメイン・ヘッダではなく、本文の一部です。Content-Length ヘッダは読み取り専用なので、設定することはできません。Connection ヘッダも設定できません。このクラスは、永続接続をサポートしていないためです。
ResetHttpHeaders()
すべての HTTP ヘッダをクリアします。
この章で前述の HTTP ユーザ認証の使用法 のセクションも参照してください。
使用する HTTP バージョンの指定
既定では、Caché Web クライアントは HTTP/1.1 を使用します。代わりに HTTP/1.0 を使用することができます。そのためには、クライアントの HttpVersion プロパティを "1.0" に設定します。
SSL サーバ名チェックの無効化
既定では、Caché Web クライアントは、SSL を介してサーバに接続するときに、証明書サーバ名と、そのサーバへの接続に使用した DNS 名が一致していることを確認します (このチェックは、RFC 2818 セクション 3.1 で説明されています。ワイルドカード・サポートは RFC 2595 で説明されていますが、ブラウザは一般的にサーバ名をチェックし、InterSystems でも同様に実行します)。
このチェックを無効にするには、クライアントの SSLCheckServerIdentity プロパティを 0 に設定します。
xsi:type 属性の使用の制御
既定では、Caché SOAP メッセージには、最上位タイプの場合にのみ xsi:type 属性が追加されます。以下はその例です。
<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name>Yeats,Clint C.</Name>
<DOB>1944-12-04</DOB>
</types:Person>  
...
これらの例では、見やすくするために改行を追加してあります。この属性を SOAP メッセージに含まれるすべてのタイプに使用するには、以下のどちらかを実行します。
同じ出力は以下のようになります。
<?xml version="1.0" encoding="UTF-8" ?>
...
<types:GetPersonResponse>
<GetPersonResult href="#id1" />
</types:GetPersonResponse>
<types:Person id="id1" xsi:type="types:Person">
<Name xsi:type="s:string">Yeats,Clint C.</Name>
<DOB xsi:type="s:date">1944-12-04</DOB>
</types:Person> 
...
プロパティはパラメータよりも優先されます。
エンコード形式でのインライン参照の使用の制御
エンコードされた形式では、任意のオブジェクト値プロパティが参照として含められ、参照オブジェクトが SOAP メッセージに個別の要素として書き込まれます。
代わりに、エンコードされたオブジェクトをインラインで書き込む場合は、ReferencesInline パラメータまたはReferencesInline プロパティに 1 を指定します。プロパティはパラメータよりも優先されます。
エンベロープ接頭語の指定
既定では、Caché Web クライアントは、送信する SOAP メッセージのエンベロープで接頭語 SOAP-ENV を使用します。別の接頭語を指定できます。そのためには、Web クライアント・クラスの SOAPPREFIX パラメータを設定します。例えば、このパラメータを MYENV に設定すると、SOAP-ENV ではなく、この接頭語が Web クライアントのメッセージに使用されます。
SOAP エンベロープへのネームスペース宣言の追加
指定の Web クライアントによって返された SOAP 応答の SOAP エンベロープ (<SOAP-ENV:Envelope> 要素) にネームスペース宣言を追加するには、Web メソッドを呼び出す前に Web クライアントの %AddEnvelopeNamespace() メソッドを呼び出します。このメソッドには、以下のシグニチャがあります。
Method %AddEnvelopeNamespace(namespace As %String, 
                             prefix As %String, 
                             schemaLocation As %String, 
                             allowMultiplePrefixes As %Boolean) As %Status
以下はその説明です。
gzip で圧縮された応答の送信
Caché Web クライアントでは応答メッセージを gzip で圧縮できます。gzip はインターネット上で広く提供されている無償の圧縮プログラムです。他の何らかのメッセージのパッケージ化 (MTOM パッケージの作成など) の後、この圧縮が実行されます。これを Web クライアントで実行するには、以下のどちらかを実行します。
この操作時は、Web サービス側で対応する解凍プログラムである gunzip を使用してメッセージが自動解凍できることを確認してください。Web サービスが Caché Web サービスの場合は、Web サービスへの送信前に着信メッセージが CSP ゲートウェイによって自動解凍されるため、注意が必要です。
SOAP アクションに対する引用符の使用 (SOAP 1.1 のみ)
SOAP 1.1 の要求メッセージでは、HTTP ヘッダに次のような SOAPAction 行が含まれます。
POST /csp/gsop/GSOP.DivideWS.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; Cache;)
Host: localhost:8080
Connection: Close
Accept-Encoding: gzip
SOAPAction: http://www.mynamespace.org/GSOAP.DivideWS.Divide
Content-Length: 397
Content-Type: text/xml; charset=UTF-8

...
既定では、SOAPAction の値は引用符で囲まれません。この値を引用符で囲むには、Web クライアント・クラスで SOAPACTIONQUOTED に 1 を指定します。この指定により、要求メッセージの HTTP ヘッダが次のようになります。
POST /csp/gsop/GSOP.DivideWS.cls HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; Cache;)
Host: localhost:8080
Connection: Close
Accept-Encoding: gzip
SOAPAction: "http://www.mynamespace.org/GSOAP.DivideWS.Divide"
Content-Length: 397
Content-Type: text/xml; charset=UTF-8

...
SOAP 1.2 では、SOAPACTIONQUOTED パラメータは機能しません。これは、要求メッセージに SOAPAction 行がないためです。次に示すように、SOAP アクションは必ず引用符で囲まれて Content-Type 行に記述されます。
Content-Type: application/soap+xml; 
   charset=UTF-8; action="http://www.mynamespace.org/GSOAP.DivideWS.Divide"
注意:
この例では、PDF 形式にしたこのドキュメントでページに行が適切に表示されるように、意図的な改行を適用しています。
HTTP のステータス 202 をステータス 200 と同じように処理する方法
既定では、HTTP 応答に SOAP エンベロープが含まれていない場合、Caché Web クライアントは、HTTP 応答ステータス 202 のみを使用する標準の WS-I Basic Profile に従います。
HTTP ステータス 202 を HTTP ステータス 200 と同じように処理する場合は、クライアントの HttpAccept202 プロパティを 1 に設定します。実際に返されるステータスを確認するには、クライアントの HttpResponse.StatusCode プロパティをチェックします。
WS-I Basic Profile では、この方法をサポートしていますが、お勧めはしません。“Profile が両方のステータス・コードを受け入れるのは、一部の SOAP 実装が HTTP プロトコル実装をほとんど制御できず、これらの応答ステータス・コードのいずれを送信するか制御できないためです。“
単方向 Web メソッドの定義
通常、Web クライアントが Web サービスを呼び出すと、メソッド自体に返りタイプがなく、Caché での実行時に何も返さない場合であっても、SOAP メッセージが返されます。
まれに、“単方向” として Web メソッドを定義することが必要な場合があります。そのようなメソッドは値を返すことがなく、メッセージに SOAP 応答は必要ではありません。
注意:
通常、単方向メソッドは使用されません。返りタイプがないメソッドの場合でも、要求と応答のペアを使用する方法のほうがより一般的であり、広くサポートされ、必要とされています。
単方向の Web メソッドを定義するには、メソッドの返りタイプを %SOAP.OneWay として定義します。WSDL では、この Web メソッドに対して定義される出力が定義されません。また、Web サービスでは、SOAP メッセージが返されません。
バイナリ・データへの改行の追加
Caché Web サービスで、%Binary または %xsd.base64Binary タイプのプロパティに自動改行を含めるようにできます。これを実行するには、以下のいずれかを実行します。
パラメータおよびプロパティの場合、既定値は 0 です。既定では、Caché Web サービスには %Binary または %xsd.base64Binary タイプのプロパティに対する自動改行は含まれません。
SOAP メッセージへのバイト・オーダー・マークの追加
既定の場合、Caché Web クライアントによって送信されるメッセージの先頭に BOM (バイト・オーダー・マーク) はありません。
メッセージはバイト・オーダーの問題がない UTF-8 としてエンコードされるため、通常 BOM は必要ありません。ただし、SOAP メッセージに BOM を組み込むことが必要であったり、推奨される状況があります。この BOM は単にメッセージが UTF-8 であることを示すものです。
Caché Web クライアントで送信されるメッセージに BOM を追加するには、クライアントの RequestMessageStart プロパティを設定します。このプロパティは、メッセージの先頭に組み込むパーツのコンマ区切りのリストにする必要があります。これらのパーツは、以下のとおりです。
既定は "DCL" です。
実際には、RequestMessageStart を以下の値のいずれかにすることができます。
解析時にプロセス・プライベート・グローバルを使用する方法
既定では、Caché Web クライアントは通常、要求や応答を解析するときにローカル配列メモリを使用します。代わりに、プロセス・プライベート・グローバルを強制的に使用させることができます。これにより、Web クライアントは非常に大きいメッセージを処理できるようになります。
そのためには、以下のように Web サービス・クラスの USEPPGHANDLER パラメータを指定します。
Parameter USEPPGHANDLER = 1;
このパラメータが 1 の場合、Web クライアントは常に、要求や応答を解析するときにプロセス・プライベート・グローバルを使用します。このパラメータが 0 の場合、Web クライアントは常に、この目的のためにローカル配列メモリを使用します。このパラメータが設定されていない場合、Web クライアントは既定の動作になります。既定の動作は通常ローカル配列メモリの使用です。
このパラメータは実行時にオーバーライドできます。そのためには、Web クライアント・インスタンスの UsePPGHandler プロパティを設定します。
カスタム SOAP メッセージの作成
特別な場合として、Web クライアントでカスタム SOAP メッセージの送信が必要なことがあります。基本的な要件は以下のとおりです。
  1. %SOAP.WebRequest のサブクラスを作成し、その LOCATION パラメータまたは Location プロパティを設定します。
  2. このサブクラスで、SOAP メッセージを送信するメソッドを作成します。このメソッドは、%Library.CharacterStream のインスタンスを作成し、送信する SOAP メッセージをそのインスタンスに配置します。メッセージの形式が正しいことを確認する必要があります。
  3. 次に、このメソッドによって SendSOAPBody() メソッドが起動されます。
    method SendSOAPBody(Action As %String, 
                        OneWay As %Boolean = 0, 
                        Request As %CharacterStream, 
                        ByRef Response) as %Status
%SOAP.WebRequest%SOAP.WebClient のサブクラスであるため、他のパラメータおよびプロパティの設定が必要な場合があります。このドキュメントで前述したように、SOAP ヘッダを追加することもできます。詳細は、%SOAP.WebRequest のクラス・ドキュメントを参照してください。
カスタムの HTTP 要求の指定
既定では、Caché Web クライアントを使用する場合、Web クライアントでは HTTP を使用して SOAP メッセージが Web サービスに転送され、その応答が受信されます。Web クライアントでは、自動的に HTTP 要求が作成されて、送信されますが、カスタムの HTTP 要求を作成することができます。そのためには、次の手順を実行します。
  1. %Net.HttpRequest のインスタンスを作成し、必要に応じてプロパティを設定します。このクラスの詳細は、"Caché インターネット・ユーティリティの使用法" を参照するか、%Net.HttpRequest のクラス・ドキュメントを参照してください。
  2. Web クライアントの HttpRequest プロパティをこのインスタンスと等しくなるように設定します。
これは、同一セッション内で SOAP サービスへの複数呼び出しをサポートする場合に特に便利です。既定では、Caché Web クライアントでは、同一セッションを使用した SOAP サービスへの複数呼び出しはサポートされません。この問題に対処するには、%Net.HttpRequest のインスタンスを新規作成し、それを Web クライアントの HttpRequest プロパティとして使用します。この変更により、同一の HTTP 要求がすべての呼び出しで再使用されるように強制され、次の要求に対する応答ですべての cookie が返されます。
Web クライアントのコールバックのカスタマイズ
コールバック・メソッドをオーバーライドすることによって、Caché Web クライアントの動作をカスタマイズできます。
%OnSOAPRequest()
Method %OnSOAPRequest(mode As %String, 
                      client As %SOAP.WebClient,  
                      action As %String,  
                      oneWay As %Boolean,  
                      method As %String,  
                      requestStream As %BinaryStream)
Web クライアントが (実際の SOAP 要求を作成する) 転送クラスの DoSOAPRequest() メソッドを呼び出す直前に呼び出されます。既定の DoSOAPRequest() メソッドは、%SOAP.WebClient に含まれていて、要求/応答に HTTP を使用します。
%OnSOAPResponse()
Method %OnSOAPResponse(mode As %String, 
                       client As %SOAP.WebClient, 
                       action As %String, 
                       oneWay As %Boolean, 
                       method As %String, 
                       requestStream As %BinaryStream, 
                       responseStream As %BinaryStream, 
                       sc As %Status)
Web クライアントが転送クラスの DoSOAPRequest() メソッドを呼び出した後に呼び出されます。sc 引数は、転送クラスの DoSOAPRequest() メソッドによって返されたステータスです。その他の引数は、%OnSOAPRequest() のものと同じです。
%OnSOAPFinished()
Method %OnSOAPFinished(mode As %String, client As %SOAP.WebClient, method As %String, sc As %Status)
Web クライアントがその処理をすべて実行した後に呼び出されます。sc 引数は、呼び出された Web メソッドによって返されたステータスです。mode 引数、client 引数、および method 引数は、その他のコールバック・メソッドのものと同じです。
Web クライアントからのカスタム転送の指定
既定では、Caché Web クライアントを使用する場合、Web クライアントでは HTTP を使用して SOAP メッセージが Web サービスに転送され、その応答が受信されます。ユーザ独自の転送クラスを定義し、使用できます。
背景
使用する Web サービスと通信するには、Caché Web クライアントに転送クラスが必要です。転送クラスは、通信に関連するパラメータ、プロパティ、およびメソッドを備えています。全体的な通信の動作は、以下のとおりです。
  1. Web クライアント・プロキシ・メソッドが実行されている場合、Web クライアント・インスタンスは Transport プロパティの値をチェックします。
    このプロパティが NULL の場合、Web クライアント・インスタンスは、それ自体を転送クラスのインスタンスとして使用します。このようなクラスを定義した場合、代わりに、Transport プロパティを他の適切なクラスのインスタンスと等しくなるように設定できます。
  2. Web クライアント・インスタンスは、転送クラスの DoSOAPRequest() メソッドを実行して、次の引数を渡します。
    1. Web クライアント・クラスの OREF
    2. SOAP アクションを指定する文字列
    3. UTF-8 でエンコードされた要求を含むストリーム
    4. 応答を含むストリーム (参照による)
  3. Web クライアント・インスタンスは、結果のステータスをチェックし、それに応じて動作します。
HTTP 転送の場合、DoSOAPRequest() メソッドには以下のロジックがあります。
  1. 要求オブジェクト (%Net.HttpRequest のインスタンス) を作成し、そのプロパティを設定します。ここで、このメソッドは、Web クライアント・インスタンスのプロパティの値を使用します。特に HttpRequestHeaderCharset プロパティとその他の HTTP 関連のプロパティの値を使用します。
  2. SOAP 要求のヘッダを確認した上で要求オブジェクトのヘッダを初期化します。
  3. 要求オブジェクトの Post() メソッドを実行します。これは、HTTP 転送に適したアクションです。
  4. 応答を取得し、それを返します。
重要:
%SOAP.WebClientDoSOAPRequest() メソッドは直接的に使用しないでください。この動作および以降の処理は保証されません。前述の概要は、一般的なヒントとして提供しています。
Caché Web クライアントのカスタム転送の定義
Caché Web クライアントでカスタム転送を使用できるようにするには、カスタムの転送クラスを定義します。次に、Web クライアントのインスタンスを作成した後に、その Transport プロパティを転送クラスのインスタンスと等しくなるように設定します。
転送クラスに関する要件は、以下のとおりです。
DoSOAPRequest() メソッドは、要求を Web サービスに転送して、応答を取得します。このメソッドのシグニチャは、以下のようにする必要があります。
Method DoSOAPRequest(webClient,action,requestStream, responseStream) As %Status 
SAX パーサのフラグ指定
Caché Web クライアントが Web サービスを呼び出すとき、Web クライアントは、Caché に付属のサードパーティ製品である SAX パーサを内部使用します。使用するパーサにフラグを設定するために、Web クライアントの SAXFlags プロパティを設定できます。
パーサのフラグ自体については、"Caché XML ツールの使用法" のドキュメントを参照してください。
WS-Security ログイン機能の使用法
認証を必要とする Web サービスが Caché Web クライアントで使用されており、新規の WS-Security 機能を使用する必要のない場合は、従来の単純な WS-Security ログイン機能を使用できます。
WS-Security ログイン機能を使用する手順は以下のとおりです。
  1. Web クライアントと、Web サービスをホストする Web サーバの間で、SSL が使用されていることを確認します。WS-Security ヘッダがクリア・テキストで送信されるので、この手法では、SSL を使用しないとセキュリティで保護されません。このドキュメントで前述の SSL を使用するようにクライアントを構成する方法,” のセクションを参照してください。
  2. Web クライアントの WSSecurityLogin() メソッドを呼び出します。このメソッドは、ユーザ名とパスワードを受け入れ、WS-Security ユーザ名トークンをクリア・テキストのパスワードを使用して生成し、WS-Security ヘッダを Web 要求に追加します。
  3. Web メソッドを呼び出します。
この方法では、次の SOAP メッセージ 1 件にのみセキュリティ・トークンが追加されます。
新しい WS-Security 機能については、"Caché Web サービスの保護" を参照してください。
HTTP ユーザ認証の使用法
Caché Web サービスの保護 の説明に従って、WS-Security を使用する代わりに、基本の HTTP 認証を使用できます。そのためには、以下の操作を実行します。
この方法は、WS-Security よりも安全性が低いですが、Web サービスによっては、この方法を使用する必要のある場合があります。