Cisco Prime Service Catalog 12.0 統合ガイド

ヘッダー ベース認証による nsAPI の呼び出し

RESTful nsAPI 呼び出しは、発信者が自身を認証できる場合にだけ処理されます。これは、ブラウザを介して以下のページでユーザが Prime Service Catalog に最初にログインするときに似ています。

http://<serverURL>/RequestCenter

次に、Service Catalog に正常にログインすると、ブラウザのアドレス バーに有効な nsAPI REST の URL を入力します。例を以下に示します。

次のような応答 XML がブラウザに表示されます。

REST API 要求がアプリケーションにログインする前に実行された場合、URL は次のエラーを返します。

RESTful nsAPI 呼び出しの認証

HTTP ヘッダーには、次のパラメータを含める必要があります。

username=<username>

password=<password>

すべての nsAPI および RAPI 要求で、HTTP Header- acceptEncryptedPassword=true が設定されていれば、パスワードは暗号化されていると見なされます。

パスワードは、次の場合に暗号化されます。

• Accept Encrypted Password の値が、[管理（Administration）] > [設定（Settings）] ページで有効（オンに設定）になっており、HTTP ヘッダーで false に設定されている場合。
• Accept Encrypted Password の値が、[管理（Administration）] > [設定（Settings）] ページで無効（オフに設定）になっており、HTTP ヘッダーで true に設定されている場合。

（注） password 属性の暗号化された値と cloudpassword 属性のクリアテキスト値を非表示にするには、newscale.properties ファイルのパラメータ nsapi.directory.person.hide.secure.information を true に設定します。

認証が成功すると、HTTP 応答で JSessionID cookie が返されます。後続の nsAPI の呼び出しで認証を再度行わずにセッションを維持するには、この呼び出しの要求に同じ JSessionID cookie を含める必要があります。

認証時の応答コードは、ユーザ アカウントのパスワードの期限切れや失敗したパスワード試行により、ロックされているかどうかが示されます。ユーザ アカウントのロックを解除するには、システム管理者に問い合わせてください。

（注） また、ユーザ認証の応答コードは、ユーザ アカウントが猶予期間であるかどうかと、ユーザ パスワードの更新期限の日付も示します。

パスワード ポリシーの詳細情報については、『Cisco Prime Service Catalog Administration and Operations Guide』の「Enforcing Password Policies」を参照してください。

API セッションは、セッション タイムアウトが発生するか、または任意のユーザに nsapi ログアウトが呼び出された場合に、非アクティブになります。nsapi を使用したログアウトの URL は次のとおりです。

次の API は、セッションがまだ有効であるかどうかを確認するために使用されます。クライアント インターフェイスは、セッションが有効な場合は HTTP コード 200 を、それ以外の場合は HTTP 401 コードを返します。

次のような応答 XML がブラウザに表示されます。

Service Catalog アプリケーションのセッションのタイム アウト設定に関する詳細情報については、『 Cisco Prime Service Catalog Administration and Operations Guide 』の「Site Administration」の章を参照してください。

（注） いずれかの nsAPIs が（nsAPI ログインを呼び出すことなく）クレデンシャルにより直接呼び出された場合、セッションは応答の送信後に自動的に終了する必要があります。nsAPI ログインが明示的に呼び出された場合、nsAPI ログアウトが手動で呼び出されるか、API タイムアウトの新しい管理設定（[管理設定（Administration Settings）] > [APIタイムアウト（API Timeout）]）に基づいてセッションがタイムアウトしない限り、nsAPI セッションは自動的に終了しません。

（注） nsAPI をクロスサイト リクエスト フォージェリ（CSRF）によるセキュリティ脆弱性から保護するには、newscale.properties ファイルの session.token.validation の値を 1 に設定します。さらに、セッションに認証トークンを提供する場合、後続の nsAPI 呼び出しにユーザ ID とパスワードを入力する必要はありません。

トークン ベース認証の使用

Prime Service Catalog はトークン ベースの認証メカニズムをサポートしています。要求（呼び出し）ごとにユーザ名とパスワードで認証を行うのではなく、1 回認証して、期間限定のトークンを代わりに取得できます。トークンを（GET 要求を使用して）入手したら、ユーザ名とパスワードを入力しなくても、後続の RESTful 呼び出しにそのトークンを使用できます。

トークン ID の取得

次の nsAPI GET 呼び出しでトークンを要求します。HTTP ヘッダーに有効なユーザ名とパスワードが指定されていることを確認してください。

http://<ServerURL/RequestCenter/nsapi/authentication/token?persistent=true

サンプル応答：

<sessiontoken utid="P_D887A7375EC640D725A1D042FBFBEAFE"/>

トークン検証パラメータ値の設定

次のように、newscale.properties ファイルで session.token.validation パラメータの値を設定します。

session.token.validation=1

さらに、[管理（Administration）] > [設定（Settings）] タブの [API セッションタイムアウト（API Session Timeout）] フィールドで、トークン有効性のタイムアウト時間を設定します。

nsAPI の呼び出しに対するトークン検証の設定

Service Catalog からの nsAPI の呼び出しに対し、トークン ベースの検証を有効にできます。この設定は任意です。検証を制御するには、newscale.propertiesファイルでパラメータ session.token.nsapisc.validation を 1 に設定します。

アップグレードを行う予定で、外部システムからの既存の nsAPI 呼び出しがこのトークン ベース検証の影響を受ける場合は、このプロパティの値を 0 に設定することを検討してください。

（注） newscale.properties ファイルを変更したら、その都度、Service Catalog サーバを再起動する必要があります。

トークンの有効期限の指定

nsAPI で使用されるトークンが期限切れの場合、nsAPI の発信者に次のエラーが返されます。

<nsapi-error-response errorcode="AUTH_0014"> Token Invalid</nsapi-error-response>

トークンの使用

後続の REST ベースの nsApi 呼び出しには、REST 呼び出しから取得されたトークン ID を HTTP ヘッダーとして追加する必要があります（ユーザ名とパスワードは不要です）。

utid=<token_id>

サポートされているエンティティ

nsAPI でサポートされるエンティティは、次のカテゴリに分けられます。

サポートされる操作

次のタイプの操作が、nsAPI でサポートされています。

• すべてのエンティティのデータ取得に対する HTTP GET 操作
• 個人、アカウント、契約、課金レート、ポリシー、およびサービス項目のインスタンスを作成または更新するための HTTP POST 操作と PUT 操作。
• タスク処理を実行するため、およびサービス項目権限を付与/取り消すための HTTP POST 操作。
• アカウント、契約、課金レート、ポリシー、およびサービス項目インスタンスを削除するための HTTP DELETE 操作。

要求と応答の形式

すべての nsAPI は要求のコンテンツ タイプに「application/xml」の使用をサポートしています。次のエンティティは、application/json コンテンツ タイプもサポートしています。

• サービス項目（Service Items）
• アカウント、契約
• 課金レート、課金履歴
• ポリシーおよびポリシー アラート

デフォルトの応答のコンテンツ タイプは要求のコンテンツ タイプと同じですが、クエリ パラメータ「responseType」（xml または json）で上書きできます。

例：

サービスを追加して、新しい要求/カートを送信します。

Method: POST

REST URL:

/RequestCenter/nsapi/transaction/requisitions

ペイロード：

成功コード：201

応答エラー コード：REST/Web サービスのエラー メッセージの表を参照してください。

サービス オーダーでの RESTful API の使用

サービス オーダーまたはサービス要求の送信

Cisco Prime Service Catalog でサービス オーダーまたはサービス要求を送信するよう、RESTful クライアントを書き込むときには、次の手順を実行する必要があります。

1. サービスを発注するための RBAC 権限がある有効なユーザ アカウントを使用して、クライアントを認証します。

コマンドの発行

http://<ServerURL>/RequestCenter/nsapi/authentication/token?persistent=true

HTTP ヘッダーでユーザ名とパスワードを指定する

呼び出しが成功した場合、認証トークンを受信します。
<sessiontoken utid="P_D887A7375EC640D725A1D042FBFBEAFE"/>

2. JSON 形式で API ペイロードを作成します。オーダーが UI で送信された場合、これらのデータは通常、ユーザがオーダー フォームに入力したデータです。

どの Prime Service Catalog サービスに要求を送信する必要があるか、どのフォーム フィールド値を入力する必要があるかが把握されているものとして、サービス要求または要求のペイロードを作成します。

ペイロード：

サービスが他のユーザに対してオーダーされたことを示すには、「customerLoginName」フィールドを使用します。

（注） RBAC の設定で定義された権限に基づいて、別のユーザの代わりにオーダーできます。

前の手順で受信した認証トークン（sessiontoken utid=<token_id>）を、HTTP ヘッダーで指定します。

オーダーが正常に送信されると、Prime Service Catalog は成功コード：201 を返します。

応答のペイロードは次のとおりです。

応答エラー コード：REST/Web サービスのエラー メッセージの表を参照してください。

3. オーダーが入ったため、RESTful API クライアントは、要求 ID を使用します。この要求 ID は、オーダーのステータスを監視するために前の手順で受信したものです。
オーダーはサービス オーケストレーションと配信プロセスに応じて、完了までに数分から数日かかる場合があります。nsAPI クライアントは以前に受信した同じ utid=<token_id> トークンを利用する場合も、新しいトークンを取得するために認証を行う場合もあります。

オーダーのステータスを取得するために RESTful 呼び出しを実行する

HTTP Method: GET

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitionId>

または、ユーザがオーダーを行ったときに受け取った応答のペイロードには、要求のステータスを確認するために使用できる URL も含まれています。

カスタム ポータルに対して行ったオーダー/要求をキャンセルする場合は、カスタム ポータルのキャンセルを呼び出すことができます。

この場合、ポータルの基礎となる RESTful API クライアントが、Prime Service Catalog に対して対応する要求を発行します。

HTTP メソッド：DELETE

http://<ServerURL>/RequestCenter/nsapi/transaction/requisitionentries/<reqEntryId>?

ペイロードは不要です。

成功コード：200

応答エラー コード：REST/Web サービスのエラー メッセージの表を参照してください。

サービス オーダーのレガシー SOAP ベースの RAPI

ここでは、Service Catalog の Web サービスの使用方法について説明します。これには SOAP ベース版の API 要求（外部システムが Service Catalog 内のサービス要求を作成および管理できるようにする API である RAPI 2）を実装する Web サービスが含まれます。Web サービスには、サービス要求内の提供タスクや承認タスクの管理を許可し、Service Catalog の内容の確認を行う要求なども含まれます。

WSDL

作成した要求を検証するには、SOAP ベースの Web サービスの WSDL が使用できる必要があります。WSDL は次の場所にあります。

http://<ServerName>/RequestCenter/webservices/wsdl/

使用可能な WSDL について、次の表にまとめます。

ロールと機能の設定

Web サービスを利用できるのは、Web サービス モジュールに対する適切な権限が含まれるロールを持つユーザです。事前に設定されたロールにはこのような権限は含まれていないため、管理者は Organization Designer を使用して、1 つ以上のカスタム ロールを作成する必要があります。ロールを作成したら、Web サービスの権限を追加できます。

Web サービスの権限を次に示します。

• Service Catalog アクセス（Service Catalog Access）：この権限を持つユーザは、Service Catalog の Web サービスにアクセスできます。
• デマンド管理アクセス（Demand Management Access）： この権限を持つユーザは、自分のデマンド管理 Web サービスにアクセスできます。
• NSAPI アクセス（NSAPI Access）：この権限を持つユーザは、NSAPI Web サービスにアクセスできます。
• 要求アクセス（Requisition Access）：この権限を持つユーザのみが、自分の RequisitionService Web サービス要求にアクセスできます。認証されたユーザとイニシエータは同一人である必要があります。同一人でない場合、対応するエラー応答がスローされます。
• 要求システムアカウント（Requisition System Account）：この権限を持つユーザは、自分だけでなく他のユーザの RequisitionService Web サービス要求にもアクセスできます。認証されたユーザとイニシエータは同一人である必要はありません。
• REX APIアクセス（REX API Access）：この権限を持つユーザは、Catalog Deployer の機能にアクセスできます。
• タスクアクセス（Task Access）：この権限を持つユーザのみが、自分の ServiceManager TaskService Web サービス要求にアクセスできます。この権限は必須です。
• タスクシステムアカウント（Task System Account）：この権限を持つユーザは、自分だけでなく他のユーザの ServiceManager TaskService Web サービス要求にもアクセスできます。認証されたユーザとイニシエータは同一人である必要はありません。

Web サービスのクライアント コードの作成

Web サービスのクライアントは、Apache の CXF や Axis などのツールを使用してコーディングできます。

Axis 2 によるクライアント コードの作成

Axis 2 を使用して Web サービスのクライアントを生成するための詳細な説明とユーザ ガイドについては、Apache の Web サイトを参照してください。

soapUI を使用して axis2 クライアントを作成する手順の概要は次のとおりです。

手順 1 Axis 2 のライブラリをダウンロードします。

手順 2 Axis 2 ライブラリの場所を soapUI の [Preferences] メニューで設定します。

手順 3 [Tools] > [Axis 2 Artifacts] を使用して、クライアント コードを作成します。

クライアント コードを作成するときには、データバインディング方式として adb （Axis のデフォルト バインディング）を選択する必要があります。テスト ケース オプションも作成する必要があります。

クライアント コードが生成されます。テスト ケース内にメソッドのスタブが作成されます。このオブジェクトに正確に入力する必要があります。

Apache CXF によるクライアント コードの生成

CXF を使用して Web サービス クライアントを生成するための手順については、Apache の Web サイトを参照してください。

soapUI を使用して CXF クライアントを作成するために必要な手順は、次のとおりです。

手順 1 Apache CXF のライブラリをダウンロードします。

手順 2 CXF ライブラリの場所を soapUI の [Preferences] メニューで設定します。

手順 3 [ツール（Tools）] > [Apache CXF] を使用して、クライアント コードを作成します。

クライアント コードが生成されます。対象のクラスは次のとおりです。

このクラスには main メソッドがあり、WSDL で定義されているすべての処理をここから起動できます。これらの処理を起動するコードは、すでに用意されています。必要な各種変数を入力する必要があります。メソッドのスタブが作成されます。必要な操作は、オブジェクトを正しく入力することだけです。

要求管理のための Web サービス

RAPI 2 要求管理によって実行できる処理を、以下の表に要約します。

（注） RAPI 2 では、要求の送信にグローバル OOB 設定ではなく、OOB 権限が必要です。OOB 権限の詳細については、『Cisco Prime Service Catalog Designer Guide』の「Organization Design」の章を参照してください。

Web サービスの認証

Service Catalog で公開される Web サービスは、すべて認証される必要があります。認証されていない Web サービス コールは、遮断および停止する必要があります。

Service Catalog の Web サービスによる認証は、以下の方法で実行できます。

• セッションごとの認証
• 要求ごとの認証

認証されてないユーザは、Web サービス呼び出しを正しく実行することができません。グローバル設定の [Web サービスの有効化（Enable Web Service）] をオフにすると、Service Catalog の Web サービスにアクセスできなくなります。デフォルトでは、この設定はオフになっています。

セッションごとの認証

この方法では、ユーザは最初に Authentication Web サービス コールを実行して、ユーザを認証します。その後、サーバがそのユーザに対してセッションを確立します。このセッションが有効な間、ユーザはその他の Web サービス コールを実行できます。セッションごとの認証要求は、AuthenticationService WSDL に含まれています。

認証要求のフォーマットは以下のとおりです。

認証時のエラー コードは、ユーザ アカウントのパスワードの期限切れや失敗したパスワード試行により、ロックされているかどうかが示されます。ユーザ アカウントのロックを解除するには、システム管理者に問い合わせてください。

（注） また、ユーザ認証のエラー コードは、ユーザ アカウントが猶予期間であるかどうかと、ユーザ パスワードの更新期限の日付も示します。エラー コードの詳細については、REST/Web サービスのエラー メッセージを参照してください。

要求ごとの認証

この方法では、Web サービスを認証するための個別のコールはありません。ユーザは各 Web サービス コールの一部として SOAP ヘッダーに認証情報を入れて送信します。Service Catalog の Web サービスに対する認証ハンドラが、そのユーザを認証するかどうかを確認します。このユーザに対してセッションがまだ確立されていない場合は、ハンドラが認証情報を SOAP ヘッダーから読み取ります。認証情報が存在すれば、ハンドラがユーザの認証を試みます。認証情報がない場合や、有効でない場合、ハンドラはクライアントに対して該当するエラー コードおよびエラー メッセージと共に例外をスローします。

暗号化

SOAP ヘッダーに指定されるパスワードは、暗号化された形式だけを受け入れるように設定されている場合があります。暗号化パスワードを強制するには、Administration モジュールの [暗号化されたパスワードを受け入れる（Accept Encrypted Password）] 設定を有効にします。暗号化ユーティリティは、パスワードの暗号化された値を取得するサイト管理者ロールを持つユーザが使用できます。このユーティリティにアクセスするには、次のブラウザ ページを開きます。

http://<server>:<port>/RequestCenter/EncryptedPassword.jsp

Web サービスの認証メカニズム

Service Catalog で公開されている各 Web サービスには、関連付けられたシステム権限があります。認証ハンドラでも、指定したユーザが Web サービスにアクセス（または実行）できるかどうかを確認します。ユーザに適切なシステム権限があれば、ユーザは処理を続行できます。適切なシステム権限がない場合は、クライアントに対してエラー コードとエラー メッセージと共に例外をスローします。

SOAP 認証と Directory Integration との相互関係

Directory Integration がイネーブルでない場合は、SOAP 要求が発行される前に、指定したユーザが個人ディレクトリに存在している必要があります。

Directory Integration がイネーブルで、[ログイン（Login）] イベントに [個人のインポート（Import Person）] の処理が含まれている場合は、ユーザのプロファイルを入手する際に外部ディレクトリが確認の対象となり、その情報が個人ディレクトリに挿入されます。この方法を取るには、ディレクトリ情報に適切な Web サービス権限を付与するロールが含まれているか、ユーザが属する事業部（またはサービス チーム）にそのようなロールが事前に割り当てられている必要があります。したがって、使用する SOAP アカウントはデータベースに事前に入力し、これらのアカウントが要求を送信する前に、アカウントに対して適切な権限を割り当てておくことを推奨します。

Directory Integration が有効で、シングル サインオン（SSO）だけを行うように [ログイン（Login）] イベントが設定されている場合は、ディレクトリ イベントを完全にバイパスし、個人ディレクトリに対する単純認証にフォールバックするオプションがあります。デフォルトでは Web サーバへの SOAP 要求があり、SSO が成功した場合、SSO のユーザは、Web サービスのセッション ユーザになります。そのためには、SOAP ヘッダーにユーザ クレデンシャルを含めない必要があります。ただし、優先クレデンシャルが SOAP 要求ヘッダーに指定されている場合は、そのクレデンシャルを使用して、外部ディレクトリではなく、個人ディレクトリに対して認証を行います。つまり、SOAP ヘッダーのユーザ クレデンシャルの存在は、認証をローカルで行うか、または外部で行うかを制御します。

[ログイン（Login）] イベントの Directory Integration に外部認証の手順（SSO との組み合わせの有無にかかわらず）が含まれる場合、認証は必ずディレクトリ データソースに対して実行されます。

サービス定義の入手

getServiceDefinition 要求は、指定したサービスが記述されたメタデータを返します。要求を送信するには、このメタデータが必要です。グリッド ディクショナリを含むサービスにこの操作を使用することは、このリリースではサポートされていません。そのようなサービスに対して操作を呼び出すと、エラーが返されます。

getServiceDefinition 要求

この要求では、その定義を必要とするサービスの名前を指定します。

soapUI で、[getServiceDefinition] ノードの下にある要求の例（Request1）を右クリックして、[要求エディタの表示（Show Request Editor）] をクリックします。生成された要求が表示されます。疑問符（?）は、値を必要とするすべての XML 要素を示します。

図 2-1 要求

SOAP 要求にはエンドポイントを指定する必要があります。この要求のプロパティ（および上図のメニューバー）をよく見ると、エンドポイントがまだ定義されていないことがわかります。これを以下の RAPI 2 サービスのエンドポイントで置き換えます。

http://<ServerName>/RequestCenter/services/ RequisitionService

ここで、 RequisitionService は wsdl 名です。

次に、Request Editor のメニューバーにある [Creates a copy of this request] アイコン（ ）を使用して、この要求をコピーします。このプロトタイプの要求は参照用に残しておきます。コピーを使用して、疑問符の部分を置き換え、認証条件のほか、イニシエータやカスタマーのログイン名、対象とするサービスの名前などを入力します。

getServiceDefinition 応答

getServiceDefinition 要求を送信するには、Request Editor ウィンドウの左上にある [Submit request to specified URL] ボタン（ ）をクリックします。応答が [要求エディタ（Request Editor）] 内の要求の右側に表示されます。

getServiceDefinition に対する応答では、サービスについてのメタデータが返されます。以下の表に要約を示します。

各ディクショナリと、ディクショナリ内の各フィールドが記述されています。オーダー時点でディクショナリに対して指定されているアクセス コントロールは、正確な形式の submitRequisition 要求を記述するのに不可欠です。オーダー時点でカスタマーから読み込みおよび書き込み可能なディクショナリだけが応答に取り込まれます。これは、submitRequisition 要求に取り込む必要があります。

「New Standard Laptop Computer」に対する完全な getServiceDefinitionResponse は、「要求と応答の例」に記載してあります。

要求の送信

submitRequisition 要求を送信する前に getServiceDefinition 要求を実行する必要はありません。ただし、getServiceDefinition では、現在のサービスのバージョンに関する有効な submitRequisition メッセージの記述に必要な情報が返されます。

• サービスの現在のバージョンは必須です。バージョン番号は、サービス定義自体、または含まれているアクティブ フォーム コンポーネント、またはディクショナリが更新されたときに、必ず増分されます。
• getServiceDefinition 要求は、どのフィールドが必須であるか指定します。送信要求にはすべての必須フィールドのデータが含まれる必要があります。
• 送信する要求には、すべての必須ディクショナリとフィールドがリストされている必要があります。ディクショナリ、またはそれぞれのディクショナリ内のフィールドの表示順序は任意です。
• ブラウザ側でトリガされるように設定されたフォーム ルールは、Web サービスに影響しません。フォーム ルールによって入力される必要がある選択リストやデフォルト値がある場合、それらのルールが検証およびワークフローの開始前に実行されるように、After Submission イベントと関連付ける必要があります。
• getServiceDefinition 要求では、各フィールドに指定されているデフォルト値も返されます。これには、カスタマーまたはイニシエータ情報のための解決済みの Lightweight 名前空間などが含まれます。これらの値は通常は必須であり、submitRequisition 要求で指定する必要があります。
• サービスの定義にオプション（単一選択、複数選択、およびオプション ボタン）を伴うフィールドがあり、それらのオプションがアクティブ フォーム コンポーネントの [Display Options]（HTML Representation）ページを使用して定義されている場合、getServiceDefinition 要求を使用して、そのサービスに対する要求を送信できます。オプションがデータ取得ルールによって指定されているときも、サービス要求は送信できますが、そのフィールドの値が有効なオプションであるかどうかの確認は、送信側のプログラムの責任になります。

submitRequisition 要求では、My Services から要求が送信されるときに発生するオーダーの時間が、基本的に省略されます。条件付きルール、データ取得ルール、または ISF は、送信された要求と一緒には実行されません。したがって、このような仕組みがディクショナリ フィールドの値の指定や評価の実行に使用されている場合は、これらの値を指定するための別の手段を探す必要があります。グリッド ディクショナリを含むサービスにこの操作を使用することは、このリリースではサポートされていません。そのようなサービスに対して操作を呼び出すと、エラーが返されます。

submitRequisition 要求

オーダー時点で表示または編集が可能なディクショナリは、submitRequisition 要求の <section> ノードとして組み込む必要があります。すべての必須フィールドとその値を指定する必要があります。オプションのフィールドには値を指定する必要はありません（しかし、soapUI によって挿入された疑問符は削除する必要があります）。ディクショナリの順序とフィールドの順序は、サービス定義での順序と一致する必要はありませんが、フィールドは対応するディクショナリノードの下にある必要があります。

たとえば、ディクショナリ RC_ServiceLocation 内の ZipCode フィールドの値を「07201」に設定する XML は、以下のようになります。

submitrequisition の応答

要求を送信する要求が成功すると、応答には作成された要求の要求 ID と、その要求の他の属性が含まれます。

submitRequisitionResult 応答の属性を、次の表に要約します。

要求が失敗すると、エラー メッセージが返されます。発生する可能性のあるエラーは、「付録 B：RAPI のエラー メッセージ」に記載されています。エラー メッセージは、次の例に示すように、必ず「SOAP fault」という書式で表されます。

要求のリストの入手

getRequisitions と getOpenRequisitions の処理では、オープン状態の要求についての情報を返します。これらは要求に含めることのできる引数が異なります。

これらの処理は、要求の管理に役立つ場合があります。たとえば、オープンな状態の要求のリストが返されたら、その中から、ユーザ定義の期限を超えた特定のタイプ（特定のサービスについて）を調べることができます。

getOpenRequisitions 要求

getOpenRequisitions は、指定した最大数まで、オープン状態の要求をすべて返します。要求は、要求 ID の降順で返されます。この要求は、一部の古い Service Catalog 統合ポイントとの下位互換性のためだけにサポートされているため、Web サービスで使用しないでください。

getRequisitions 要求

getRequisitions は、指定した最大数まで、要求をすべて返します。返される要求の表示タイプやステータスを指定することもできます。この要求は、一部の古い Service Catalog 統合ポイントとの下位互換性のためだけにサポートされているため、Web サービスで使用しないでください。

要求のステータスの入手

getRequisitionStatus の処理では、指定した要求の承認やタスク プランのステータスに関する情報を返します。詳細度は、My Services ユーザが提供計画を表示した場合の内容と同程度です。

図 2-2 getRequisitionStatus

getRequisitionStatus 要求

この要求は、要求の現在のステータスに関する情報を返します。

GetRequisitionStatus 応答

要求を取得する要求が成功すると、その応答には要求に関する情報が含まれます。

get*RequisitionsResult 応答の属性を、以下の表に要約します。

要求へのコメントの追加

addComments によって、指定した要求にユーザのコメントを追加します。

addComments 要求

この要求では、指定したコメントを指定した要求に追加します。指定されたユーザは、要求にアクセスする権限を持っている必要があります。

要求のキャンセル

cancelRequisition は、指定したサービス要求をキャンセルするために使用します。要求に含まれるすべてのサービスがキャンセルされます。

cancelrequisitionentry は、サービス要求内にある指定したサービス（要求エントリ）をキャンセルします。要求内の唯一（または最後）のサービスの場合は、要求がキャンセルされます。そうでない場合は、ステータスは変更されないままになります。

タスク管理用の Web サービス

概要

タスク管理用の Web サービスから実行できる処理を、以下の表に要約します。

承認のリストの入手

getAuthorizations および getMyAuthorizations 操作は、「In Progress」である承認についての情報を返します。これらは要求に含めることのできる引数が異なります。

要求サービスの操作では、操作の対象となる Web Services Administrative ユーザ（SOAP ヘッダーで指定）や Service Catalog ユーザごとに個別のプロビジョニングを行いますが、それとは異なり、これらのタスク サービスの操作では、ユーザを 1 名のみ SOAP ヘッダーに指定できます。したがって、承認を入手または処理されるユーザは、Web サービス モジュールの Task Access 権限を持っている必要があります。手順は次のとおりです。

• この権限が含まれるロールを作成します。承認を実行する権限は My Services Professional ロールに含まれているので、このロールの子を作成します。

• Web サービスを使用して、自身の承認を確認または処理する必要のあるユーザに、このロールを割り当てます（追加するか、または My Services Professional の代わりとします）。

getMyAuthorizations 要求

getMyAuthorizations は、すべてのオープン状態の要求を、Service Catalog のクレデンシャルが SOAP ヘッダーに指定されているユーザに対して、指定されている最大数まで返します。要求は、要求 ID の降順で返されます。この要求は、JSR168 準拠の承認ポートレットでの使用だけがサポートされており、Web サービスでは使用できません。

getAuthorizations 要求

getAuthorizations は、リストで指定した承認から開始して、特定の承認の最大数まで、すべての承認を返します。返される要求の表示タイプやステータスを指定することもできます。この要求は、JSR168 準拠の承認ポートレットでの使用だけがサポートされており、Web サービスでは使用できません。

getAuthorizationsForUser 要求（内部用途のみ、非サポート）

これは上記の getAuthorizations とよく似ていますが、承認を入手する対象のユーザを指定できる userLoginName パラメータが追加されています。

getAuthorizationsForUser SOAP 要求の例

getAuthorizations 要求および getAuthorizationsForUser 要求に役立つパラメータ

承認の許可または拒否

応答は以下に示すとおりです（読みやすくするために書式化してあります）。

要求と応答の例

getServiceDefinition 応答

submitRequisition の応答の例

getMyAuthorizations の応答の例

REST/Web サービスのエラー メッセージ

以下のエラー メッセージにおいて数値を波カッコで囲んだ記号の部分（「{0}」など）は、実際のエラー メッセージではエラーの発生元となったオブジェクトの名前や ID で置き換えられます。