Cisco IP Solution Center API プログラマ ガイド 6.0
ISC API の概要
ISC API の概要
発行日;2012/02/04 | 英語版ドキュメント(2009/12/18 版) | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 2MB) | フィードバック

目次

ISC API の概要

API コンポーネント

クライアント

HTTP/HTTPS サーバ

HTTP 転送

HTTP 応答

HTTP 認証/暗号化

SOAP プラグイン

SOAP メッセージ

メッセージ検証/SOAP Fault

メッセージ セキュリティ

API 通知サーバ

API サーバ/サーブレット

操作

XML スキーマ

XML の例

サービス モデル

サービス オーダー/サービス リクエスト

サービス オーダーのライフ サイクル

サービス リクエストの修正

サービス オーダーの例

名前とロケータ ID

サービス定義

API エラー メッセージ

エラー ログ

ISC API の概要

Cisco IP Solution Center(ISC)Application Programming Interfaces(API; アプリケーション プログラミング インターフェイス)により、Operations Support System(OSS; オペレーション サポート システム)クライアント プログラムを使用して ISC システムに接続できます。ISC API は eXtensible Markup Language(XML)インターフェイス要求/応答システムを使用して、ISC サーバからのデータの挿入、取り出し、更新、および削除のメカニズムを提供します。ISC API は、メッセージの暗号化に Secure Hypertext Transfer Protocol(HTTPS)を使用し、ユーザ認証に Cisco Role-Based Access Control(RBAC)を使用することもできます。

ISC API は、HTTP/HTTPS/SOAP(Simple Object Access Protocol)インターフェイスを使用します。API 要求は、XML データを API サーバに送信することにより、HTTP/HTTPS と SOAP の組み合わせを使用して実行されます。サーバは XML 応答を返します。これは、API 要求が正常に終了したかどうかを示すか、データを返す符号化された SOAP メッセージでもあります。

API は、データベース変更イベントに対して通知サーバを使用することもできます。データベース オブジェクトが作成、修正、または削除されるときはいつでも、またはスケジュールされたタスクがその実行を開始または終了するときに、イベントが登録され、通知が送信されます。イベント通知は XML 応答の形式で、クライアントまたは指定された URL に送信されます。

API を使用すると、ISC GUI で使用できる操作の一部を実行できます。詳細については、 付録 A「GUI と API のマッピング」 を参照してください。

本書では、すべての ISC サーバで共通な操作を実行するための API の使用法について説明し、ネットワークでの、MPLS、L2VPN、VPLS、FlexUNI/EVC、および TEM の各サービスのプロビジョニングの例を提供します。

この章の内容は、次のとおりです。

「API コンポーネント」

「操作」

「XML スキーマ」

「サービス モデル」

「API エラー メッセージ」

API コンポーネント

ISC API のメイン コンポーネントは次のとおりです。

クライアント:OSS クライアント プログラム。

HTTP/HTTPS サーバ:HTTP/HTTPS バインディング情報を処理する標準 HTTP/HTTPS Tomcat サーバ。

SOAP プラグイン:標準 Apache SOAP プラグイン。

API サーバ/サーブレット:SOAP メッセージを受け取り、SOAP 符号化を解除します。

API 通知サーバ:データベース変更イベント用の非同期通知に使用されます。ISC には、Tibco Event Bus を使用して発生するイベントが通知されます。

処理サーバ:特定の処理アクティビティを実行するサーバ。

データベース:ISC リポジトリ。

XML 検証スキーマおよびメタデータ:XML 符号化データの検証ファイル。

図 1-1 に、ISC API のメイン コンポーネントと XML メッセージのプロセス フローを示します。

図 1-1 API コンポーネント

 

これらのコンポーネントについては、以降の項で説明します。

クライアント

OSS クライアント プログラムであればどれでもクライアントとなります。クライアントは XML 要求メッセージを定型化し、XML 応答を受信します。API メッセージの生成には、XML フォーマットをサポートする任意の言語を使用できます。

クライアント インターフェイスは次のとおりです。

ISC API システムへのログイン

XML 要求の生成

API サーバへの要求の送信

API サーバからの応答の受信

XML 応答データ内容の解析


) API クライアントは、確実に実行を継続するため、回復不能例外(ConnectionException)を自分で処理する必要があります。


HTTP/HTTPS サーバ

ISC は Tomcat サーバを使用して HTTP/HTTPS バインディングを処理します。デフォルトのポートは次のとおりです。

HTTP:8030

HTTPS:8443

ISC のインストール時に別のポートを指定できます。詳細については、『 Cisco IP Solution Center Installation Guide, 6.0 』を参照してください。

HTTP 転送

API はメッセージの転送に標準 HTTP/HTTPS を使用します。HTTP 要求または応答のペイロードは SOAP メッセージです。個々の SOAP 要求は、HTTP POST を使用して Web サーバに送信されます。必須 HTTP ヘッダーは次のとおりです。

POST:最初のヘッダーは、この特定の POST が SOAP API 向けであることを示します。POST が含まれないすべての HTTP 要求は無視されます。

Content-type: text/xml:2 番目のヘッダーで、送信されるデータが XML であることが確認されます。このヘッダーがないと、HTTP 415 エラーが戻されます。

Content-length: <value in kilobytes>:3 番目のヘッダーは正の整数で 40 以内の値である必要があります。この値が 40 キロバイトよりも大きいと、HTTP 413 エラーが戻されます。

4 番目のヘッダーは SOAP メッセージの長さ(バイト単位)です。

XML 要求の HTTP ヘッダーの例を次に示します。

POST /soap/servlet/messagerouter HTTP/1.0
Host: server1.myhost.com:80
Content-type: text/xml
Content-length: 613
 

) HTTP ヘッダーは一定ではありません。HTTP ストリングを示す最新の HTTP ソフトウェアについては、ISC インストレーションに付属のクライアント ソフトウェアを参照してください。


HTTP 応答

HTTP プロトコルでエラーが検出された場合、該当する HTTP エラー メッセージが HTTP 応答で戻されます。SOAP 要求の処理に対して戻される HTTP 戻りコードの例を次に示します。

コンテンツの長さが 40 KB を超過している

HTTP/1.1 413 Request Entity Too Large
 

コンテンツ タイプが "text/xml" でない

HTTP/1.1 415 Unsupported Media Type
 

要求方式が POST 以外である

HTTP/1.1 405 Method Not Allowed
 

SOAP 要求の処理中に、エラーの有無にかかわらず、HTTP 戻りコード「HTTP/1.1 200 OK」を常に受け取ります。次の例を参照してください。

contacting: http://myserver.com:8030/soap/servlet/messagerouter
with: /tmp/tmp.2764
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 597
Date: Fri, 21 Feb 2003 15:43:58 GMT
Server: Apache Tomcat/4.0.1 (HTTP/1.1 Connector)
Set-Cookie: JSESSIONID=C2337537E4C568A7A6228022A3A39521;Path=/soap
 

HTTP 認証/暗号化

HTTP 認証はオプションで、HTTP 基本認証構成によって制御されます。ユーザ認証が強制実行される匿名アクセスを無効にする必要があります。

API メッセージを暗号化するには HTTPS(HTTP Secure Socket Layer(SSL))を使用できます。SSL はデフォルトではサーバで有効になっていません。SSL を使用するには、ISC インストール プロセスで HTTPS をインストールする必要があります。SSL 証明書がサーバにインストールされていると、HTTP ではなく HTTPS プロトコルを使用して要求を送信できます。


) ISC API は、リモート認証をサポートします。詳細については、「リモート認証」を参照してください。


SOAP プラグイン

ISC には、メッセージが SOAP プロトコルに準拠しているかどうか検証するため、SOAP プラグインが組み込まれています。SOAP は、次から構成される XML ベースのプロトコルです。

アプリケーションによって定義されたデータ タイプのインスタンスを表すための一連の符号化規則。

リモート プロシージャ コールおよび応答を示す規則。

メッセージの内容とメッセージの処理方法を記述するフレームワーク。

SOAP は、SOAP 対応サービスの展開、管理、および運用を行うためのサーバ サイド インフラストラクチャを提供します。


) ISC API は SOAP ライブラリによる SOAP フォーマット機能をサポートします。ただし、SOAP ライブラリ機能を必要としないサービス プロバイダーの場合、SOAP ライブラリは必要に応じて無効になることがあります。この機能がない場合は、ISC は SOAP 形式のメッセージの送受信に通常の HTTP/HTTPS ソケット メカニズムを使用します。SOAP ライブラリを無効にするには、ISC プロパティ ファイルに nbi.Writer.SoapEncapsulation=false(デフォルト設定)を設定します。このデフォルト設定により、SOAP カプセル化クライアントと SOAP 以外のカプセル化クライアントの両方を実行できます。純粋な SOAP 環境を実行している場合は、このアトリビュートを true に設定できます。


SOAP メッセージ

HTTP 要求/応答のペイロードは SOAP メッセージです。SOAP メッセージには、エンベロープ、ヘッダー、本文が含まれます。

soapenv-Envelope は、SOAP メッセージの内容とメッセージの処理方法について説明するフレームワークを定義します。

soapenv-Header はセッション データを定義し、メッセージ処理情報と、ペイロード データの形式に関する情報を含みます。

soapenv-Body エレメントには、ドメイン固有のデータである下位エレメント(操作、名前/値ペア、キー プロパティ)が含まれます。

soapenv-Fault エレメントには、SOAP 固有のエラー メッセージが含まれています。これらのメッセージは SOAP 本文で戻されます。

SOAP メッセージ エンベロープ

メッセージ エンベロープは名前空間の宣言に使用されます。SOAP メッセージは、メッセージ本文の最初のエレメントに関連付けられた XML 名前空間を使用して経路設定されます。SOAP エンベロープにおける名前空間の最初のブロックが、SOAP および XML 符号化の標準です。次の例を参照してください。

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns0="http://www.cisco.com/cim-cx/2.0"
xmlns:ns1="http://insmbu.cisco.com/urn:CIM">
<soapenv:Header>
<ns0:message id="87855" timestamp="2002-12-13T14:55:38.885Z"
sessiontoken="p36bttjwy1"/>
</soapenv:Header>
<soapenv:Body>
<ns1:createInstanceResponse/>
</soapenv:Body>
</soapenv:Envelope>
Responses
 

次の名前空間が太字で示されています。

xmlns:ns0="http://www.cisco.com/cim-cx/2.0" は、メッセージ ヘッダーのフォーマット機能を示すために使用されます。

xmlns:ns1="http://insmbu.cisco.com/urn:CIM" は、実行される操作と、データ モデルを示すために使用されます。

SOAP メッセージ ヘッダー

メッセージ ヘッダーには、メッセージ自体に関する情報が含まれます。メッセージ ID、メッセージのタイムスタンプ、セッション トークン、および待機フラグが含まれています。次の例で、SOAP ヘッダー情報を示します。

<soapenv:Header>
<ns0:message id="87855" timestamp="2002-12-13T14:55:38.885Z"
sessiontoken="p36bttjwy1" wait="true" waitTimeout="60" />
</soapenv:Header>
<soapenv:Body>
 

表 1-1 に、SOAP メッセージ ヘッダーの詳細を示します。

 

表 1-1 ヘッダー定義

要素
説明

メッセージ ID

クライアント要求および応答の追跡に使用する相関 ID。ISC はこの ID を無視します。

タイムスタンプ

メッセージが送信された時刻(Zulu 時間)。日時フォーマットの詳細については、「API リクエストの日付/時刻フォーマット」を参照してください。

セッション トークン

ログインで割り当てられ、システムへのアクセスに使用されるセッション ID。

待機フラグ

表 1-2 に説明があります。

待機フラグは SOAP メッセージ ヘッダーと特定の表示操作で指定されます。 表 1-2 に、XML 応答で戻される待機フラグを示します。待機フラグはオプションの要求アトリビュートです。

 

表 1-2 SOAP メッセージの待機フラグ

フラグ
適用対象
説明

level

enumerateInstance

正の整数

表示で戻されるオブジェクトの深さ。必要に応じて下位レベルのオブジェクトが抑制されます。

wait

ヘッダー

true | false

サービス リクエストが完了するまで接続を開いたままにしておくかどうか指定します。完了すると、サービス リクエストの状態が戻されます。デフォルトは false(待機なし)です。

waitTimeout

ヘッダー

インターバル(秒単位)

サービス リクエストの完了を待機する時間の最大値。ISC プロパティ ファイルに waitTimeout 値を設定できます。デフォルトは 20 分です。

(注) 待機がタイムアウトになると、サービス リクエストは、待機時間を超過していることを示すエラー メッセージを戻します。ただし、この要求は引き続き処理されます。


ヒント ISC がプロビジョニングでデバイスにアクセスできないようにするため、API を使用してデバイスをロックする手順の詳細については、「デバイスのロック」を参照してください。


SOAP メッセージ本文

SOAP エンベロープ内のメッセージ本文には、一連の操作が実装されます。SOAP 本文の先頭行はメソッド コールまたは操作で、この操作のオブジェクトは className で示されます。オブジェクトのアトリビュートは、各クラスのプロパティ(名前/値ペア)で指定されます。

新規サイトを作成する次の XML の例では、操作は createInstance で、className は Site です。Name、Organization、および SiteInfo のプロパティが含まれています。

<soapenv:Body>
<ns1:createInstance>
<objectPath xsi:type="ns1:CIMObjectPath">
<className xsi:type="xsd:string">Site</className>
<properties xsi:type="ns1:CIMPropertyList"
soapenc:arrayType="ns1:CIMProperty[]">
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">Name</name>
<value xsi:type="xsd:string">Site1</value>
</item>
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">Organization</name>
<value xsi:type="xsd:string">Customer2</value>
</item>
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">SiteInfo</name>
<value xsi:type="xsd:string">Site comment info</value>
</item>
</properties>
</objectPath>
</ns1:createInstance>
</soapenv:Body>
 

SOAP 本文に実装される操作の詳細については、「操作」を参照してください。

メッセージ検証/SOAP Fault

XML 要求の形式が不完全であるか、SOAP サーバに内部エラーが発生した場合、SOAP Fault メッセージを受け取ります。次の例を参照してください。

 
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns0="http://www.cisco.com/cim-cx/2.0"
xmlns:ns1="http://insmbu.cisco.com/urn:CIM">
<soapenv:Header>
<ns0:message id="87855" timestamp="2002-12-13T14:55:38.885Z"
sessiontoken="p36bttjwy1"/>
</soapenv:Header>
<soapenv:Body>
< soapenv:Fault>
<faultcode>SOAP-ENV:Client</faultcode>
<faultstring>Client Error</faultstring>
<faultactor/>
</soapenv:Fault>
</soapenv:Body>
 

さらに、XML 要求が検証に失敗してもエラーが生成されます。

例外メッセージが XML 応答の <Exception> XML タグ内でユーザに示されます。

よく発生するエラー メッセージは、ユーザに理解できるテキストに変換され、XML 応答の <Message> タグ内に示されます。

ISC エラー レポートについては、「API エラー メッセージ」を参照してください。

メッセージ セキュリティ

ISC API は、SOAP メッセージの次のセキュリティ方式をサポートします。

メッセージ セキュリティでは、API はトランスポート レイヤでの暗号化をサポートします。「HTTP 応答」を参照してください。

ユーザ セキュリティでは、API は Cisco Role-Based Access Control(RBAC)をサポートしてユーザ セッションを制御します。詳細については、「タスク」を参照してください。

API 通知サーバ

このサーバは、データベース変更イベントの非同期通知に使用されます。これは指定されたデータベース変更イベントを監視し、クライアント接続または URL を経由して、通知を送信します。


) 通知 URL は ISC プロパティ ファイル内に設定され、インストール時に指定できます。


詳細については、「イベント通知」を参照してください。

API サーバ/サーブレット

API サーバ(サーブレットとして実行)は、SOAP メッセージを受信し、SOAP 符号化を削除します。API サーバは、処理を開始する前に、メッセージの形式が正しいかどうかも検証します。

要求については、API は要求メッセージを適切な処理サーバに委任します。

応答については、処理サーバは要求をクライアントに返送します。

API は操作を同期化します。つまり、要求が出されると、要求ごとに応答が出されます。HTTP/HTTPS 接続が着信要求用に確立され、別の HTTP/HTTPS 接続が発信応答の受信用に使用されます。これらの接続は、必要に応じて解除と再確立ができます。

図 1-2 に、プロバイダー システム内のクライアント プログラムから ISC リポジトリへの XML 要求のプロセス フローと、XML 応答の戻りパスを示します。

図 1-2 プロセス フロー図

 

操作

処理サーバは、特定の処理アクティビティまたは操作を実行します。これらの操作は、ISC コンポーネント オブジェクトおよびサービス オブジェクト上で実行されます。API リポジトリ オブジェクト モデルには、すべてのオブジェクト関係、アトリビュート、および操作が含まれています。

API 操作は 3 つのカテゴリ(一般、特殊、応答)に分かれています。

一般操作は、ISC コンポーネント オブジェクト上で実行されます。

createInstance:オブジェクトの作成

deleteInstance:オブジェクトの削除

modifyInstance:オブジェクトの編集

execQuery:SQL ベースのクエリー

execReport:設定済みレポート クエリーおよび SLA レポート クエリー

execMethod:デバイス ロックに使用

enumerateInstances:複数オブジェクトの取得、またはオブジェクトのプロパティの表示

特殊操作はシステムへのアクセスに使用されます。

createSession:ログイン

deleteSession:ログアウト

個々の API 操作には、関連する応答(応答自身である deliverEvent を除く)があります。操作ごとに、4 つのタイプの応答があります。

応答:要求が正常に処理されたことを示す応答です。

データ:情報への要求に対する応答です。

通知(deliverEvent):データベース オブジェクトの追加、削除または変更を示す応答です。

エラー:エラーが発生していることを示す応答です。

ISC リポジトリ オブジェクトに対して実行できる操作を図 1-3 に示します。

図 1-3 SOAP エンベロープ本文操作

 

特定の操作の API の詳細については、本書の該当する章を参照してください。

XML スキーマ

ISC は XML スキーマとメタデータを使用して、クライアントから渡された XML 要求が正しいかどうか検証します。この検証により、className が有効であるかどうかと、XML 要求にリストされているアトリビュートが認識されているかどうかが確認されます。

API XML スキーマは World Wide Web Consortium(W3C)組織で定義され、データ構造を表現するための構造化された方法が規定されています。このスキーマは、データ タイプを定義するための構造と、データ構造に対するこれらのデータ タイプのマッピングを提供します。


) ISC API 用の XML コンポーネントの例は、次の URL から入手できます。
http://www.cisco.com/en/US/docs/net_mgmt/ip_solution_center/6.0/developer/reference/ xmlapi.zip


XML の例

ISC では、製品に XML 要求と応答の例が用意されています。固有のクライアント コードを開発するには、この XML の例を参考として使用してください。

ISC API 用の XML コンポーネントの例は、次の場所から入手できます。

http://www.cisco.com/en/US/docs/net_mgmt/ip_solution_center/6.0/developer/reference/ xmlapi.zip

表 1-3 に、さまざまなカテゴリの XML の例、および各例が本書で説明されている場所を示します。

 

サービス モデル

ISC サービス モデルは、サービス オーダー、サービス定義、およびサービス リクエストをプロビジョニング プロセスで使用します。

サービス オーダーによって、プロビジョニング プロセスをスケジュール設定し、プロビジョニング プロセスの履歴を取得できます。サービス オーダーは、複数のサービス リクエストをグループにまとめる方法を提供します。これによって、ISC は単一の PE をターゲットとする可能性のある複数のコンフィギュレーション コマンドを一度にダウンロードできます。これで、ネットワーク デバイスへの再設定の回数が削減されます。

サービス リクエストはサービス オーダーで実装されます。ネットワークでプロビジョニングされ、アクティブ化されるのはサービス リクエストです。サービス リクエストでは、物理リンクのアトリビュートを定義し、使用するサービス ポリシーを指定します。サービス ポリシーは、サービス定義内で定義します。

サービス定義は、サービス ポリシーを定義します。サービス ポリシーを定義すると、ポリシー プロパティ用の追加のアトリビュート(editable=true)も設定できます。これにより、サービス リクエストの作成者は特定のポリシー アトリビュートを上書きできます。サービス オーダーとサービス リクエストは、サービス定義を使用して、プロビジョニング プロセス中に使用する共通データを定義します。

サービス オーダー/サービス リクエスト

ISC サービスは、エンドユーザ サービスまたはインフラストラクチャ サービスとして定義できます。エンドユーザ サービスは、サービス プロバイダーから利益を受けるエンド ユーザ(個人または組織)が利用できます。インフラストラクチャ サービスは、エンドユーザ サービスを提供する前に適切に配置されている必要があります。インフラストラクチャ サービス自体は、エンドユーザ サービスとして提供できません。ISC API は、サービス オーダーを使用して、両方のタイプのサービスをサポートします。

サービス オーダーにより、サービス プロバイダーが、ISC を使用して実装されるすべてのサービス リクエストの作成、修正、または削除を追跡できます。

サービス オーダーは次の目的のために作成されます。

バッチ操作用に 1 つ以上のサービス リクエストを指定する。

既存のサービス リクエストを変更する。

サービス リクエストの実装順序を指定する。

多数の個別操作を実装する。1 つのサービス オーダーで MPLS サービス リクエストが修正され、同時に他の操作も実行できます。

関連操作を実行する。1 つのサービス オーダーで、組織、サービス定義、および Cisco ルータが作成できます。

サービス オーダーのライフ サイクル

サービス オーダーの標準的なライフ サイクルは次のとおりです。

サービス オーダーが作成され、サービス リクエストが指定される。

ISC がサービス リクエストを受信する。

サービス リクエストが、実行期日に基づいて実装される。サービス オーダー、またはサービス オーダー内のサービス リクエストの実行期日が将来である場合は、スケジュール キューに配置されます。

サービス リクエストが正しい時刻に実行される。

サービス リクエストが正常に展開されたかどうかを示す、応答メッセージが生成されます。

サービス リクエストの修正

すでに展開済みのサービス リクエストに変更を加えるには、既存のサービス リクエストを修正するサービス オーダーを新たに作成する必要があります。新規サービス オーダーはアクティブなサービス オーダーになります。前のサービス オーダーは、アクティブなサービスの履歴レコードになります。同様に、サービス リクエストを削除するには、既存のサービス リクエストを解放するためにサービス オーダーを新たに作成する必要があります。


) テンプレートのあるサービス リクエストを修正する場合、またはテンプレートのあるサービス リクエストを解放する前に、サービス リクエストからテンプレート情報を削除しておく必要があります。詳細については、「テンプレート コンフィギュレーションの削除」を参照してください。


サービス オーダーの例

サービス オーダーの XML 要求には一般情報が含まれたヘッダーがあり、その後に 1 つ以上のサービス リクエストとサービス定義が続きます。ヘッダー情報の一部は、複数のサービス リクエストにまたがって使用できます。サービス リクエストにはサービス固有の情報が含まれていますが、サービス オーダーのヘッダーで定義されているグローバル パラメータを上書きするために使用することもできます。

ヘッダー情報付きのサービス オーダーの XML 要求と、そこに含まれるサービス リクエストの例を次に示します。

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:ns0="http://www.cisco.com/cim-cx/2.0"
xmlns:ns1="urn:CIM">
<soapenv:Header>
<!-- WaitTimeout has a default set in system properties.-->
<ns0:message id="87855" timestamp="2002-12-13T14:55:38.885Z"
Wait="false" WaitTimeout="60" sessiontoken="p36bttjwy1"/>
</soapenv:Header>
<soapenv:Body>
<ns1:performBatchOperation>
<actions xsi:type="ns1:CIMActionList"
soapenc:arrayType="ns1:CIMAction[]">
<action>
<actionName xsi:type="xsd:string">createInstance</actionName>
<objectPath xsi:type="ns1:CIMObjectPath">
<className xsi:type="xsd:string">ServiceOrder</className>
<properties xsi:type="ns1:CIMPropertyList"
soapenc:arrayType="ns1:CIMProperty[]">
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">ServiceName</name>
<value xsi:type="xsd:string">ServiceOrder-ConfigAudit</value>
</item>
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">CarrierId</name>
<value xsi:type="xsd:string">5</value>
</item>
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">DesiredDueDate</name>
<value xsi:type="xsd:dateTime">2002-12-14T14:55:38.885Z</value>
</item>
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">NumberOfRequests</name>
<value xsi:type="xsd:string">1</value>
</item>
</properties>
</objectPath>
</action>
<action>
<actionName xsi:type="xsd:string">createInstance</actionName>
<objectPath xsi:type="ns1:CIMObjectPath">
<className xsi:type="xsd:string">ServiceRequest</className>
<properties xsi:type="ns1:CIMPropertyList"
soapenc:arrayType="ns1:CIMProperty[]">
<item xsi:type="ns1:CIMProperty">
<name xsi:type="xsd:string">RequestName</name>
<value xsi:type="xsd:string">CONFIG-AUDIT-TASK</value>
</item>

名前とロケータ ID

サービス オーダーまたはサービス リクエストを作成する場合は、サービス名を指定する必要があります。これらの名前は、クエリーを分かりやすくするために使用します。

サービス名の例には次のようなものがあります。

サービス オーダー:AcmeServiceOrder1、L2PN-ATM-SO

サービス リクエスト:MPLSServiceRequest、L2VPN-FrameRelaySR

サービス オーダーの XML 要求を実行すると、ISC は XML 応答で LocatorId を戻します。このロケータ ID は、サービス オーダーまたはサービス リクエストの Name に関連付けられます。ロケータ ID はすべてのサービス リクエスト タイプで固有です。サービス リクエストのタイプの例は MPLS または TemplateData です。


ヒント すべてのサービス オーダーおよびサービス リクエストに、ロケータ ID またはサービス名のレコードを作成します。ロケータ ID は、サービス オーダーの表示、サービス オーダー タスク(設定監査または機能監査)の実行、およびサービス オーダーまたはサービス リクエストに関連するすべての後続の要求に必要です。


サービス オーダーおよびサービス リクエストの応答には、失敗したサービス リクエストのログ情報の取得に使用できる TaskLocatorId も含まれます。詳細については、「タスク ログの表示」を参照してください。

サービス定義

サービス定義では、サービス ポリシーとその特性を定義します。サービス定義はサービス リクエストで指定できますが、必須指定ではありません。サービス定義を使用して、複数のサービスによって使用できるコンフィギュレーション パラメータを作成します。

ISC は、各サービス タイプ(MPLS、L2VPN)およびテンプレートに対するサービス定義をサポートしています。

詳細については、サービス プロビジョニングに関する各章を参照してください。テンプレート サービス定義の詳細については、「テンプレート サービス定義」を参照してください。

API エラー メッセージ

API は要求/応答システムです。入力メッセージはエラーがないか処理され、エラーは XML 応答の一部として API クライアントにレポートされます。エラーは標準符号化方式にフォーマットされます。符号化方式は、次のスキーマによって示される 3 つのアトリビュートの集合です。

<xs:element name="error">
<xs:complexType>
<xs:sequence>
<xs:element ref="code"/>
<xs:element ref="description"/>
<xs:element ref="detail"/>
</xs:sequence>
</xs:complexType>
</xs:element>
 

error は、メソッドまたは操作が正常に実行できない基本的なエラーを定義します。

code アトリビュートには、エラーの性質を示す数値のステータス コードが入ります。

description アトリビュートには、人間が読めるエラーの説明が入ります。

detail アトリビュートが指定されると、説明が追加されます。


) 有効なステータス コードおよび説明は、『Cisco IP Solution Center System Error Messages, 6.0』で定義されます。


エラーは複数の ISC コンポーネントで発生する場合があります。たとえば、code と description は API エラーを示し、detail には別のコンポーネントのエラーに関する情報が入ることがあります。

ISC は、エラーが検出されたコンテキスト(作成、削除、修正)と、エラーの原因となったクラスに応じたエラー メッセージを処理します。このため、API は XML 応答で操作とクラス名の両方を戻します。

次のメッセージ内で注意が必要なテキストは太字で示されています。

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmls
oap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSche
ma-instance" xmlns:ns0="http://www.cisco.com/cim-cx/2.0" xmlns:ns1="urn:CIM">
<soapenv:Header>
<ns0:message id="87855" sessiontoken="040833748184101892B5C1130544B053" timestamp="2003-10-29T17:30:23.199
Z" />
</soapenv:Header>
<soapenv:Body>
<ns1:createInstanceResponse>
<returns xsi:type="ns1:CIMReturnList" soapenc:arrayType="ns1:CIMReturn[]">
<objectPath xsi:type="ns1:CIMObjectPath">
<className xsi:type="xsd:string">VPNServicesModule</className>
<errors xsi:type="ns1:CIMErrorList" soapenc:arrayType="ns1:CIMError[]">
<error xsi:type="ns1:CIMError">
<code xsi:type="xsd:int">1104</code>
<description xsi:type="xsd:string">Unable to find object (Device) with value (CatIOS). Referenced object does not exist.</description>
<detail xsi:type="xsd:string">For input string: "CatIOS"</detail>
</error>
</errors>
</objectPath>
</returns>
</ns1:createInstanceResponse>
</soapenv:Body>
</soapenv:Envelope>
 

この例の内容は次のとおりです。

createInstanceResponse は、エラーが create 操作に関連付けられていることを示します。

create 操作が実行されているクラスは VPNServicesModule です。

エラー コード 1104 を使用すると、『 Cisco IP Solution Center System Error Messages, 6.0 』でメッセージを検索できます。メッセージはコードと説明が連結したものです。したがって、1104- Unable to find object (Device) with value (CatIOS). Referenced object does not exist. となります。


) ブロック コール <errors> は、1 つの応答に複数の <error> がある場合に使用されます。


次のサンプル API エラー メッセージは、ServiceRequest の createInstanceResponse を示しています。

<actionName xsi:type="xsd:string">createInstanceResponse</actionName>
<objectPath xsi:type="ns1:CIMObjectPath">
<className xsi:type="xsd:string">ServiceRequest</className>
<errors xsi:type="ns1:CIMErrorList" soapenc:arrayType="ns1:CIMError[]">
<error xsi:type="ns1:CIMError">
<detail xsi:type="xsd:string">ORA-00060: deadlock detected while waiting for resource
</detail>
<description xsi:type="xsd:string">22 : SQL Exception while updating com.cisco.vpnsc.repository.mpls.RepMplsSR</description>
<code xsi:type="xsd:int">22</code>
</error>
 

この例の内容は次のとおりです。

error はエラー コード 22 で示されるリポジトリ エラーです。

description には MPLS SR 内のエラーが示されています。

detail には ORACLE のデッドロックと示されています。

エラー ログ

API は、デバッグ目的で使用できるエラー ログも提供します。次の例は、インストレーションの tmp ディレクトリ内の NBI ログを示しています。

 
FINE: getErrorMsgByName(2029)
Oct 29, 2003 12:15:57 PM com.cisco.vpnsc.repository.common.RepVpnscLogger severe
SEVERE: [NbiException.processException:
com.sybase.jdbc2.jdbc.SybSQLException: ASA Error -196: Index 'MGMT_ADDR_CR' for table 'CISCO_ROUTER' would not be unique
at com.sybase.jdbc2.tds.Tds.processEed(Tds.java:2538)
at com.sybase.jdbc2.tds.Tds.nextResult(Tds.java:1922)
at com.sybase.jdbc2.jdbc.ResultGetter.nextResult(ResultGetter.java:69)
at com.sybase.jdbc2.jdbc.SybStatement.nextResult(SybStatement.java:201)
at com.sybase.jdbc2.jdbc.SybStatement.nextResult(SybStatement.java:182)
............

この例の内容は次のとおりです。

引数が 2029 の getErrorMsgByName のコールでは、2029 がエラー コードです。

ASA Error(SYBASE から)が detail フィールドに示されています。

スタック トレース情報は Cisco Technical Assistance Center(TAC)のサポートに使用されます。