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