Java SDK
SDX NITRO API は、API の範囲と目的に応じてシステム API と構成 API に分類されます。NITRO 操作のトラブルシューティングも可能です。
システム API
NITRO を使用する最初のステップは、SDX アプライアンスとのセッションを確立し、管理者の資格情報を使用してセッションを認証することです。
アプライアンスの IP アドレスとアプライアンスに接続するプロトコル (HTTP または HTTPS) を指定して、nitro_service クラスのオブジェクトを作成します。次に、このオブジェクトを使用し、管理者のユーザー名とパスワードを指定して、アプライアンスにログオンします。
注:そのアプライアンスにはユーザーアカウントが必要です。実行できる構成操作は、アカウントに割り当てられている管理者の役割によって制限されます。
次のサンプルコードは、HTTPS プロトコルを使用して IP アドレス 10.102.31.16 の SDX アプライアンスに接続します。
//Specify the IP address of the appliance and service type
nitro_service nitroservice = new nitro_service ("10.102.31.16", "https");
//Specify the login credentials
nitroservice.login("nsroot", "verysecret");
注: nitro_service オブジェクトは、アプライアンスでのそれ以降の NITRO 操作すべてで使用します。
アプライアンスから切断するには、以下のようにlogout()メソッドを呼び出します。
nitroservice.logout();
設定 API
NITRO プロトコルは、SDX アプライアンスのリソースの設定に使用できます。
リソースを構成するための API は、com.citrix.sdx.nitro.resource.config という形式のパッケージまたは名前空間にグループ化されます。
たとえば、NetScalerリソースには com.citrix.sdx.nitro.resource.config.ns パッケージまたは名前空間があります。
リソースクラスは、その他多くの操作を実行するための API を提供します。これらの操作には、リソースの作成、リソースの詳細と統計の取得、リソースの更新、リソースの削除、リソースに対する一括操作の実行などがあります。
リソースを作成する
SDXアプライアンスにリソース（NetScalerインスタンスなど）を作成するには、次の手順を実行します。
- 対応するプロパティー名を使用して、リソースの必須プロパティーの値を設定します。その結果、リソースに必要な詳細を含むリソースオブジェクトが生成されます。 注:これらの値はクライアント上でローカルに設定されます。この値は、オブジェクトがアップロードされるまでアプライアンスに反映されません。
- static add () メソッドを使用して、リソースオブジェクトをアプライアンスにアップロードします。
次のサンプルコードは、SDXアプライアンスに「ns_instance」という名前のNetScalerインスタンスを作成します。
ns newns = new ns();
//Set the properties of the NetScaler locally
newns.set_name("ns_instance");
newns.set_ip_address("10.70.136.5");
newns.set_netmask("255.255.255.0");
newns.set_gateway("10.70.136.1");
newns.set_image_name("nsvpx-9.3.45_nc.xva");
newns.set_profile_name("ns_nsroot_profile");
newns.set_vm_memory_total(new Double(2048));
newns.set_throughput(new Double(1000));
newns.set_pps(new Double(1000000));
newns.set_license("Standard");
newns.set_username("admin");
newns.set_password("admin");
int number_of_interfaces = 2;
network_interface[] interface_array = new network_interface[number_of_interfaces];
//Adding 10/1
interface_array[0] = new network_interface();
interface_array[0].set_port_name("10/1");
//Adding 10/2
interface_array[1] = new network_interface();
interface_array[1].set_port_name("10/2");
newns.set_network_interfaces(interface_array);
//Upload the NetScaler instance
ns result = ns.add(nitroservice, newns);
リソース詳細の取得
SDX アプライアンス上のリソースのプロパティを取得するには、次の手順を実行します。
- get () メソッドを使用して、アプライアンスから設定を取得します。結果はリソースオブジェクトです。
- 対応するプロパティ名を使用して、必要なプロパティをオブジェクトから抽出します。
次のサンプルコードは、すべてのNetScalerリソースの詳細を取得します。
//Retrieve the resource object from the SDX appliance
ns[] returned_ns = ns.get(nitroservice);
//Extract the properties of the resource from the object
System.out.println(returned_ns[i].get_ip_address());
System.out.println(returned_ns[i].get_netmask());
リソース統計の取得
SDX アプライアンスは、その機能の使用状況に関する統計を収集します。これらの統計は NITRO を使用して取得できます。
次のサンプルコードは、IDが123456aのNetScalerインスタンスの統計を取得します。
ns obj = new ns();
obj.set_id("123456a");
ns stats = ns.get(nitroservice, obj);
System.out.println("CPU Usage:" + stats.get_ns_cpu_usage());
System.out.println("Memory Usage:" + stats.get_ns_memory_usage());
System.out.println("Request rate/sec:" +stats.get_http_req());
リソースを更新する
アプライアンス上の既存のリソースのプロパティを更新するには、次の手順を実行します。
- id プロパティーを、更新するリソースの ID に設定します。
- 対応するプロパティー名を使用して、リソースの必須プロパティーの値を設定します。結果はリソースオブジェクトです。 注:これらの値はクライアント上でローカルに設定されます。この値は、オブジェクトがアップロードされるまでアプライアンスに反映されません。
- update () メソッドを使用して、リソースオブジェクトをアプライアンスにアップロードします。
次のサンプルコードでは、IDが123456aのNetScalerインスタンスの名前を「ns_instance_new」に更新します。
ns update_obj = new ns();
//Set the ID of the NetScaler to be updated
update_obj.set_id("123456a");
//Get existing NetScaler details
update_obj = ns.get(nitroservice, update_obj);
//Update the name of the NetScaler to "ns_instance_new" locally
update_obj.set_name("ns_instance_new");
//Upload the updated NetScaler details
ns result = ns.update(nitroservice, update_obj);
リソースを削除する
既存のリソースを削除するには、削除するリソースの ID を引数として渡して、リソースクラスで静的メソッド delete () を呼び出します。
次のサンプルコードは、ID 1 のNetScalerインスタンスを削除します。
ns obj = new ns();
obj.set_id("123456a");
ns.delete(nitroservice, obj);
一括操作
複数のリソースを同時に照会または変更できるため、ネットワークトラフィックを最小限に抑えることができます。たとえば、同じ操作で複数のNetScaler SDXアプライアンスを追加できます。
各リソースクラスには、リソースの追加、更新、削除のためのリソースの配列を取るメソッドがあります。一括操作を実行するには、各操作の詳細をローカルで指定し、その詳細を一度にサーバーに送信します。
NITRO では、一括操作内の一部の操作が失敗したことを考慮して、次のいずれかの動作を構成できます。
- 出口。最初のエラーが発生すると、実行は停止します。エラー発生前に実行されたコマンドがコミットされます。
- 続ける。一部のコマンドが失敗した場合でも、リスト内のすべてのコマンドが実行されます。
注:
nitro_service () メソッドで
onerror param を設定して、アプライアンスとの接続を確立する際に必要な動作を設定します。
次のサンプルコードは、1 回の操作で 2 つの ADC アプライアンスを追加します。
ns[] newns = new ns[2];
//Specify details of first NetScaler
newns[0] = new ns();
newns[0].set_name("ns_instance1");
newns[0].set_ip_address("10.70.136.5");
newns[0].set_netmask("255.255.255.0");
newns[0].set_gateway("10.70.136.1");
...
...
...
//Specify details of second NetScaler
newns[1] = new ns();
newns[1].set_name("ns_instance2");
newns[1].set_ip_address("10.70.136.8");
newns[1].set_netmask("255.255.255.0");
newns[1].set_gateway("10.70.136.1");
...
...
//upload the details of the NetScalers to the NITRO server
ns[] result = ns.add(nitroservice, newns);
例外ハンドリング
errorcode フィールドはオペレーションのステータスを示します。
- エラーコード 0 は、操作が成功したことを示します。
- 0 以外のエラーコードは、NITRO 要求の処理中にエラーが発生したことを示します。
エラーメッセージフィールドには、簡単な説明と失敗の性質が表示されます。
com.citrix.sdx.nitro.exception.nitro_exception クラスは、NITRO API の実行中のすべての例外をキャッチします。例外に関する情報を取得するには、 getErrorCode() メソッドを使用します。
エラーコードの詳細については、 <NITRO_SDK_HOME>/docフォルダにある API リファレンスを参照してください。