この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章では、サービス カタログ(Service Catalog)の Web サービスの使用法について説明します。これには、SOAP ベース バージョンの要求 API(RAPI 2)を実装する Web サービスが含まれます。これは、外部システムが Service Catalog 内でサービス要求を作成および管理できるようにする API です。Web サービスには、サービス要求内の提供タスクや承認タスクの管理を許可し、Service Catalog の内容の確認を行う要求なども含まれます。
角カッコ(<>)で囲まれた要素は、適切なパラメータまたはパラメータ値を代入する必要があることを示します。
nsAPI は、次のように GET 操作においてエンティティのタイプに基づき多様なフィルタをサポートしています。
|
|
|
http://serverURL/RequestCenter/nsapi/directory/people/update |
||
http://serverURL/RequestCenter/nsapi/transaction/tasks/215/approve |
エンティティ名フィルタでワイルドカード検索を行う場合(?name=<value> など)、検索文字列の先頭のワイルドカード文字(「*」や「%」など)は無視されます。これらの文字が文字列の中または末尾にある場合は、ワイルドカード照合で適用されます。
名前検索で先頭のワイルドカード文字の使用を有効にするには、ContainsQueryInFnS プロパティを newscale.properties ファイル(RequestCenter.war/WEB-INF/classes/config にあります)で見つけ、値を true に設定します。
(注) このような検索操作は、システム パフォーマンスに悪影響を与える可能性があり、実稼働環境では一般的に推奨されません。
関連付けられているエンティティとは、プライマリ エンティティと一緒に取得される、ネストされたエンティティのことです。たとえば、個人がメンバとして属している OU などがあります。関連付けられているエンティティ名のフィルタは、ワイルドカード検索をサポートしません。このようなフィルタによる検索では、完全一致の結果のみが返されます。また、大文字小文字が区別されます。つまり、検索文字列内のワイルドカード文字は、照合の際にリテラルとして扱われます。次に例を示します。
組織内の正確に「star*OU」という名前の個人を返します。
複数のデータ行を返す操作では、ソート コントロールを使用できます。フィルタの場合と同様、ソート コントロールは REST URL のパラメータとして指定されます。
どのソート パラメータも REST URL に渡されない場合は、次の表に示すように、デフォルトのソート フィールドとソート順序が使用されます。
|
|
Row Id とは、サービス項目、標準、およびカスタム コンテンツ テーブルにレコードが挿入された物理的な順序を表します。これは、それらの各テーブルの PrimaryID というカラムに対応しています。
サービス項目、標準、およびカスタム コンテンツのエンティティはすべてのカラムのソートをサポートしています。他のエンティティは、特定のフィールドによるソートだけがサポートされています。詳細については、API リファレンスおよび例を参照してください。
複数のデータ行を返す操作では、ページ コントロールを使用できます。また、REST URL のパラメータとしても指定されます。
上記の各パラメータおよび返されるレコードの総数が、REST XML 応答のルート タグ内に属性として示されます。次に例を示します。
取得されるレコード数より大きい startRow を指定すると、HTTP 500 エラーが返されます。取得されるレコード数より大きい recordSize を指定すると、すべての行が返されます。
次の例では、Service Designer で 60 個のサービスが定義されており、Portal Designer の nsAPI 設定で指定できるレコードの最大数が 30 であると想定しています。
最初の 30 個のサービスが返されます。このような要求に対する応答の例は次のようになります。
4 番めのサービスから始まる 30 個のサービスが返されます。このような要求に対する応答の例は次のようになります。
4 番めのサービスから始まる 5 個のサービスが返されます。このような要求に対する応答の例は次のようになります。
4 番めのサービスから始まる 30 個のサービスが返されます。このような要求に対する応答の例は次のようになります。
ある種のエンティティにはネスト構造が含まれます。第 1 レベルの子だけまたは関連付けられたエンティティの取得は nsAPI によってサポートされます。親エンティティおよびその子エンティティを表にまとめます。
|
|
結果セットで複数行のデータを返すカテゴリ検索、サービス検索、または人の検索では、関連付けられたエンティティはパフォーマンス上の理由により取得されません。関連付けられたエンティティを利用できるのは、個々のエンティティに対する ID または名前による取得操作の場合だけです。
nsAPI コールは、Portal Designer モジュールで開発された JavaScript ポートレットで呼び出すことができます。JavaScript、REST URL、AJAX、または Ext JS コンポーネントを使用すると、ポートレットを作成して目的のエンティティのデータを取得し、グリッド形式でレンダリングできます。
以下に、Ext JS を使用してカテゴリのリストをレンダリングする例を示します。
現在ログインしているユーザの名前空間変数は JavaScript ポートレットで使用できるようになります。次に例を示します。
JSR ポートレットを介してアクセスした場合、nsAPI Java クライアントを使用してログイン操作およびログアウト操作を呼び出せます。
次に、ログインしているユーザの詳細情報を取得する、Spring ベースの JSR Portlet Controller の例を示します。
ここでは、エンティティの取得方法を示すサンプル コードの一部をいくつか示します。これらの方法の詳細については、個々のエンティティ クラスに関する Javadoc を参照してください。
ここでは、個人の作成および更新方法、ならびにタスクに対するアクションの実行方法を示すサンプル コードの一部をいくつか示します。これらの方法の詳細については、個々のエンティティ クラスに関する Javadoc を参照してください。
nsAPI の javadoc は、製品インストーラの Image フォルダにあります。REST URL および java クライアントから nsAPI を呼び出す例を、サポートされているエンティティごとに示します。
|
|
---|---|
特定の ServiceItemTypename のポリシーの作成 /RequestCenter/nsapi/serviceitem/definition/{serviceItemTypeName}/policies/create <policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy"> <paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/> <policyAction policyActionTemplateName="policyalert" executionOrder="1"> actionParamValue="Policy alert when Price is updated for a Laptop"/> <status-message code="POLICY_SUCCESS_003"> |
|
<policy policyType="update" accountName="bangalore" policyEnabled="true" executionOrder="1" dataTypeLogicName="SiLaptop" policyTemplateLogicName="updatecheckchange" policyId="33" name="Laptop Policy"> <paramValue policyParamLogicName="updatecheckchange-serviceitemattribute" paramValue="Price"/> <policyAction policyActionTemplateName="policyalert" executionOrder="1"> actionParamValue="Policy alert when Price is updated for a Laptop"/> <status-message code="POLICY_SUCCESS_003"> <value>Policy updated successfully.</value> |
|
<policy policyType="quota" name="Laptop Quota policy Fourth"> <status-message code="POLICY_SUCCESS_002"> <value>Policy deleted successfully.</value> |
|
|
---|---|
http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions |
|
ログインしているユーザに対して RBAC チェックが適用されます。 http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitionId> |
|
指定された要求 ID のすべての要求エントリのサービス フォーム データを取得します。応答は、各要求のサービス名、フォーム フィールドのデータ、および requisitionEntryId を含むリストです。応答は、XML 形式および JSON 形式で取得できます。 http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/id/<requisitioin_id>/requisitiondata |
|
/RequestCenter/nsapi/transaction/requisitions 応答エラー コード:表 REST/Web サービスのエラー メッセージを参照 |
|
/RequestCenter/nsapi/transaction/requisitions {"city":"Bangalore", "country": "India"}, {"city":"Mysore", "country":"India"} 応答エラー コード:表 REST/Web サービスのエラー メッセージを参照 |
|
/RequestCenter/nsapi/transaction/requisitions {"city":"Bangalore", "country": "India"}, {"city":"Mysore", "country":"India"} 応答エラー コード:表 REST/Web サービスのエラー メッセージを参照 |
|
/RequestCenter/nsapi/transaction/requisitions 応答エラー コード:表 REST/Web サービスのエラー メッセージを参照 |
|
/RequestCenter/nsapi/transaction/requisitionentries/{reqentry_id} 応答エラー コード:表 REST/Web サービスのエラー メッセージを参照 |
|
要求キャンセル nsAPI の cancelMonitorPlan オプションは、オープン オーダーのモニタ プランをキャンセルします。要求のステータスは Delivery Canceled に設定されます。 /RequestCenter/nsapi/transaction/requisition/{requisitionID}?cancelMonitorPlan=true 応答エラー コード:表 REST/Web サービスのエラー メッセージを参照 (注) cancelMonitorPlan オプションを実行する権限があるのは、サイト管理者ロールを持つユーザのみです。 |
|
nsXML で指定された入力に基づいてフォーム データを更新する http://<ServerURL>/RequestCenter/nsapi/transaction/updateServiceRequest <?xml version="1.0" encoding="UTF-8"?> <message channel-id="" is-autocomplete="false" is-published="true"> <task-started task-type="task"> <data-value multi-valued="false"> <name>GridUpdate-1.Name</name> <value>ordernamechanged4</value> <data-value multi-valued="false"> <name>GridUpdate-1.Roll</name> <value>orderrollchanged4</value> |
|
フィルタに使用可能なビューおよびステータスは、My Services の [Requisitions] タブにあるものに対応しています。 Status が指定されなかった場合は、「Ongoing」が使用されます。 ViewName が指定されなかった場合は、「Ordered for Self」が使用されます。
Status に指定可能な値:Ongoing、Preparation、Ordered、Closed、Canceled、Rejected、All。 誤った値が指定された場合、デフォルトの値(「Ongoing」および「Ordered for Self」)が使用されます。 http://<ServerURL>/RequestCenter/nsapi/transaction/requisitions/ViewName=<viewName>[|AND|Status=<status>] |
|
Customer Name、Owner(Initiator)Name、Requisition ID、Service Name、Started Date、Status、Submit Date |
|
|
|
(注) dueDate および dueDateRaw 属性は、非同期伝送設定が [管理(Administration)] > [設定(Settings)] モジュールで無効の場合だけ使用できます。 |
|
http://<ServerURL>/RequestCenter/nsapi/transaction/v1/orderform?serviceids=<list of service ids, comma seperated> |
|
フォームにグリッド ディクショナリが含まれている場合の出力例: (注) フィールドに複数の値がある場合、そのフィールドの値はリストとみなされ、そのフィールドには複数値フラグが表示されます。 |
|
フォームにグリッド ディクショナリが含まれている場合の入力例: (注) 要求送信 API のペイロードは、サービス フォーム詳細 API から取得できます。 |
1. これらの API をすべて使用するには、サービス項目の定義が存在している必要があります。
2. URL の「serviceItemLogicName」は有効な名前である必要があります。
b. 「作成」では、「更新」および「削除」とは異なり、同じサービス項目が以前にあってはなりません。
c. 入力 JSON の属性が SI 定義に存在する必要があります。
d. 親レコードでレコードを参照するためには、「作成」および「更新」API のいずれにも、その参照レコードが存在している必要があります。
e. 包含レコードは親レコードの更新シナリオに存在する必要はありません。
f. 親レコードの更新時に、「名前」を除く、それに含まれる子レコード データを更新できます。このためには所有者情報が一致する必要があります。
g. 子レコードにこれまで一度も所有者 SI がなかった場合は、ユーザが親レコードの更新を使用して、既存の SI レコードを包含レコードとして別の既存の SI(親)に追加する必要があります。
例:デスクトップ(親 SI)と CPU(子 SI)、およびこれら両方に別々に作成されるインスタンス(Desktop1 および CPU1)。ここで、Desktop1 を更新し、CPU1 がこれまで所有者 SI を持ったことがない場合は、CPU1 をこれに接続できます。この呼び出しによって、CPU1 は Desktop1 の包含レコードになります。
h. 更新時に、入力のすべての SI レコード(親レコードまたはそれに含まれる子レコード)はマージされ、保存される必要があります。既存の属性データは、それらの属性が更新 API の入力で指定されていない場合は、変更しないでください。
i. 参照レコードが親レコード更新で更新されることはありません。これらは、参照されるだけです。
j. 親レコードに 1 つの包含オブジェクトがあり、その包含レコードを親に含めない場合、含まれるのが単一値であれば入力として空のオブジェクト {} を渡し、含まれるのが複数値であれば空の配列 [] を渡す必要があります。
例:Harddisk - 単一値が含まれるタイプの属性 MultiHardDisk - 複数値が含まれるタイプの属性。
k. 既存の参照レコードを削除するために親を更新するには、入力構造が前述と同じである必要があります。
m. 更新 API の入力で属性が指定されない場合、その属性データは更新の実行によって変更されません。
4. 削除 API の場合、親レコードとそれに関連していたすべての子レコードが削除されますが、親レコードと関連していない参照レコードは削除されません。
5. 必要に応じ、 newscale.properties ファイルで serviceitem.nsapi.rbac.check プロパティを false に設定することで、nsAPI に基づいてサービス項目に対する RBAC チェックをバイパスすることができます。
次の表では、サービス項目に対して作成/更新/削除操作を行うための nsAPI URL について説明します。要求のコンテンツ タイプは、application/xml または application/json です。デフォルトの応答のコンテンツ タイプは要求のコンテンツ タイプと同じになります。つまり入力データが xml 形式であれば応答データも xml 形式になります。これらは、追加のクエリー パラメータ「responseType」を指定することにより、変更できます。パラメータで指定できる値は「xml」または「json」です。たとえば、xml で入力した場合、URL で responseType-json を指定すると、応答は json 形式で返されます。
nsAPI は、サービス項目および標準の権限の割り当てと取り消しに対してのみサポートされます。SI インスタンス データに対するレコード レベルの権限の定義は、SIM モジュールから、または nsAPI を使ってのみ可能です(Org Designer からはできません)。
|
|
---|---|
http://<ServerURL>/RequestCenter/nsapi/rbac/extensibleschema/grantpermission |
|
http://<ServerURL>/RequestCenter/nsapi/rbac/extensibleschema/revokepermission SIM RBAC に関連するすべての権限は、この nsAPI によって実行できます。
|
|
ヘッダー:<Username> <password> および <Content-Type=application/xml> Method=POST ヘッダー:<Username> <password> および <Content-Type=application/xml> Method=POST 特定のオブジェクトにユーザが付与/取り消しできる権限の詳細については、 特定のオブジェクトにユーザが付与/取り消しできる権限 の表を参照してください。 |
カスタム コンテンツは、サービス ポータルのコンテンツのソースとして機能する、ユーザ定義のテーブルにより構成されます。これらのテーブルは、標準と同様にポートレットのデータ ソースとして参照されます。
全カラム名のリスト、および各エンティティの説明については、『 Cisco Prime Service Catalog Designer Guide 』の「Designing Portals」の章にある「Reference Data」の項を参照してください。
|
|
---|---|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/service/{name} |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/category/{name} |
|
REST URL: rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/group/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/person/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/queue/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
http://<ServerURL>/RequestCenter/rexapi/entity/functionalposition/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/role/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/emailtemplate/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/agent/{name} rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/getdata rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
|
REST URL: http://<ServerURL>/RequestCenter/rexapi/entity/putdata rex xml の詳細については、「Rex XML 構造の例」を 参照してください 。 |
Prime Service Catalog の管理者はレート リミッタにより、許可される要求数および許可される要求の時間帯(秒数)をグローバルに設定します。
要求(外部アプリケーションからの要求、または Prime Service Catalog UI 内の要求)は、設定に従って受け入れられ、設定の制限を超えると拒否されます。
要求が拒否された場合、レート制限に対する HTTP 応答コード- 429 Too Many Requests (RFC 6585) が要求ユーザに返されます。
次のグローバルなデフォルト値がレート制限機能のために管理者によって設定されます。
さらに、管理者は次の修飾子を使用して、グローバル(デフォルト)値を上書きできます(特定の URL、1 つ以上のメソッドが上書きされます)。
(注) 時間帯は上書きできません。上書きでは毎回、グローバル設定を使用します。
(注) JSON の検証は手動で行います。設定ファイル nsAPIRateLimit.json を保存する際に、アプリケーションは JSON の検証を行いません。このため、無効な JSON の場合にアプリケーションが動作しないことがあります。
例外の性質に応じて、異なる HTTP 応答コードが nsAPI により返されます。
nsAPI は、指定されたフィルタについて結果が見つからない場合、または無効なフィルタ条件が指定された場合にエラー メッセージを返します。次に例を示します。
nsAPI でのメソッドの実行中に発生したすべての例外について、nsAPI は Java から NSAPIException をスローします。
次のチャートに、さまざまなエンティティ タイプでサポートされる操作についての要約を示します。
|
|
|
|
|
|
|
|
|
|
|
|
---|---|---|---|---|---|---|---|---|---|---|---|
|
|||||||||||
|
|||||||||||
|
|||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||||||||||
|
|||||||||||
|
|||||||||||