Cisco Unified Provisioning Manager Northbound Interface プログラマー ガイド
サンプル クライアント
サンプル クライアント
発行日;2012/02/26 | 英語版ドキュメント(2010/10/13 版) | ドキュメントご利用ガイド | ダウンロード ; この章pdf , ドキュメント全体pdf (PDF - 768KB) | フィードバック

目次

サンプル クライアント

概要

SDK 開発環境の設定

SDK ディレクトリの概要

サンプル Java クライアントの設定

SDK サンプル クライアントの実行

環境変数

XML サンプル ファイル

SDK のインストールと実行

SDK コマンド

NBI の事前設定要件

Perl NBI クライアントの設定

要件

共通のプロパティ

XML テンプレートの使用方法

サポートされる要求

使用方法(セッション例)

セッション例

サンプル クライアント

ここでは、サンプル クライアントをビルドするためのソース コード、jar ファイル、および XML ファイルの使用方法を説明します。詳細については、次の項を参照してください。

「概要」

「Provisioning Manager NBI SDK 開発環境の設定」

「サンプル Java クライアントの設定」

「Perl NBI クライアントの設定」

概要

Ant を使用して、2 つの Provisioning Manager NBI クライアントをコンパイルして生成します。クライアントは環境変数を使用して、要求の送信先となるサーバ URL を指定します。

単純なユーザ通知サービスが提供されます。Ant を使用して、Tomcat にインストールされた AXIS2.war ファイルでインストールできるアーカイブをコンパイルして生成します。

また、クライアント、ユーザ通知、およびツールを、Windows XP プラットフォームにインストールできる zip ファイルにパッケージ化することもできます。

Provisioning Manager NBI SDK 開発環境の設定

Provisioning Manager のインストールの CUPM¥sep¥ipt¥nbi-sdk に、サンプルのクライアント環境のディレクトリがあります。

ディレクトリ内で操作することも、別の Windows XP プラットフォームにコピーすることもできます。このプラットフォームには Java 1.5 と Ant 1.6.5 がインストールされている必要があります。ユーザ通知を実行する場合は、Tomcat と AXIS2 もインストールする必要があります。

Provisioning Manager NBI SDK ディレクトリの概要

ここでは、Provisioning Manager NBI SDK に含まれるディレクトリについて説明します。SDK をダウンロードして解凍すると、...¥nbi-sdk ディレクトリの下に次のディレクトリが表示されます。

doc:ユーザー向けのマニュアル。

html-doc:NBI XSD ファイルごとに、このディレクトリには XSD ファイルの注釈フィールドから生成された html ドキュメントが保存されます。さらに、すべての NBI 複合オブジェクトのグラフィックによる説明も保存されます。

このドキュメントでは Provisioning Manager NBI で使用されるすべての複合オブジェクトについて説明しています。トップ レベルのオブジェクトについては、キーとなるアトリビュート、オブジェクトの作成要求で設定する必要のあるアトリビュートについて説明します。

また、オブジェクトのグラフィック表現も保存されます。

productcatalog:完全な Provisioning Manager 製品カタログの XML ファイル バージョンが保存されます。製品カタログ ディレクトリには、次の 2 つのサブディレクトリがあります。Provisioning Manager によってサポートされるすべての製品を定義する XSD ファイルが保存される schema サブディレクトリと、Provisioning Manager を使用して注文できるすべての製品の XML 定義が保存される metadata サブディレクトリです。

sample:サンプル クライアントをビルドするための Java ファイル、bat ファイル、XML ファイル。また、設定オブジェクトのサンプル作成要求も含まれています。

wsdl-xsd:Provisioning Manager NBI を定義するすべての WSDL ファイルおよび XSD ファイルが保存されます。

サンプル Java クライアントの設定

環境をセットアップした後、Provisioning Manager システムまたは別のシステムで、CUPM¥sep¥ipt¥nbi-sdk¥sample ディレクトリに移動します。

このディレクトリ内の build.xml ファイルによって、サブディレクトリ output および image が作成されます。 output ディレクトリには、生成されたすべての class、jar、zip、およびその他のターゲットが保存されます。 image ディレクトリは、環境変数 CUPM_NBI_SDK_COMMAND_HOME で参照される場合に、ここから実行できるインストール可能なイメージです。また、 image ディレクトリは、他のプラットフォームでのインストールのために zip ファイルに圧縮されます。

build-install-all target を使用して、クライアントの準備やユーザ通知サービスを準備して展開するために必要なすべての Ant ターゲットを実行します。

build.xml ファイルは、次のターゲットを提供します。

build-install-all:クライアントをコンパイルおよびビルドし、ユーザ通知をコンパイル、ビルド、およびインストールします。

build-clients:クライアントのビルドのみを行います。

compile-clients:Java のコンパイル。

lib-clients:クライアントの jar ファイルを作成します。

image-clients:インストール可能な image ディレクトリにクライアントを追加します。

build-consumer:ユーザ通知サービスのビルドのみを行います。

compile-consumer-schema

compile-consumer-src

lib-consumer

image-consumer

イメージのビルド後、または別のプラットフォームでのインストール後、CUPM¥sep¥ipt¥nbi-sdk¥sample ディレクトリから次の Ant コマンドを実行します。

setup-axis2-tomcat :新しい AXIS2 のインストールから AXIS2.war ファイルを生成し、AXIS2.war ファイルを Tomcat のインストールにコピーして拡張します。

deploy-consumer :AXIS2 がインストールされて拡張された Tomcat のバージョンにユーザ通知をインストールします。

SDK サンプル クライアントの実行

image ディレクトリの準備が完了したら、環境変数 CUPM_NBI_SDK_COMMAND_HOME を CupmNbiSdkCommand ディレクトリへのフル パスを参照するように設定します。パス ディレクトリに CUPM_NBI_SDK_COMMAND_HOME を含めます。

次の SDK コマンドにアクセスできるようになります。

SdkQueryEnvVar :SDK クライアントによって使用されるすべての環境変数を現在の設定とともに表示します。

ValidateRequest <XML-File> :NBI 要求が含まれる XML ファイルを検証します。SAX パーサーは適切な XSD ファイルに対して検証を実行します。

PingRequest <Optional Arguments> :指定した Provisioning Manager サーバに ping 要求を送信し、ユーザ通知サービスへの EPR を設定します。


) サーバ URL とユーザ通知 URL は環境変数から指定するか、またはコマンド ラインで引数によって指定することができます。引数 -h はコマンドの引数の説明を提供します。


SendXmlRequest <XML-File> :このクライアントは XML ファイルを読み取ります。オプションで、ファイル内の EPR を、環境変数によって指定された EPR に置き換えます。オプションで、idPrefix の設定を置き換えます。その後、要求を送信し、応答を出力します。

要求で通知を送信する場合、ユーザ通知サービスによって Tomcat コマンド ウィンドウに出力されます。

環境変数

サンプル NBI クライアントでは、コマンド ライン上、または環境変数を使用してサーバ情報および通知を設定できます。環境変数を使用すると、1 台のサーバへ要求のセットを発行し、1 つの URL で通知を受信できます。コマンド ラインで毎回設定する代わりに、環境変数を設定する方が簡単です。

表 A-1 に、サポートされる環境変数を示します。

 

表 A-1 環境変数

環境変数
デフォルト
目的/注意

server.ipaddress

localhost

要求の送信先の Provisioning Manager サーバの IP アドレス。

server.port

80

Provisioning Manager のグラフィカル ユーザ インターフェイスおよび Web サービス アクセスのために設定されるポート。

(注) 転送エラーが表示される場合は、お使いのサーバがポート 80 を使用してない可能性があります。ポート 80 が使用中のプラットフォームにサーバをインストールする場合、別のポート(たとえば、ポート 1024)を選択します。

server.namespace

axis2/services/CUPMServices

Provisioning Manager で設定されたサービス。これは変更できません。

server.url

--

設定されている場合、完全 URL 名に使用されます。設定されていない場合、server.ipaddress、port、および namespace を組み合わせてサーバの URL を作成します。

notification.ipaddress

localhost

NBI 結果の送信先となるユーザ通知の IP アドレス。

notification.port

8080

ユーザ通知 URL のポート。

notification.namespace

axis2/services/NotificationConsumerSe

サーバの名前空間。これはサンプルで指定された名前です。自分の名前を入力する場合は、ここに名前を入力します。

notification.url

--

設定されている場合、完全 URL 名に使用されます。設定されていない場合、notification.ipaddress、port、および namespace を組み合わせてサーバの URL を作成します。

cupm.user

--

Provisioning Manager NBI へのアクセス用クレデンシャルとして使用される管理権限のある Provisioning Manager アカウント。

(注) SdkSetup.bat ファイルではこの名前が pmadmin であることを前提とします。このアカウントをインストール時に別の名前に設定する場合、手動で正しい ID に設定する必要があります。

cupm.password

--

Provisioning Manager NBI へのアクセス用クレデンシャルとして使用される管理権限のある Provisioning Manager アカウントのパスワード。

(注) SdkSetup ではこのパスワードを引数として想定するため、自動的に設定できます。

server.protocol

http

要求/応答トランザクションが http または https のどちらであるかを判断します。この環境変数を https に設定すると、https トランザクションが実装されますが、https.certificate 環境変数が設定されていない場合は、証明書が確認されません。

』を参照してください。

https.certificate

false

ブール設定、true または false。ヌル設定は false と見なされます。

true に設定した場合、サーバからの証明書は各要求トランザクションの一部として検証されます。

サーバからの証明書のインストールは、この機能を使用するための前提条件です。

Sun Microsystems のコマンド InstallCert.java をダウンロードして実行することを推奨します。

request.idprefix

--

NBI ID の先頭に追加するすべての同期要求のためのオプションの NBI パラメータがあります。これは XML 要求ファイルで指定されます。この環境変数を設定する場合、XML ファイルの値が上書きされます。

XML サンプル ファイル

ネットワーク オブジェクトの作成、更新、取得、削除、および一覧表示の XML 要求の例が含まれます。電話機および回線を設定するための単純なオーダーが含まれます。


) これらの要求では、ユーザの設定と一致するように編集することを要求します。


ユーザの環境に合わせて更新できるように、サンプル XML ファイルにコメントが入力されています。たとえば、デバイスの作成の場合、少なくとも、デバイスに合わせて IP アドレスとクレデンシャルを設定する必要があります。

Provisioning Manager NBI SDK のインストールと実行

ここでは、Provisioning Manager NBI クライアントをビルドしてテストするための最小手順について説明します。

1. お使いのシステムに Java JRE または JDK 1.5 をインストールします。

a. zip ファイルから Java をインストールするか、または別の方法を使用してインストールします。

b. Java 1.5 ディレクトリを参照するように JAVA_HOME パラメータを設定します。

c. パスに %JAVA_HOME%¥bin を追加します。


) SDK と同じプラットフォームに Provisioning Manager をインストールする場合、この手順をスキップして、Provisioning Manager に付属の Java バージョンを使用することができます。


2. お使いのシステムに Ant 1.6.5 をインストールします。

a. zip ファイルをダウンロードします。

b. ファイルを解凍します。

c. 解凍されたディレクトリに ANT_HOME 環境変数を設定します。

d. パスに %ANT_HOME%¥bin を追加します。

3. Axis2 1.3 をインストールします。

a. zip ファイルをダウンロードします。

b. ファイルを解凍します。

c. 解凍されたディレクトリに AXIS2_HOME 環境変数を設定します。

d. パスに %AXIS2_HOME%¥bin を追加します。

4. Tomcat 5.5 をインストールします。

a. zip ファイルをダウンロードします。

b. ファイルを解凍します。

c. 解凍されたディレクトリに CATALINA_HOME 環境変数を設定します。

d. パスに %CATALINA_HOME%¥bin を追加します。

5. Provisioning Manager をインストールします。SDK システムまたは別のシステムに Provisioning Manager 2.0 をインストールできます。2.0. Provisioning Manager NBI の単純なテスト、開発、および理解のためには、同じシステムを使用することを推奨します。大規模な開発の場合は、別のシステムに Provisioning Manager をインストールすることを推奨します。

Provisioning Manager 2.0 のセットアップ ファイルを実行します(installShield ウィザードが起動します)。これによって、Java 1.5 がインストールされ、JAVA_HOME 環境変数が設定されます。


) インストール後に Provisioning Manager サーバが起動します。


6. Provisioning Manager NBI SDK をインストールします。

a. 任意のディレクトリで cupm-nbi-sdk.zip ファイルを解凍します。

b. サンプル サブディレクトリに移動します(...¥nbi-sdk¥sample)。

c. ant build-install-all を実行します。これによって、次の内容が実行されます。

2 つのサンプル クライアントをコンパイルしてビルドします。

XML 要求バリデータ ユーティリティをコンパイルしてビルドします。

ユーザ通知サービス AAR ファイルをコンパイルしてビルドします。

axis2.war ファイルを作成します。

Tomcat で axis2.war をインストールして拡張します。

Tomcat で axis2 にユーザ通知サービスを展開します。

d. %CATALINA_HOME%¥bin¥startup を実行します。Tomcat が起動します。

e. SdkSetup.bat <pmadmin-password> を実行します。最初の引数として pmadmin ユーザ ID のパスワードを使用してこの bat ファイルを実行します。この bat ファイルによって、次の内容が実行されます。

前の手順でビルドした SDK コマンド イメージに環境変数 CUPM_NBI_SDK_COMMAND_HOME を設定します(...¥nbi-sdk¥sample¥image¥CupmNbiSdkCommands)。

パスに CUPM_NBI_SDK_COMMAND_HOME を追加します。

次の SDK 環境変数を設定します。

server.ipaddress=localhost

notification.ipaddress=localhost

cupm.user=pmadmin

cupm.password=<bat-parameter>

PingRequest クライアントを実行します。これを実行すると、ping 応答からのデータが表示されます。Provisioning Manager バージョンと Provisioning Manager NBI バージョンが表示されます。また、通知サーバのステータス文字列が Tomcat ウィンドウに表示されます。


) SDK と Provisioning Manager を同じシステムにインストールし、Provisioning Manager のアカウント名およびポートのデフォルト値を使用するように SdkSetup.bat は作られています。

次のいずれかが Provisioning Manager のインストールに該当する場合、カスタマイズした設定にあわせて環境変数を設定する必要があります。

Provisioning Manager が SDK 以外のシステムにインストールされている。

Provisioning Manager アカウントが pmadmin ではない。

ポート 80 がサーバで使用されていない。

ポート 8080 がユーザ通知に使用されていない。

独自のユーザ通知サービスを使用している。

基本以外の設定の場合、SdkSetup.bat を実行し、これに失敗します。 SET コマンドを使用して、ユーザの設定に合わせて環境変数を設定します。


 

f. SendXmlRequest xml¥CreateDevice.xml を実行します。XML サブディレクトリ内の XML ファイル CreateDevice.xml をサーバに送信します。これによって、IPT 機能を備えた架空のデバイスが作成されます。これを実行すると、数秒後に応答 XML ファイルが表示され、通知結果 XML ファイルが Tomcat ウィンドウに表示されます。

実デバイスを作成するには、まず CreateDevice.XML ファイルを編集する必要があります。実デバイスに合わせて IP アドレスおよびクレデンシャルを変更します。

g. SendXmlRequest xml¥CreateDomain.xml を実行します。XML サブディレクトリの XML ファイル CreateDomain.xml をサーバに送信します。これによって、ドメインが作成されます。これを実行すると、応答 XML ファイルが表示されます。約 1 分後、通知結果 XML ファイルが Tomcat ウィンドウに表示されます。

h. SendXmlRequest xml¥CreateServiceArea.xml を実行します。XML サブディレクトリ内の XML ファイル CreateServiceArea.xml をサーバに送信します。これによって、ドメイン内にサービス エリアが作成されます。これを実行すると、応答 XML ファイルが表示されます。数秒後、通知結果 XML ファイルが Tomcat ウィンドウに表示されます。

i. SendXmlRequest xml¥CreateSubscriber.xml を実行します。XML サブディレクトリ内の XML ファイル CreateSubscriber.xml をサーバに送信します。これによって、ドメイン内に加入者が作成されます。これを実行すると、応答 XML ファイルが表示されます。数秒後、通知結果 XML ファイルが Tomcat ウィンドウに表示されます。

j. SendXmlRequest xml¥CreateSubscriber2.xml を実行します。XML サブディレクトリ内の XML ファイル CreateSubscriber2.xml をサーバに送信します。これによって、ドメイン内に別の加入者が作成されます。これを実行すると、応答 XML ファイルが表示されます。数秒後、通知結果 XML ファイルが Tomcat ウィンドウに表示されます。

SDK コマンド

SDK をインストールして SdkSetup を実行すると、そのコマンド ウィンドウから SDK コマンドにアクセスできるようになります。これらのコマンドは任意のディレクトリから実行することができます。

SDK コマンドを次に示します。

SendXmlRequest :ディスクから XML ファイルを読み込みます。最初の引数は XML ファイルのファイル名で、このファイルがカレント ディレクトリにない場合は、フル パスのファイル名にします。このコマンドでは、環境変数設定を使用して、XML ファイルを送信する前に修正します。また、コマンド ラインから設定したり、現在の設定を変更したりすることもできます。最初の引数として -h と入力すると、このコマンドの使用方法が表示されます。

ValidateRequest :ディスクから XML ファイルを読み込みます。置換を行わずに、適切な XSD ファイルに対して XML ファイルが SAX パーサーで検証され、有効な XML ファイルであることが確認されます。ファイルが検証にパスした場合は、[File is valid] と表示されます。検証に失敗した場合、SAX パーサーの例外処理が実行され、最初の問題が発生したことが説明されます。最初の引数として -h と入力すると、このコマンドの使用方法が表示されます。

PingRequest :ping 要求のみを送信します。ディスクから何も読み取られません。インスタンスが作成され、Java で表示されます。クライアントからサーバへの接続およびクレデンシャルをテストし、サーバからユーザ通知への接続をテストするために ping 要求が使用されます。最初の引数として -h と入力すると、このコマンドの使用方法が表示されます。

SdkQueryEnvVar :他のコマンドやその現在の設定で使用されるすべての環境変数が表示されます。

SdkVersion :SDK コマンドがビルドされた日付と時刻が表示されます。

NBI の事前設定要件

ListProductAttributeChoice 要求は NBI の事前設定要件とも呼ばれます。これは製品のアトリビュートの選択リストを返すように設計されています。選択リストは、その他の設定に応じて、完全な選択リストの場合もあれば、コンテキストベースの選択リストの場合もあります。NBI から返された選択リストでは、その要求でその他の情報を提供する必要があります。

表 A-2 で、製品のアトリビュートの選択リストを返すためのその他の要件、制限事項、および制約事項について説明します。

 

表 A-2 アトリビュート要件の選択リスト

製品
アトリビュート
NBI 固有

Phone

Line

LineOnSharedPhone

EnableCUPCLicense

Type

すべてのタイプが返されます。ロールやサービス エリアに基づくフィルタリングは行われません。この情報は Provisioning Manager のユーザ インターフェイスで表示される情報とは異なります。

Phone

emenable

usedummymacaddress

タイプを指定する必要があります。

Phone

pbt

タイプとプロトコルを指定する必要があります。

Line

lineposition

Line のために SelectedPhone アトリビュートを渡す必要があります。Line On Shared Phone の場合、Target Phone を渡す必要があります。

Line

SelectedPhone

サポートされていません。

Line

EM Line

Line On Shared Phone

directorynumber

サポートされていません。

Line On Shared Phone

targetphone

サポートされていません。

EM Access

pbt

追加情報として、プロトコルが必要です。

EM_Line

SelectedEM_Access

サポートされていません。

Voicemail

SelectedLine

サポートされていません。

Email

SelectedVoicemail

サポートされていません。

UnifiedMessaging

SelectedEmail

サポートされていません。

Perl NBI クライアントの設定

サンプル Perl クライアントがサブディレクトリ perl/pm に保存されています。

要件

Perl 5.10.0 が必須です。NBI クライアントは ActivePerl で開発されてテストされました。ActivePerl は ActivePerl インタープリタの無料ダウンロードを提供しています。ActivePerl-5.10.0.1005-MSWin32-x86-290470.msi ファイルが使用されました。zip バージョンをダウンロードするだけではなく、インストール ファイルを実行する必要があります。

共通のプロパティ

Perl クライアントでは、Provisioning Manager Server EPR とクレデンシャルに対しても通知 EPR に対しても Java クライアントと同じ環境変数を使用します。すべての要求のセッション全体で環境変数を使用することも、コマンド ラインから要求ごとに指定または上書きすることもできます。

XML テンプレートの使用方法

Perl クライアントでは、要求の送信に XML テンプレートを使用します。各テンプレートには、コマンドの完全な SOAP エンベロープが含まれています。キーワードがユーザ指定の値に置換されると、有効な XML 要求がサーバに送信されます。

表 A-3 に、NBI Perl クライアントでサポートされるキーワードを示します。

 

表 A-3 NBI Perl Client でサポートされるキーワード

プロパティ名またはデータのソース
Perl キーワード
注意

server.url

SERVER_URL

server.url を設定する場合、指定したように置換されます。server.url が指定されない場合、URL が他のサーバ プロパティから構成されます。

server.protocol

SERVER_PROTOCOL

http のみがサポートされます。https をサポートするように拡張できます。

server.ipaddress

SERVER_URL

--

server.port

SERVER_PORT

--

server.namespace

SERVER_NAMESAPCE

Axis2/services/CUPMService のみが有効な設定です。

notification.url

NOTIFICATION_URL

server.url と同じロジックです。

notification.ipaddress

NOTIFICATION_IPADDRESS

--

notification.port

NOTIFICATION_PORT

--

notification.namespace

NOTIFICATION_NAMESPACE

--

cupm.user

CUPM_USER

または

USERNAME

--

cupm.password

CUPM_PASSWORD

または

PASSWORD

--

cupm.password はデータの最初のソースです。

ENCODED_PASSWORD

base 64 暗号化でエンコードした後の cupm.password。

form command line

REQUEST_NAME

NBI 要求の名前。

object.name

OBJECT_NAME

要求を区別するために設計されました。プル要求の場合、オブジェクト名はインスタンスを取得するためのリストの NBI ID を定義します。

pull.count
(指定されていない場合、デフォルトの 1)

PULL_COUNT

--

 

サポートされる要求

サンプル Perl クライアントは次の要求をサポートします。

ping

pull

listDomain

listSubscriber

このアーキテクチャでは、Perl モジュール(.pm)ファイルをサブディレクトリ モジュールに追加し、対応する XML テンプレート ファイルをサブディレクトリ XML/CUPMRequest に追加することによって追加コマンドの拡張が可能です。

使用方法(セッション例)

Perl クライアントはコマンド ラインから実行されます。サブディレクトリがシステム パス環境変数に追加されない場合は、perl/pm サブディレクトリから実行する必要があります。

コマンドは pm.pl です。引数なしでコマンドを入力します。-h を指定して入力するとオンライン ヘルプが表示されます。

コマンドには引数(要求名)を 1 つ指定できます。-D プレフィクスで追加プロパティを割り当てることができます。

セッション例

次のコマンドはサーバに対して ping を実行し、ドメイン リストを取得します。

1. 環境変数を設定するには、次の手順を実行します。

set server.ipaddress=1.2.3.4

set cupm.user=pmadmin

set cupm.password=yourpassword

set notification.ipaddress=5.6.7.8

2. perl クライアント pm.pl ping を実行します。ping 要求を送信します。応答で Provisioning Manager バージョンと Provisioning Manager NBI バージョンが返され、表示されます。

3. pm.pl ping -Dserver.ipaddress=11.22.33.44 -Dcupm.password=diffpassword を実行します。別のサーバに ping 要求を送信し、環境変数設定を一時的に上書きします。

4. pm.pl listDomain を実行します。listDomain コマンドを送信します。応答で NBI ID が返され、表示されます。

5. pm.pl pull -Dobject.name=<NBI-ID-RETURNED-BY-ABOVE-LIST> を実行します。ドメインのリストの最初の要素を返します。

6. pm.pl pull -Dobject.name=<NBI-ID-RETURNED-BY-ABOVE-LIST> -Dpull.count=1000 を実行します。リストの残りのオブジェクトを最大 1000 個返します。

7. listDomain 要求と listSubscriber 要求は、リストの生成直後にすべての項目を自動的にプルする機能を提供します。これは pull.count 環境変数を正の値に設定することによってトリガーされます。

たとえば、 pm.pl listSubscriber -Dpull.count=5 を実行します。

これによって、システムのすべての加入者のリスト要求が送信されます。ユーザ通知によって通知がディスクに書き込まれるのを待機します。次に、シーケンス アトリビュートの末尾が受信されるまで、5 つずつリストをさかのぼってプルします。


) この機能を実行するには、メソッド saveMessageResult へのコールをアンコメントした後、NotificationConsumerService をコンパイルする必要があります。