この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
• 「概要」
この章では、Cisco Service Portal(Service Portal)の Web サービスの使用について説明します。内容には、Requisition API(RAPI 2)を実装するサービスも含まれています。この API を使用すると、外部システムから Request Center 内のサービス要求を作成および管理できます。Web サービスには、サービス要求内の提供タスクや承認タスクの管理、Request Center のサービス カタログや Demand Center サービス ポートフォリオの内容の確認などを行う要求も含まれます。
この章の対象読者は、Request Center と外部アプリケーションとの間の RAPI インターフェイスの実装を担当するプログラマや設計者です。以下の方法論や技術についての知識があると、このマニュアルの理解や有効活用の助けになります。
• SOAP メッセージや Web Service Descriptive Language(WSDL)などの Web サービス
Web サービスは、要求(サービス要求)や要求を構成するタスクを、外部アプリケーションから作成または更新するためのツールです。外部アプリケーションは、サービス要求の送信から Service Portal のインストール、あらゆる許可タスクや確認タスクの組み込み、およびあらゆるサービス提供タスクの実行など、要求履行プロセスの全部または一部を実行できます。外部アプリケーションは、SOAP メッセージを Service Portal に送信し、受信した応答を処理することでこれらの処理を実行します。
Web サービスの作成と実装に必要な前提条件を次に示します。次のものがあります。
• Web サービスをサポートするように設定された Service Portal インストール環境があること。
• Web サービス要求を送信し、応答を受信するためのクライアントを構築できる環境があること。
[Administration] > [Settings] でグローバル設定 [Enable Web services] をオンにする必要があります。これは、システムのすべての Web サービスを対象とするグローバル スイッチです。このグローバル設定がオフになっていると、Request Center の Web サービスを利用できなくなります。デフォルトでは、この設定はオフになっています。
作成した要求を検証するには、Web サービスの WSDL が使用できる必要があります。WSDL は次の場所にあります。
http://<ServerName>/RequestCenter/webservices/wsdl/
|
|
Web サービスを利用できるのは、Web サービス モジュールに対する適切な権限が含まれるロールを持つユーザです。事前に設定されているロールにこのような権限は含まれていないため、管理者は Organization Designer を使用して、1 つ以上のカスタム ロールを作成する必要があります。ロールを作成したら、Web サービスの権限を追加できます。
• Requisition Access :この権限のみを持つユーザは、自分の RequisitionService Web サービス要求にアクセスできます。認証されたユーザとイニシエータは同一人である必要があります。同一人でない場合、対応するエラー応答がスローされます。
• Requisition System Account :この権限を持つユーザは、自分だけでなく他のユーザの RequisitionService Web サービス要求にもアクセスできます。認証されたユーザとイニシエータは同一人である必要はありません。
• Task Access :この権限のみを持つユーザは、自分の ServiceManagerTaskService Web サービス要求にアクセスできます。
• Task System Account :この権限を持つユーザは、自分だけでなく他のユーザの ServiceManagerTaskService Web サービス要求にもアクセスできます。認証されたユーザとイニシエータは同一人である必要はありません。
• Service Catalog Access :この権限を持つユーザは、Service Catalog Web サービス要求にアクセスできます。
• Financial Management Access :この権限を持つユーザは、Service Portfolio Web サービス要求にアクセスできます。
このマニュアルで紹介するサンプルは、Web サービスの開発/テスト ツールである soapUI を使用して作成されたものです。このツールの無料版は、soapUI の Web サイトから入手可能です。プロフェッショナル版も利用できます。次に概要を示した手順は、使用するツールのバージョンによって異なることがあります。
soapUI をダウンロードしてインストールしたら、Web サービスを作成するためのワークスペースを作成します。サンプルの要求を作成し、Service Portal に送信された要求を検証するために使用する WSDL を含むプロジェクトを作成できます。プロジェクトを作成するには、初期 WSDL が必要です。後で同じプロジェクトに WSDL を複数追加することもできます。プロジェクトの作成中に [Create Requests] オプションをオンにしたままにすると、サンプル要求を生成できます。
Web サービスのクライアントを Axis 2 を使用して作成するための詳細な手順およびユーザ ガイドについては、Apache の Web サイトを参照してください。
ここでは、soapUI を使用して axis2 クライアントを作成するための大まかな手順を示します。
ステップ 1 Axis 2 のライブラリをダウンロードします。
ステップ 2 Axis 2 ライブラリの場所を soapUI の [Preferences] メニューで設定します。
ステップ 3 [Tools] > [Axis 2 Artifacts] を使用して、クライアント コードを作成します。
クライアント コードを作成するには、データバインディング方式として adb (Axis のデフォルトのバインディング)を選択する必要があります。テスト ケース オプションも作成する必要があります。
クライアント コードが生成されます。テストケース内にメソッドのスタブが作成されます。このオブジェクトに正確に入力する必要があります。
Web サービス クライアントを CXF を使用して作成するための手順については、Apache の Web サイトを参照してください。
soapUI を使用して CXF クライアントを作成するために必要な手順は、次のとおりです。
ステップ 1 Apache CXF のライブラリをダウンロードします。
ステップ 2 CXF ライブラリの場所を soapUI の [Preferences] メニューで設定します。
ステップ 3 [Tools] > [Apache CXF] を使用して、クライアント コードを生成します。
クライアント コードが生成されます。関連するクラスは次のとおりです。
RequisitionServicePortType_RequisitionServiceHttpPort_Client.java
このクラスには main メソッドがあり、WSDL で定義されているすべての処理をここから起動できます。これらの処理を起動するコードは、すでに用意されています。必要な操作は、必要となるさまざまな変数を入力することだけです。
RAPI 2 要求管理によって実行できる処理を、以下の表に要約します。
|
|
この章の例は、New Standard Laptop Computer サービスに対する要求を送信するために必要な XML を示しています。このサービスをオーダーするためのサービス フォームは、管理者ユーザからオーダーする場合、以下のようになります(管理者以外のユーザの場合は、フォームの先頭にある New Laptop ディクショナリは表示されません)。
Request Center で公開される Web サービスは、すべて認証される必要があります。認証されていない Web サービス コールは、遮断および停止する必要があります。
Request Center の Web サービスによる認証は、以下の方法で実行できます。
認証されてないユーザは、Web サービス コールを正しく実行することができません。グローバル設定の [Enable Web Services] がオフになっていると、Request Center の Web サービスは使用できません。デフォルトでは、この設定はオフになっています。
この方法では、ユーザは最初に Authentication Web サービス コールを実行して、ユーザを認証します。その後、サーバがそのユーザに対してセッションを確立します。このセッションが有効な間、ユーザはその他の Web サービス コールを実行できます。セッションごとの認証要求は、AuthenticationService WSDL に含まれています。
この方法では、Web サービスを認証するための個別のコールはありません。その代わりに、ユーザは各 Web サービス コールの一部として SOAP ヘッダーに認証情報を入れて送信します。Request Center の Web サービスに対する認証ハンドラが、そのユーザを認証するかどうかを確認します。このユーザに対してセッションがまだ確立されていない場合は、ハンドラが認証情報を SOAP ヘッダーから読み取ります。認証情報が存在すれば、ハンドラがユーザの認証を試みます。認証情報がない場合や、有効でない場合、ハンドラはクライアントに対してエラー コードおよびエラー メッセージと共に例外をスローします。
Request Center で公開されている各 Web サービスには、関連付けられたシステム権限があります。認証ハンドラでも、指定したユーザが Web サービスにアクセス(または実行)できるかどうかを確認します。ユーザに適切なシステム権限があれば、ユーザは処理を続行できます。適切なシステム権限がない場合は、クライアントに対してエラー コードとエラー メッセージと共に例外をスローします。
Directory Integration がイネーブルでない場合は、SOAP 要求が発行される前に、指定したユーザが個人ディレクトリに存在している必要があります。
Directory Integration がイネーブルで、Login イベントに Import Person 操作が含まれている場合は、個人のプロファイルを取得する際に外部ディレクトリが確認の対象となり、その情報が個人ディレクトリに挿入されます。この方法を取るには、ディレクトリ情報に適切な Web サービス権限を付与するロールが含まれているか、ユーザが属する事業部(部門)(またはサービス チーム)にそのようなロールが事前に割り当てられている必要があります。したがって、使用する SOAP アカウントはデータベースに事前に入力し、これらのアカウントが要求を送信する前に、アカウントに対して適切な権限を割り当てておくことを推奨します。
getServiceDefinition 要求は、指定したサービスが記述されたメタデータを返します。要求を送信するには、このメタデータが必要です。グリッド ディクショナリを含むサービスにこの操作を使用することは、このリリースではサポートされていません。そのようなサービスに対して操作を呼び出すと、エラーが返されます。
この要求では、その定義を必要とするサービスの名前を指定します。
soapUI で、[getServiceDefinition] ノードの下にある要求の例(Request1)を右クリックして、[Show Request Editor] をクリックします。要求が、作成されたときの状態で表示されます。疑問符(?)は、値を必要とするすべての XML 要素を示します。
SOAP 要求にはエンドポイントを指定する必要があります。この要求のプロパティ(および上図のメニューバー)をよく見ると、エンドポイントがまだ定義されていないことがわかります。これを以下の RAPI 2 サービスのエンドポイントで置き換えます。
http://<ServerName>/RequestCenter/services/ RequisitionService
ここで、 RequisitionService は wsdl 名です。
次に、Request Editor のメニューバーにある [Creates a copy of this request] アイコン( )を使用して、この要求をコピーします。このプロトタイプの要求は参照用に残しておきます。コピーを使用して、疑問符の部分を置き換え、認証条件のほか、イニシエータやカスタマーのログイン名、対象とするサービスの名前などを入力します。
getServiceDefinition 要求を送信するには、Request Editor ウィンドウの左上にある [Submit request to specified URL] ボタン( )をクリックします。応答が Request Editor 内の要求の右側に表示されます。
getServiceDefinition に対する応答では、サービスについてのメタデータが返されます。以下の表に要約を示します。
各ディクショナリと、ディクショナリ内の各フィールドが記述されています。オーダー時点でディクショナリに対して指定されているアクセス コントロールは、正確な形式の submitRequisition 要求を記述するのに不可欠です。オーダー時点でカスタマーから読み込みおよび書き込み可能なディクショナリだけが応答に取り込まれます。これは、submitRequisition 要求に取り込む必要があります。
「New Standard Laptop Computer」に対する完全な getServiceDefinitionResponse は、「要求と応答の例」に記載してあります。
技術的には、submitRequisition 要求を送信する前に getServiceDefinition 要求を実行する必要はありません。ただし、getServiceDefinition では、現在のサービスのバージョンに関する有効な submitRequisition メッセージの記述に必要な情報が返されます。
• サービスの現在のバージョンは必須です。バージョン番号は、サービス定義自体、または含まれているアクティブ フォーム コンポーネント、またはディクショナリが更新されたときに、必ず増分されます。
• getServiceDefinition 要求では、どのフィールドが必須であるかが指定されます。したがって、送信する要求にはすべての必須フィールドを確実に含めることができます。
• 送信する要求には、すべての必須ディクショナリとフィールドがリストされている必要があります。ディクショナリ、またはそれぞれのディクショナリ内のフィールドの表示順序は任意です。
• getServiceDefinition 要求では、各フィールドに指定されているデフォルト値も返されます。これには、カスタマーまたは発信者情報のための解決済みの Lightweight 名前空間などが含まれます。これらの値は通常は必須であり、submitRequisition 要求で指定する必要があります。
• サービスの定義にオプション(単一選択、複数選択、およびオプション ボタン)を伴うフィールドがあり、それらのオプションがアクティブ フォーム コンポーネントの [Display Options](HTML Representation)ページを使用して定義されている場合、getServiceDefinition 要求を使用して、そのサービスに対する要求を送信できます。オプションがデータ取得ルールによって指定されているときも、サービス要求は送信できますが、そのフィールドの値が有効なオプションであるかどうかの確認は、送信側のプログラムの責任になります。
submitRequisition 要求では、My Services から要求が送信されるときに発生するオーダーの時間が、基本的に省略されます。条件付きルール、データ取得ルール、または ISF は、送信された要求と一緒には実行されません。したがって、このような仕組みがディクショナリ フィールドの値の指定や評価の実行に使用されている場合は、これらの値を指定するための別の手段を探す必要があります。グリッド ディクショナリを含むサービスにこの操作を使用することは、このリリースではサポートされていません。そのようなサービスに対して操作を呼び出すと、エラーが返されます。
オーダー時点で表示または編集が可能なディクショナリは、submitRequisition 要求の <section> ノードとして組み込む必要があります。すべての必須フィールドとその値を指定する必要があります。オプションのフィールドには値を指定する必要はありません(しかし、soapUI によって挿入された疑問符は削除する必要があります)。ディクショナリの順序とフィールドの順序は、サービス定義での順序と一致する必要はありませんが、フィールドは対応するディクショナリノードの下にある必要があります。
|
|
たとえば、ディクショナリ RC_ServiceLocation 内の ZipCode フィールドの値を「07201」に設定する XML は、以下のようになります。
要求を送信する要求が成功すると、応答には作成された要求の要求 ID と、その要求の他の属性が含まれます。
submitRequisitionResult 応答の属性を、次の表に要約します。
|
|
要求が失敗すると、エラー メッセージが返されます。発生する可能性のあるエラーは、「付録 B:RAPI のエラー メッセージ」に記載されています。エラー メッセージは、次の例に示すように、必ず「SOAP fault」という書式で表されます。
getRequisitions と getOpenRequisitions の処理では、オープン状態の要求についての情報を返します。これらは要求に含めることのできる引数が異なります。
これらの処理は、要求の管理に役立つ場合があります。たとえば、オープンな状態の要求のリストが返されたら、その中から、ユーザ定義の期限を超えた特定のタイプ(特定のサービスについて)を調べることができます。
getOpenRequisitions は、指定した最大数まで、オープン状態の要求をすべて返します。要求は、要求 ID の降順で返されます。この要求は、一部の古い Request Center 統合ポイントとの下位互換性のためだけにサポートされているため、Web サービスで使用しないでください。
getRequisitions は、指定した最大数まで、要求をすべて返します。返される要求の表示タイプやステータスを指定することもできます。この要求は、一部の古い Request Center 統合ポイントとの下位互換性のためだけにサポートされているため、Web サービスで使用しないでください。
getRequisitionStatus の処理では、指定した要求の承認やタスク プランのステータスに関する情報を返します。詳細度は、My Services ユーザが配信計画を表示した場合の内容と同程度です。
|
|
要求を取得する要求が成功すると、その応答には要求に関する情報が含まれます。
get*RequisitionsResult 応答の属性を、以下の表に要約します。
|
|
配信計画での時点。(「Service Group Authorization」または「Delivery project for <service name>」など) |
|
この要求では、指定したコメントを指定した要求に追加します。指定されたユーザは、要求にアクセスする権限を持っている必要があります。
|
|
cancelRequisition は、指定したサービス要求をキャンセルするために使用します。要求に含まれるすべてのサービスがキャンセルされます。
cancelrequisitionentry は、サービス要求内にある指定したサービス(要求エントリ)をキャンセルします。要求内の唯一(または最後)のサービスの場合は、要求がキャンセルされます。そうでない場合は、ステータスは変更されないままになります。
応答は以下に示すとおりです(読みやすくするために書式化してあります)。
タスク管理用の Web サービスから実行できる処理を、以下の表に要約します。
|
|
getAuthorizations および getMyAuthorizations 操作は、「In Progress」である承認についての情報を返します。これらは要求に含めることのできる引数が異なります。
要求サービスの操作では、操作の対象となる Web Services Administrative ユーザ(SOAP ヘッダーで指定)や Request Center ユーザごとに個別のプロビジョニングを行いますが、それとは異なり、これらのタスク サービスの操作では、ユーザを 1 名のみ SOAP ヘッダーに指定できます。したがって、承認を入手または処理されるユーザは、Web サービス モジュールの Task Access 権限を持っている必要があります。次の手順を実行します。
• この権限が含まれるロールを作成します。承認を実行する権限は My Services Professional ロールに含まれているので、このロールの子を作成します。
• Web サービスを使用して、自身の承認を確認または処理する必要のあるユーザに、このロールを割り当てます(追加するか、または My Services Professional の代わりとします)。
getMyAuthorizations は、すべてのオープン状態の要求を、SOAP ヘッダーに Request Center のクレデンシャルが指定された個人に対して、指定されている最大数まで返します。要求は、要求 ID の降順で返されます。この要求は、JSR168 準拠の承認ポートレットでの使用だけがサポートされており、Web サービスでは使用できません。
getAuthorizations は、リストで指定した承認から開始して、特定の承認の最大数まで、すべての承認を返します。返される要求の表示タイプやステータスを指定することもできます。この要求は、JSR168 準拠の承認ポートレットでの使用だけがサポートされており、Web サービスでは使用できません。
上記の getAuthorizations とよく似ていますが、承認を入手する対象のユーザを指定できる userLoginName パラメータが追加されています。
|
|
応答は以下に示すとおりです(読みやすくするために書式化してあります)。
|
|
exportOfferingCostData 操作では、1 回以上のサービスについてのコスト情報がエクスポートされます。
getAllServiceOfferingStatus では、すべての提供サービスの名前と現在のステータスを入手します。
getServiceOfferingStatus では、指定した検索条件に名前が一致するすべてのサービスの名前とステータスを入手します。検索条件には任意の文字列を指定できます。検索では大文字小文字は区別されません。
getServiceOfferingStatus 要求の例を以下に示します。
メッセージ本文にユーザが指定するパラメータは必要ありません。
提供サービスごとに、応答には提供名とそのステータスが含まれます。
以下のエラー メッセージにおいて数値を波カッコで囲んだ記号の部分(「{0}」など)は、実際のエラー メッセージではエラーの発生元となったオブジェクトの名前や ID で置き換えられます。