SOAP Web サービス クライアントに関するヒント

この記事には、以下のトピックが含まれています。
casm173
この記事には、以下のトピックが含まれています。
CA SDM インストールのサンプル ディレクトリには、Web サービス用のサンプル Java クライアント アプリケーションが用意されています。 このサンプルは、Web サービス クライアント アプリケーション開発に役立ちます。
Web サービス メソッドの多くは、入力パラメータとして配列を必要とします。 たとえば、createIssue() メソッドでは、propertyValues の空の配列を渡すことができます。 これらの配列は省略できる場合もありますが、その場合は空の配列を渡す必要があります。 Visual Studio .NET を使用して Web サービスにアクセスする場合は、以下のいずれかの方法で空の配列を指定します。
  • C# 言語
    String[] emptyArray = new string[0];
  • Visual Basic .NET
    Dim emptyArray As String() = {}
  • Java
    ArrayOfString attr = new ArrayOfString(); attr.setString(new String[0]); ArrayOfString is a proprietary class.
emptyArray は、空の配列を受け付ける配列パラメータに渡すことができます。
CA SDM Web サービスは、World Wide Web コンソーシアム(W3C)によって確立された標準の Apache 実装を使用しています。 オペレーティング環境の種類に関係なくクライアントがサービスにアクセスできることが理想ですが、ベンダの実装によってはアクセスできないこともあります。 多くのプログラム環境では、Web サービス記述用語(WSDL) からプロキシ クラスを生成するためのツールを提供しています。
Java クライアント
$NX_ROOT/samples/sdk/websvc 内の TableOfContents.doc に、Java サンプル プログラムが複数記載されています。
各サンプル プログラムには、スクリプト ファイル run_java_test_bat.txt (Windows)および run_java_test_sh.txt (UNIX)を使用してコンパイルおよび実行する方法を説明したメモが含まれています。 これらのスクリプトは、org.apache.axis.wsdl.WSDL2Java を使用して CA SDM Web サービスのクライアント側スタブ ファイルを生成する方法を示しています。
Axis 1.4 を使用する場合は、正常にスタブ ファイルを生成するために、-w パラメータが必要です。 記載されたとおりに WSDL2Java を実行すると、サブディレクトリ com/ca/www/UnicenterServicePlus/ServiceDesk 内にスタブ ファイルが生成されます。 以下のファイルが生成されます。
  • ArrayOfInt.java
  • ArrayOfString.java
  • ListResult.java
  • USD_WebService.java
  • USD_WebServiceLocator.java
  • USD_WebServiceSoap.java
  • USD_WebServiceSoapSoapBindingStub.java。
以下のステートメントを使用して、これらのクラスをインポートします。
import com.ca.www.UnicenterServicePlus.ServiceDesk.*;
Web サービス メソッドの多くには、独自のクラス ArrayOfString タイプのパラメータがあります。 たとえば、createRequest() メソッドの attrVals、propertyValues、および属性パラメータは、すべて ArrayOfString パラメータです。
ArrayOfString 変数に値を設定するには、変数をインスタンス化してから、以下のように setString() を使用します。
ArrayOfString attrVals = new ArrayOfString(); attrVals.setString(new String[]{"customer", customerHandle, "description", "description text"});
空に設定する方法
attrVals.setString(new String[0]);
List メソッドからの戻り値として、別の独自クラス ListResult タイプの次のような変数を使用します。doQuery()、getRelatedList()、getNotificationsForContact()、getPendingChangeTaskListForContact()、および getPendingIssueTaskListForContact()。 ListResult には listHandle および listLength エレメントが含まれており、以下の例で示すとおりに getListHandle() and getListLength() を使用して取得できます。
ListResult doQueryResult = new ListResult(); doQueryResult = USPSD.doQuery(sid, "iss", "active = 1"); int listHandle = doQueryResult.getListHandle(); int listLength = doQueryResult.getListLength();
getListValues() メソッドでは、listHandle を使用して、リストのサブセットから値を取得します。
freeListHandles() メソッドの Handles パラメータは、別の独自クラス ArrayOfInt です。 ListResult から取得した listHandle を使用して、 freeListHandles() を呼び出します。
ArrayOfInt handleList = new ArrayOfInt(); handleList.setInteger(new java.lang.Integer []{ new java.lang.Integer(listHandle) }); USPSD.freeListHandles(sid, handleList);
メソッドの中には、javax.xml.rpc.holders.StringHolder タイプの参照パラメータによる引き渡しがあるものもあります。 たとえば、createRequest() には、このタイプのパラメータが NewRequestHandle と NewRequestNumber の 2 つあります。
StringHolder NewRequestNumber = new StringHolder(); StringHolder NewRequestHandle = new StringHolder(); String result; result = USPSD.createRequest(sid, creatorHandle, attrVals, propertyValues, template, attributes, NewRequestHandle, NewRequestNumber);
これによって、Request のハンドルおよび参照番号(ref_num)は、NewRequestHandle.value および NewRequestNumber.value からそれぞれ取得できます。
SOAP Web サービス設定
CA SDM SOAP Web サービスは、専用の Web 環境設定ファイルのエントリを使用して設定できます。 以下の表に、設定オプションの名前および説明を示します。
オプション名
説明
design_mode_stubs
Web サービスを
デザイン モード
に設定します(CA SDM のみ)。
require_secure_logon
login() および loginService() Web メソッドを、https などの暗号化プロトコルを使用してコールする必要があります。
require_secure_connection
すべての Web メソッドを暗号化プロトコルを使用してコールする必要があります。
disable_user_logon
login() および loginService() の両方の Web メソッドを無効にするため、ログインには loginServiceManaged() だけが使用できます。
CA SDM では、Web サービス メソッドに渡された属性値の長さを検証することにより、実行している Tomcat サーバの完全性を保護しています。 デフォルトでは、属性値の長さが 900,000 バイトを超えると Web サービス コールは Axis エラーを返します。
以下のパラメータを deploy.wsdd ファイルに設定します。
  • fatal_max_string_length
    Web サービス メソッドが受け付ける属性値の最大長を設定します。
    デフォルト:
    900,000 バイト
  • validate_parameters
    属性値の長さのチェックを実行するかどうかを設定します。 検証をオフにする場合は、このパラメータを 0 に設定します。
    デフォルト:
    1 (オン)
  • exception_methods
    属性値の長さの検証から除外する Web サービス メソッドのカンマ区切りリストを表示します。
Web サービスの再展開
新しい環境設定は、CA SDM Web サービスを再展開すると有効になります。 Web サービスを再展開するには、以下の手順に従います。
  1. コマンド プロンプトを開き、CLASSPATH 環境変数に必須の Axis jar ファイルを組み込みます。必須の Axis jar ファイルは /java/lib にあります。
    たとえば、Windowsで設定する場合は、以下のコマンドを実行します。
    set AXISHOME=%NX_ROOT%\java\lib set classpath= %AXISHOME%\axis.jar;%AXISHOME%\jaxrpc.jar;%AXISHOME%\saaj.jar;%AXISHOME%\commons-logging.jar;%AXISHOME%\commons-discovery.jar;%AXISHOME%\wsdl4j.jar;%AXISHOME%\log4j-1.2.8.jar;%classpath%;
  2. ディレクトリを /sdk/websvc/R11 に変更し、以下のコマンドを実行します。
    java org.apache.axis.client.AdminClient undeploy.wsdd java org.apache.axis.client.AdminClient deploy.wsdd
  3. CA SDM サービスをリサイクルして、Tomcat をリサイクルします。 以下のコマンドを使用して Tomcat をリサイクルするだけで、CA SDM システム全体のシャットダウンを回避できます。
    pdm_tomcat_nxd - c stop pdm_tomcat_nxd - c start
    Web サービスが再展開されます。
  4. 以下のデフォルト URL の Axis サービス一覧ページを表示して、実際に Web サービスが展開されていることを確認します。
    http://<servername>:< port>/axis/services
    実際の URL は、インストールの設定によって異なります。
SOAP エラー処理
Web サービス メソッドにエラーが発生した場合、SOAP Fault が返されます。 SOAP Fault は Web サービスで発生する例外情報を返すための標準的な方法です。
SOAP Fault メッセージには標準化された および エレメントが含まれますが、重要なほとんどの情報は エレメントに記述されています。 エレメントには と エレメントが含まれます。 エレメントでは、CA SDM またはナレッジ管理製品に固有のエラー コードの列挙が返されます。 エレメントには、エラーを説明する英語の文字列が含まれています。 エレメントは開発者が使用するのに適した内容です。ユーザに対してはより適切なメッセージを表示する必要があります。
以下の例は CA SDM getObjectValues() メソッドに不正なパラメータが渡された場合の SOAP Fault です。
<soap:Fault> <faultcode>soap:Client</faultcode> <faultstring>Error on fetch with attribute list:persistent_id,first_name,last_nameParamErrorHere<faultstring> <detail> <ErrorCode>1001</ErrorCode> <ErrorMessage>Error on fetch with attribute list: persistent_id,first_name,last_nameParamErrorHere </ErrorMessage> </detail> </soap:Fault>
Microsoft .NET の管理コードを使用して作成されたクライアントを使用している場合は、Web サービス メソッドのコールに失敗すると「SOAPException」例外が発生します。 エラーが発生すると、呼び出された操作がキャンセルされます。
エラーがサーブレット コンテナによって書き込まれる場合は、サーブレット コンテナのログに表示されます。 それ以外の場合、エラー情報は CA SDM のログに書き込まれます。 これらのログは以下のサブディレクトリに配置されています。
  • CA SDM インストール ディレクトリ内の /bopcfg/www/CATALINA_BASE/logs サブディレクトリ
  • CA SDM インストール ディレクトリ内の /log サブディレクトリ、およびプレフィックスが「stdlog」のすべてのログのサブディレクトリ
これらのログを定期的に監視することをお勧めします。サーバは、独自のエラーを CA SDM Web サービスに報告せずにログに記録してしまうことがあるためです。
ロック エラー
更新中の CA SDM のオブジェクトはロックされます。 オブジェクトを更新するメソッド(updateObject() または transfer() など)は以下のロック エラー コードを返すことがあります。
UDS_LOCK_ERR
このコードは、別のユーザがレコードを更新していることを示します。 多くの場合、ErrorMessage エレメントには、ロックしているユーザのハンドルが返されます。
タイムアウト
CA SDM サーバの負荷が高い場合は、メソッドの実行に時間がかかることがあります。 まれに、個々のプロセスが応答に失敗したり、他のエラーが発生したことが原因となり、メソッドの実行結果がまったく返されないことがあります。 必要以上に動作が停止することを避けるため、Web サービス メソッドは一定時間を過ぎるとタイムアウトになります。 Web サービス メソッドのタイムアウトは CA SDM サーバのタイム アウトのことで、Web サーバやネットワークなどのタイムアウトでは
ありません
J2EE アプリケーション サーバがリサイクルされた後の初回アクセス時には、Web サービスに数秒の遅れが生じます。 これは、アプリケーションが初期化中であったり、DLL やライブラリなどをロード中であるためで、Web サービス メソッドの 1 回目のコール時のみ発生します。 それ以降のコールでは、これよりも早く結果が返されます。
メソッドがタイムアウトになった場合、以下のエラー コードが返されます。
UDS_TIMEOUT_ERR
操作が中止されたわけではありません。 サーバは、リクエストを受信した可能性があり、その場合、時間はかかりますが正常に処理されます。
doSelect( )
メソッドを使用して数千のレコードを取得する場合に、このタイプの問題が発生することがあります。
doSelect
メソッドの詳細については、「CA Service Desk Manager 参照コマンド」を参照してください。
エラー コード
Web サービス コールで返される可能性のある SOAP Fault の 値は以下のとおりです。
エラー名
説明
UDS_OK
0
正常。
UDS_FAILURE
1
一般エラー。システム ログを確認してください。
UDS_BAD_PARAM
1000
メソッドに不正なパラメータが渡されました。 このエラーは、必要なパラメータが見つからない場合、渡されたタイプが正しくない場合、または無効な値が使用された場合に発生します。
UDS_INTERNAL_ERR
1001
内部エラーが発生したことを示します。 返される配列とシステム ログに説明が記述されています。
UDS_LOCK_ERR
1002
別のユーザやプロセスがロックしているオブジェクトを更新しようとしました。 通常、オブジェクトをロックしている連絡先の ID が戻りデータに返されます。
UDS_UPDATE_ERR
1003
オブジェクトの更新中にエラーが発生しました。 必要な属性がすべて設定されていることを確認してから、システム ログを確認してください。
UDS_CREATION_ERR
1004
オブジェクトの作成中にエラーが発生しました。 必要な属性がすべて設定されていることを確認してから、システム ログを確認してください。
UDS_NOT_FOUND
1005
検索メソッドによって一致項目、または指定オブジェクトが見つかりませんでした。 不正または無効なハンドルがメソッドに渡された場合に発生します。
UDS_SESSION_TIMEOUT
1006
現在のメソッドがタイムアウトになりました。CA SDM サーバの負荷が高い、またはメソッドが不正です。
UDS_SERVER_GONE
1007
CA SDM サーバ接続が失われました。UDS メソッドは機能しなくなり、すべてのリスト参照は失われます。
UDS_FETCH_ERR
1008
リスト データの取得中にエラーが発生しました。
UDS_BAD_SESSION
1010
無効な SID が使用されました。
UDS_CNTXT_TIMEOUT
1011
SID がタイムアウトになりました。
UDS_SECURE_CHANNEL_REQUIRED
1012
Web サービス(または Web サービス メソッド)にアクセスするにはセキュリティで保護されたチャネル(SSL など)が必要ですが、保護されていないチャネルを使用しようとしています。
UDS_SECURITY_VIOLATION
1013
試行した操作は CA SDM セキュリティに違反するため中止されました。
UDS_OVER_POLICY_LIMIT
3002
試行したリクエストはポリシーに定義された制限を越えるため拒否されました。