Caché SOAP の問題のトラブルシューティング
この章では、Caché での SOAP の問題の原因を特定する際に役に立つ情報を提供します。以下のトピックについて説明します。
-
WSDL を利用する際の問題 (SOAP ウィザードを使用する際の問題)
明らかにセキュリティに関係する問題については、"Caché Web サービスの保護" の “セキュリティの問題のトラブルシューティング” を参照してください。
トラブルシューティングに必要な情報
SOAP の問題の原因を特定するには、通常、以下の情報が必要です。
-
WSDL およびこれが参照するすべての外部ドキュメント。
-
(メッセージ関連の問題の場合) 何らかの形式のメッセージ・ロギングおよびトレース。以下のオプションがあります。
オプション SSL/TLS で使用可能かどうか HTTP ヘッダを表示するかどうか コメント Caché SOAP ログ はい いいえ セキュリティ・エラーの場合、このログは、SOAP フォルトに含まれるものよりも詳細を表示します。 CSP ゲートウェイ・トレース はい はい MTOM (MIME 添付) を使用する SOAP メッセージの問題の場合、HTTP ヘッダを表示することは重要です。 サードパーティのトレース・ツール いいえ ツールに依存 トレース・ツールの中には、送信された実際のパケットなど、下位レベルの詳細を表示するものもあります。これらの情報は、トラブルシューティングの際に重要になる場合があります。 これらのオプションについては、以降のサブセクションで説明しています。
また、フォルトを正しく処理して最適な情報を受け取るようにすることは非常に有効です。“SOAP フォルトの処理” を参照してください。
Caché SOAP ログ
Caché ネームスペースとの間でやり取りされる SOAP 呼び出しをログに記録するには、そのネームスペースで ^ISCSOAP グローバルの次のノードを設定します。
ノード | 目的 |
---|---|
^ISCSOAP("Log") | ログ記録の種類を指定します。以下の値のいずれかを使用します (大文字と小文字が区別されます)。
|
^ISCSOAP("LogFile") | 作成するログ・ファイルの完全なパスとファイル名を指定します。 |
ログには送信者または受信者が適切に示されるので、そのやり取りにどの Web サービスまたは Web クライアントが関係しているのかを確認することができます。
次に、ログ ファイルの一部の例を示します (この例では、読みやすいように改行が追加されています)。
01/05/2010 13:27:02 *********************
Output from web client with SOAP action = http://www.mysecureapp.org/GSOAP.AddComplexSecureWS.Add
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'
...
<SOAP-ENV:Header>
<Security xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
</SOAP-ENV:Header>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
01/05/2010 13:27:33 *********************
Input to web client with SOAP action = http://www.mysecureapp.org/GSOAP.AddComplexSecureWS.Add
ERROR #6059: Unable to open TCP/IP socket to server localhost:8080
string
以下の点に注意してください。
-
Caché XML ツールを使用すると、署名が行われた XML ドキュメントのシグニチャを検証して、暗号化された XML ドキュメントを解読できます。これらのタスクをそのネームスペースで実行する場合、ログにはそれらのタスクの詳細も含まれます。これについては、"Caché XML ツールの使用法" を参照してください。
-
Caché SOAP ログは、何もメッセージが送信されない (つまり、サービスとクライアントが同じマシン上に存在する) 場合でも SOAP 呼び出しをキャプチャします。
-
サーバ・エラーが発生した場合、SOAP ログへの書き込みは停止します。代わりにコンソール・ログを参照してください。詳細は、"Caché 監視ガイド" の “ログ・ファイルの監視” を参照してください。
CSP ゲートウェイの HTTP トレース
[CSP ウェブゲートウェイ管理] ページでは、CSP ページ (Web サービスなど) に送信した HTTP 要求と返信された応答をトレースするオプションを利用できます。"CSP ゲートウェイ構成ガイド" の “HTTP トレースの表示” を参照してください。
サードパーティのトレース・ツール
Web サービスのテストには、Wireshark、ProxyTrace、tcpTrace、XMLSpy、soapUI、Web Service Studio Express などのトレース・ツールを使用できます。これらのツールには、無償で利用できるものと、ライセンスが必要なものがあります。InterSystems では、これらのツールのいずれについてもその使用を特に推奨しているわけではありません。これらのツールの情報は一般情報として提供しています。
トレース・ツールを使用すると、実際のメソッド呼び出し、および応答を確認できます。トレース・セッションは、特定のポートで待ち受けし、そのポートで受信するメッセージを表示し、それらのメッセージを宛先ポートに転送し、応答を表示し、待ち受けるポートに応答を転送します。
例えば、http://localhost:57772/csp/gsop/GSOP.Divide.CLS に Caché Web サービスがあるとします。
また、そのサービスと対話するために作成された Caché Web クライアントがあるとします。この Web クライアントの LOCATION パラメータは、"http://localhost:57772/csp/gsop/GSOP.Divide.CLS" に等しくなります。
クライアントとサービスの間のメッセージをトレースするには、以下の 2 つの操作が必要です。
-
トレース・ツールで、ポート 8080 (例) で待ち受けし、宛先ポート 57772 を使用するトレース・セッションを開始します。
-
Web クライアントで、ポートとして 57772 の代わりに 8080 を使用するように LOCATION パラメータを編集し、再コンパイルします。
または、Web クライアントを呼び出すコードで、次のようにその Web クライアントの Location プロパティを変更します。
//reset location to port 8080 to enable tracing set client.Location="http://localhost:8080/csp/gsop/GSOP.DivideWS.cls"
これで、Web クライアントを使用するときに、トレース・ツールがクライアントと Web サービスの間のメッセージを傍受して表示するようになります。この例を次に示します。
上の部分は、クライアントによって送信される要求を示しています。下の部分は、Web サービスによって送信される応答を示しています。
WSDL を利用する際の問題
SOAP ウィザード (または、ウィザードが使用する %SOAP.WSDL.ReaderOpens in a new tab クラス) を使用する際に問題が発生した場合、その問題は以下のいずれかである可能性があります。
-
WSDL が SSL で保護されている。この場合、ウィザードによって以下のようなエラーが発行されます。
ERROR #6301: SAX XML Parser Error: invalid document structure while processing Anonymous Stream at line 1 offset 1
ウィザードを使用する際に SSL 構成を指定できますが、これを指定して、上記のエラーが発生する場合、SSL 構成は正しく指定されていません。代わりに、別の方法で WSDL にアクセスし、それをファイルにダウンロードして、ファイルの WSDL を使用することもできます。
-
WSDL がパスワードで保護されている。この場合、ウィザードによって以下のようなエラーが発行されます (行やインデントが変換し、前のシナリオとの違いがあることに注意してください)。
ERROR #6301: SAX XML Parser Error: Expected entity name for reference while processing Anonymous Stream at line 10 offset 27
このエラーが発生した場合は、パスワードが求められているかどうかを確認します。このドキュメントで前述した “SOAP ウィザードの使用法” の説明を参照してください。
-
WSDL が現在アクセスできない要素を使用する。この場合、ウィザードによって以下のようなエラーが発行されます。
ERROR #6416: Element 'wsdl:definitions' - unrecognized wsdl element 'porttype'
キーワードは unrecognized です。これは、WSDL が現在アクセスできない要素を参照することを示します。WSDL に <import> および <include> 指示文がないか慎重に確認してください。
import 指示文は以下のようになります。
<import namespace="http://example.com/stockquote/definitions" location="http://example.com/stockquote/stockquote.wsdl"/>
この場合の回避策は以下のとおりです。
-
プライマリ WSDL をファイルにダウンロードします。
-
参照する WSDL をファイルにダウンロードします。
-
参照する WSDL の新しい場所を参照するようにプライマリ WSDL を編集します。
同様に、相対 URL を使用して WSDL が他のドキュメントを参照するようにすることも可能です。以下はその例です。
xmlns:acme="urn:acme.com.:acme:service:ServiceEndpointInterface"
WSDL をファイルにダウンロードした場合、この相対参照は機能しません。この場合、参照先ドキュメントをダウンロードして、その新しい場所を使用するように WSDL を編集する必要もあります。
-
-
WSDL に複数のパートを伴う <message> 要素が含まれ、ドキュメント・スタイルのバインディングを使用する。この場合、ウィザードによって以下のようなエラーが発行されます。
ERROR #6425: Element 'wsdl:binding:operation:msg:input' - message 'AddSoapOut' Message Style must be used for document style message with 2 or more parts.
この場合、ウィザードの使用時に [ドキュメントスタイルのウェブメソッドでラップしないメッセージフォーマットを使用] オプションを選択します。
-
WSDL が無効。このような場合、SOAP ウィザードによってその問題を示すエラーが発行されます。以下に一例を示します。
ERROR #6419: Element 'wsdl:binding:operation' - inconsistent soap:namespace for operation getWidgetInfo
このエラー・メッセージは、<operation> 要素に関する問題を示しています。以下に、このエラーを生成する無効な WSDL の一部の例を示します。
<?xml version="1.0" encoding="UTF-8"?> <wsdl:definitions targetNamespace="http://acme.acmecorp.biz:9999/widget/services" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" = [parts omitted]> <wsdl:message name="getWidgetInfoRequest"> </wsdl:message> <wsdl:message name="getWidgetInfoResponse"> <wsdl:part name="getWidgetInfoReturn" type="xsd:string"/> </wsdl:message> <wsdl:portType name="Version"> <wsdl:operation name="getWidgetInfo"> <wsdl:input message="impl:getWidgetInfoRequest" name="getWidgetInfoRequest"/> <wsdl:output message="impl:getWidgetInfoResponse" name="getWidgetInfoResponse"/> </wsdl:operation> </wsdl:portType> <wsdl:binding name="VersionSoapBinding" type="impl:Version"> <wsdlsoap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="getWidgetInfo"> <wsdlsoap:operation soapAction=""/> <wsdl:input name="getWidgetInfoRequest"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://acmesubsidiary.com" use="encoded"/> </wsdl:input> <wsdl:output name="getWidgetInfoResponse"> <wsdlsoap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" namespace="http://acme.acmecorp.biz:9999/widget/services" use="encoded"/> </wsdl:output> </wsdl:operation> </wsdl:binding> [parts omitted]
この場合、<operation> の <input> パートで要求メッセージ (getVersionRequest) がネームスペース "http://acmesubsidiary.com" に含まれていることが示されているにもかかわらず、WSDL の前の部分でこのメッセージが "http://acme.acmecorp.biz:9999/widget/services" のように Web サービスのターゲット・ネームスペースであることが示されていることが問題です。
無効な WSDLドキュメントが、有効な XML ドキュメントである可能性もあるため、純粋な XML ツールを使用して WSDL を検証することは十分なテストとはいえません。いくつかのサードパーティ製 WSDL 検証ツールが提供されており、SOAP ウィザードから返される情報を使用して、WSDL を直接検証することもできます。
-
WSDL に、Caché でサポートされていない機能が含まれている。最初の章の “WSDL の利用” のセクションを参照してください。
メッセージを送信する際の問題
Caché Web サービスまたは Web クライアントと SOAP メッセージを送受信する際に問題が発生した場合、以下の一般的なシナリオのリストを検討してください。
-
SOAP メッセージには長い文字列または長いバイナリ値が含まれている可能性があり、かつ Caché で長い文字列演算を有効にしていない。この場合、Caché によって以下のいずれかのエラーがスローされます。
-
<MAXSTRING> エラー
-
データ型検証エラー (これには、他の原因がある可能性もあります):
ERROR #6232: Datatype validation failed for tag your_method_name ...
ウィザードで WSDL を読み取る場合、Caché では文字列タイプの入出力を %StringOpens in a new tab として表現できることが前提となっています。同様に、Caché では XML タイプ base64Binary の入出力をすべて %xsd.base64BinaryOpens in a new tab として表現できることが前提となっています。WSDL 内には、この入出力が長い文字列に関する制限を超えている可能性があることを SOAP ウィザードに通知するための情報が含まれていません。
このドキュメントで前述した “生成されたクラスを長い文字列に合わせて調整する方法” を参照してください。この情報は Web クライアントと Web サービスの両方に当てはまります。
-
-
Web サービスまたは Web クライアントが WS-Security ヘッダを受け取った可能性があるが、それらを認識できるように構成されていない。この場合、以下のような汎用エラーが発行されます。
<ZSOAP>zInvokeClient+269^%SOAP.WebClient.1
このようなエラーには、他の原因がある可能性もあります。このようなエラーが発生した場合は、まずメッセージに WS-Security ヘッダが含まれていないか確認し、含まれていた場合には、以下を Web サービスまたは Web クライアントに追加してリコンパイルしてください。
Parameter SECURITYIN="REQUIRE";
また、Caché によって (構成クラス内に) セキュリティ・ポリシーが生成された場合は、足りない詳細を提供するためにそのポリシーを編集する必要があります。"Caché Web サービスの保護" の “生成されたポリシーの編集” のセクションを参照してください。これを行わないと、上記のような汎用エラーが発生します。
-
Web サービスまたは Web クライアントが、SOAP 仕様に従って、必要とされるものよりもさらに具体的なメッセージ形式を要求している可能性がある (これは、Caché に含まれないサービスまたはクライアントの場合に発生する可能性があります)。インターシステムズでは、以下のシナリオが発生しました。ここでは、(ほぼ) 最も一般的なものから最も一般的でないものまでをリストしています。
-
Web サービスまたは Web クライアントで、メッセージがそのメッセージ内のすべての要素に xsi:type 属性を指定することを必要としている。この属性の使用を指定するには、“xsi:type 属性の使用の制御” を参照してください。この情報は、Web サービスと Web クライアントの両方に当てはまります。
-
NULL 文字列値に対して、Web サービスまたは Web クライアントが NULL 要素を (省略するのではなく) 要求している。この回避策として、NULL 文字列の引数の形式を制御できます。“NULL 文字列の引数が持つ形式の制御” を参照してください。この情報は、Web サービスと Web クライアントの両方に当てはまります。
-
Web サービスまたは Web クライアントが特定のネームスペース接頭語を要求している。Caché には、一般に、ネームスペース接頭語を指定する方法は用意されていません。
ただし、SOAP エンベロープの場合は、使用する接頭語を指定できます。“SOAP エンベロープ接頭語の指定” を参照してください。この情報は、Web サービスと Web クライアントの両方に当てはまります。
-
Web クライアントが、SOAP アクションを引用符で囲むよう要求している。この回避策については、“SOAP アクションに対する引用符の使用 (SOAP 1.1 のみ)” を参照してください。
-
Web サービスまたはクライアントが、各 SOAP メッセージの冒頭に BOM (バイト・オーダー・マーク) を要求している。SOAP メッセージはバイト・オーダーの問題がない UTF-8 としてエンコードされるため、BOM は必要ありません。“SOAP メッセージへのバイト・オーダー・マークの追加” を参照してください。この情報は、Web サービスと Web クライアントの両方に当てはまります。
これらの問題を示す症状は、使用しているサードパーティ製品によって異なります。
-
-
Web サービスまたは Web クライアントが WSDL に準拠していない可能性がある。これは、Caché Web サービスや Web クライアントでは発生しませんが、他のシナリオで発生することが考えられます。インターシステムズでは、以下のシナリオを認識しています。
-
メッセージに含まれる要素が WSDL によって要求されるネームスペース内にない。
-
メッセージに含まれる要素が WSDL と同じ順序でない。
サービスまたはクライアントが WSDL に準拠しているかどうかを確認するには、メッセージを WSDL と照合します。
または、サードパーティの Web サービスの場合、その Web サービスが WSDL に準拠しているかどうかを確認するには、以下を実行すると便利です。
-
サードパーティ製ツールを使用して、Web クライアントを作成します。
-
メッセージをその Web クライアントから送信します。
-
これが成功した場合、Web サービスはその WSDL と整合性のあるメッセージを想定および送信し、問題の原因が他にあることが考えられます。その場合、このクライアントから送信されたメッセージを Caché クライアントから送信されたメッセージと照合します。
-
これが成功しなかった場合、Web サービスはその WSDL と整合性のあるメッセージを想定および送信しないことが考えられます。
-
-
-
Web サービスまたは Web クライアントが、Caché でサポートされていない形式のメッセージを送信する可能性がある。使用している WSDL を検証し、それが Caché でサポートされていることを確認すると便利です。最初の章の “WSDL の利用” を参照してください。これらの詳細は、Caché で徐々に変更されてきていることに注意してください。