Caché Web クライアントの調整

Web クライアントのキープ・アライブを無効にする方法

既定では、Caché Web クライアント・インスタンスを再利用して複数の要求メッセージを送信すると、Caché は (HTTP 1.1 キープ・アライブ接続を使用して) 1 つの HTTP 転送ですべてのメッセージを送信します。具体的には、Caché は TCP/IP ソケットを閉じてから再び開く必要がないように、開いたままにします。このキープ・アライブ動作を無効にするには、以下のいずれかを実行します。

• Web クライアントのインスタンスを削除し、新しいインスタンスを作成して使用します。

• 最初のメッセージの送信後に、クライアントの HttpRequest.SocketTimeout プロパティを 0 に設定します。以下はその例です。

  Set client.HttpRequest.SocketTimeout=0
  

  

• クライアントからの 2 つ目の要求に Connection: close HTTP ヘッダを追加します。このためには、最初のメッセージを送信した後に、以下のようなコードを追加します。

  Set sc=client.HttpRequest.SetHeader("Connection","close")
  

  

NULL 文字列の引数が持つ形式の制御

通常、引数を省略すると、Caché Web クライアントから送信する SOAP メッセージでは、対応する要素が省略されます。これを変更するには、Web クライアント・クラスで XMLIGNORENULL パラメータを 1 に設定します。この場合、SOAP メッセージには空の要素が含まれます。

クライアントのタイムアウトの制御

Caché Web クライアントに対して、2 つの異なるタイムアウト期間を制御できます。

• Web クライアントの Timeout プロパティは、読み取りのタイムアウトを意味します。このプロパティは、Web クライアントが応答を待機する長さを秒単位で指定します。

  このプロパティが指定されていない場合、Web クライアントは、%Net.HttpRequestOpens in a new tab クラスの Timeout プロパティで指定されている既定値を使用します。この既定値は 30 秒です。

  プロキシ・サーバを使用している場合は、このプロパティにより、プロキシからの応答をクライアントが待機する長さが制御されます。

• OpenTimeout プロパティは、オープン・タイムアウトを指定します。これは、TCP/IP 接続のオープンを待機する秒数です。このプロパティが指定されていない場合は、Timeout によって指定された値が使用されます。

プロキシ・サーバの使用法

Caché Web クライアントは、プロキシ・サーバ経由で Web サービスと通信できます。これを設定するために、使用するプロキシ・サーバを示すように Web クライアント・インスタンスのプロパティを指定します。これらのプロパティは、以下のとおりです。

HTTP ヘッダの設定

Web クライアントによって送信される HTTP ヘッダをさらに制御する必要がある場合は、%SOAP.WebClientOpens in a new tab の次のメソッドを使用できます。

この章で前述の “HTTP ユーザ認証の使用法” のセクションも参照してください。

使用する HTTP バージョンの指定

既定では、Caché Web クライアントは HTTP/1.1 を使用します。代わりに HTTP/1.0 を使用することができます。そのためには、クライアントの HttpVersion プロパティを "1.0" に設定します。

SSL サーバ名チェックの無効化

既定では、Caché Web クライアントは、SSL を介してサーバに接続するときに、証明書サーバ名と、そのサーバへの接続に使用した DNS 名が一致していることを確認します (このチェックは、RFC 2818Opens in a new tab セクション 3.1 で説明されています。ワイルドカード・サポートは RFC 2595Opens in a new tab で説明されていますが、ブラウザは一般的にサーバ名をチェックし、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 メッセージに含まれるすべてのタイプに使用するには、以下のどちらかを実行します。

• Web クライアントのインスタンスで、OutputTypeAttribute プロパティを 1 に設定します。

• Web クライアント・クラスで、OUTPUTTYPEATTRIBUTE パラメータを 1 に設定します。

同じ出力は以下のようになります。

<?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

以下はその説明です。

• namespace は追加するネームスペースです。

• prefix はこのネームスペースで使用するオプションの接頭語です。この引数を省略すると、接頭語が生成されます。

• schemaLocation はこのネームスペースのためのオプションのスキーマの場所です。

• allowMultiplePrefixes は、指定されたネームスペースが異なる接頭語で複数回宣言可能かどうかを制御します。この引数が 1 の場合、指定されたネームスペースは異なる接頭語で複数回宣言可能です。この引数が 0 の場合、同じネームスペースに異なる接頭語で複数の宣言を追加すると、最後に指定された接頭語のみが使用されます。

gzip で圧縮された応答の送信

Caché Web クライアントでは応答メッセージを gzip で圧縮できます。gzip はインターネット上で広く提供されている無償の圧縮プログラムです。他の何らかのメッセージのパッケージ化 (MTOM パッケージの作成など) の後、この圧縮が実行されます。これを Web クライアントで実行するには、以下のどちらかを実行します。

• Web クライアントのインスタンスで、GzipOutput プロパティを 1 に設定します。

• Web クライアント・クラスで、GZIPOUTPUT パラメータを 1 に設定します。

この操作時は、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"

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.OneWayOpens in a new tab として定義します。WSDL では、この Web メソッドに対して定義される出力が定義されません。また、Web サービスでは、SOAP メッセージが返されません。

バイナリ・データへの改行の追加

Caché Web サービスで、%BinaryOpens in a new tab または %xsd.base64BinaryOpens in a new tab タイプのプロパティに自動改行を含めるようにできます。これを実行するには、以下のいずれかを実行します。

• Web サービス・クラスで、BASE64LINEBREAKS パラメータを 1 に設定します。

• Web サービス・クラス・インスタンスに対して、Base64LineBreaks プロパティを 1 に設定します。このプロパティの値は、BASE64LINEBREAKS パラメータによって設定される値より優先されます。

パラメータおよびプロパティの場合、既定値は 0 です。既定では、Caché Web サービスには %BinaryOpens in a new tab または %xsd.base64BinaryOpens in a new tab タイプのプロパティに対する自動改行は含まれません。

SOAP メッセージへのバイト・オーダー・マークの追加

既定の場合、Caché Web クライアントによって送信されるメッセージの先頭に BOM (バイト・オーダー・マーク) はありません。

メッセージはバイト・オーダーの問題がない UTF-8 としてエンコードされるため、通常 BOM は必要ありません。ただし、SOAP メッセージに BOM を組み込むことが必要であったり、推奨される状況があります。この BOM は単にメッセージが UTF-8 であることを示すものです。

Caché Web クライアントで送信されるメッセージに BOM を追加するには、クライアントの RequestMessageStart プロパティを設定します。このプロパティは、メッセージの先頭に組み込むパーツのコンマ区切りのリストにする必要があります。これらのパーツは、以下のとおりです。

• DCL は、XML 宣言です。

  <?xml version="1.0" encoding="UTF-8" ?>
  

  

• BOM は、UTF-8 BOM です。

既定は "DCL" です。

実際には、RequestMessageStart を以下の値のいずれかにすることができます。

• "DCL"

• "BOM"

• "BOM,DCL"

解析時にプロセス・プライベート・グローバルを使用する方法

既定では、Caché Web クライアントは通常、要求や応答を解析するときにローカル配列メモリを使用します。代わりに、プロセス・プライベート・グローバルを強制的に使用させることができます。これにより、Web クライアントは非常に大きいメッセージを処理できるようになります。

そのためには、以下のように Web サービス・クラスの USEPPGHANDLER パラメータを指定します。

Parameter USEPPGHANDLER = 1;

このパラメータが 1 の場合、Web クライアントは常に、要求や応答を解析するときにプロセス・プライベート・グローバルを使用します。このパラメータが 0 の場合、Web クライアントは常に、この目的のためにローカル配列メモリを使用します。このパラメータが設定されていない場合、Web クライアントは既定の動作になります。既定の動作は通常ローカル配列メモリの使用です。

このパラメータは実行時にオーバーライドできます。そのためには、Web クライアント・インスタンスの UsePPGHandler プロパティを設定します。

カスタム SOAP メッセージの作成

特別な場合として、Web クライアントでカスタム SOAP メッセージの送信が必要なことがあります。基本的な要件は以下のとおりです。

1. %SOAP.WebRequestOpens in a new tab のサブクラスを作成し、その LOCATION パラメータまたは Location プロパティを設定します。

2. このサブクラスで、SOAP メッセージを送信するメソッドを作成します。このメソッドは、%Library.CharacterStreamOpens in a new tab のインスタンスを作成し、送信する SOAP メッセージをそのインスタンスに配置します。メッセージの形式が正しいことを確認する必要があります。

3. 次に、このメソッドによって SendSOAPBody() メソッドが起動されます。

   method SendSOAPBody(Action As %String, 
                       OneWay As %Boolean = 0, 
                       Request As %CharacterStream, 
                       ByRef Response) as %Status
   

   

   • Action は、実行する SOAP アクションの名前を指定する文字列です。

   • OneWay は、メッセージが単方向かどうかを制御する true/false フラグです。

   • Request は、現在のロケールの文字セットで SOAP 要求の本文を組み込む %Library.CharacterStreamOpens in a new tab のインスタンスです。

   • Response は、参照によって文字ストリームか、%XML.NodeOpens in a new tab のインスタンスとして返される応答です。

     SendSOAPBody() を呼び出したときに Response が NULL である場合は、メソッドによって Response が %Library.CharacterStreamOpens in a new tab のインスタンスに設定されます。このストリームには、現在のロケールの文字セットで SOAP 応答の本文が格納されます。

     SendSOAPBody() を呼び出したときに Response が %Library.CharacterStreamOpens in a new tab のインスタンスである場合は、メソッドによって Response が更新され、現在のロケールの文字セットで SOAP 応答の本文が組み込まれます。

     SendSOAPBody() を呼び出したときに Response が %XML.NodeOpens in a new tab のインスタンスである場合は、メソッドによって Response が更新され、本文 DOM がポイントされます。

%SOAP.WebRequestOpens in a new tab は %SOAP.WebClientOpens in a new tab のサブクラスであるため、他のパラメータおよびプロパティの設定が必要な場合があります。このドキュメントで前述したように、SOAP ヘッダを追加することもできます。詳細は、%SOAP.WebRequestOpens in a new tab のクラス・ドキュメントを参照してください。

カスタムの HTTP 要求の指定

既定では、Caché Web クライアントを使用する場合、Web クライアントでは HTTP を使用して SOAP メッセージが Web サービスに転送され、その応答が受信されます。Web クライアントでは、自動的に HTTP 要求が作成されて、送信されますが、カスタムの HTTP 要求を作成することができます。そのためには、次の手順を実行します。

1. %Net.HttpRequestOpens in a new tab のインスタンスを作成し、必要に応じてプロパティを設定します。このクラスの詳細は、"Caché インターネット・ユーティリティの使用法" を参照するか、%Net.HttpRequestOpens in a new tab のクラス・ドキュメントを参照してください。

2. Web クライアントの HttpRequest プロパティをこのインスタンスと等しくなるように設定します。

これは、同一セッション内で SOAP サービスへの複数呼び出しをサポートする場合に特に便利です。既定では、Caché Web クライアントでは、同一セッションを使用した SOAP サービスへの複数呼び出しはサポートされません。この問題に対処するには、%Net.HttpRequestOpens in a new tab のインスタンスを新規作成し、それを 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 を使用します。

• mode は、SOAP 要求のタイプ ("SOAP" または "binary") を指定します。

• client は、Web クライアント・インスタンスの OREF です。

• action は、SOAPAction ヘッダの値を格納します。

• oneWay は、送信される本文がない場合には true です。

• method 引数は、呼び出されている Web メソッドの名前です。

• requestStream 引数は、ストリームの SOAP 要求メッセージを格納します。

%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 サービスに転送され、その応答が受信されます。ユーザ独自の転送クラスを定義し、使用できます。

Caché Web クライアントのカスタム転送の定義

Caché Web クライアントでカスタム転送を使用できるようにするには、カスタムの転送クラスを定義します。次に、Web クライアントのインスタンスを作成した後に、その Transport プロパティを転送クラスのインスタンスと等しくなるように設定します。

転送クラスに関する要件は、以下のとおりです。

• 転送クラスは、インスタンス化可能 (つまり、非抽象) である必要があります。

• 転送クラスは、以下で説明するように DoSOAPRequest() メソッドを実装する必要があります。

DoSOAPRequest() メソッドは、要求を Web サービスに転送して、応答を取得します。このメソッドのシグニチャは、以下のようにする必要があります。

Method DoSOAPRequest(webClient,action,requestStream, responseStream) As %Status 

• webClient は、Web クライアント・クラスの OREF です。

• action は、SOAP アクションを指定する %StringOpens in a new tab です。

• requestStream は、UTF-8 でエンコードされた要求を含むストリームです。

• responseStream は、DoSOAPRequest() が応答の記述に使用する %FileBinaryStreamOpens in a new tab 引数です。このストリームでは、?xml 指示文のエンコード属性で指定した文字セットにデータを含める必要があります。UTF-8 の使用をお勧めします。

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 認証を使用できます。そのためには、以下の操作を実行します。

• Web メソッドを呼び出す前に、Web クライアントの HttpUsername プロパティと HttpPassword プロパティを設定します。

• Web クライアントと、Web サービスをホストする Web サーバの間で、SSL が使用されていることを確認します。ユーザ名とパスワードはクリア・テキストで送信されるので、この手法は、SSL を使用しないとセキュリティで保護されません。このドキュメントで前述の “SSL を使用するようにクライアントを構成する方法” のセクションを参照してください。

この方法は、WS-Security よりも安全性が低いですが、Web サービスによっては、この方法を使用する必要のある場合があります。