.NET SDK

Last published : Oct 06, 2026
SDX NITRO API 根据其范围和用途分为系统 API 和配置 API。您还可以对 NITRO 操作进行故障排除。
Related information
NITRO API

系统 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.<resource_type>。这些包或命名空间中的每一个都包含一个名为 <resource_type> 的类，该类提供用于配置资源的 API。
例如，NetScaler 资源具有 com.citrix.sdx.nitro.resource.config.ns 包或命名空间。
资源类提供用于执行其他操作的 API。这些操作可以是创建资源、检索资源和资源属性、更新资源、删除资源以及对资源执行批量操作。

创建资源

要在 SDX 设备上创建资源（例如，NetScaler 实例）：
  1. 通过使用相应的属性名称设置资源的所需属性值。结果是一个资源对象，其中包含资源所需的详细信息。 注意：这些值在客户端本地设置。在对象上传之前，这些值不会反映在设备上。
  2. 使用静态 add() 方法将资源对象上传到设备。
以下示例代码在 SDX 设备上创建了一个名为“ns_instance”的 NetScaler 实例：
ns newns = new ns();

//Set the properties of the NetScaler locally
newns.name = "ns_instance";
newns.ip_address = "10.70.136.5";
newns.netmask = "255.255.255.0";
newns.gateway = "10.70.136.1";
newns.image_name = "nsvpx-9.3.45_nc.xva";
newns.profile_name = "ns_nsroot_profile";
newns.vm_memory_total = 2048;
newns.throughput = 1000;
newns.pps = 1000000;
newns.license = "Standard";
newns.username = "admin";
newns.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].port_name = "10/1";

//Adding 10/2
interface_array[1] = new network_interface();
interface_array[1].port_name = "10/2";

newns.network_interfaces = interface_array;

//Upload the NetScaler instance
ns result = ns.add(nitroservice, newns);

检索资源详细信息

要检索 SDX 设备上资源的属性，请执行以下操作：
  1. 使用 get() 方法从设备检索配置。结果是一个资源对象。
  2. 使用相应的属性名称从对象中提取所需的属性。
以下示例代码检索所有 NetScaler® 资源的详细信息：
//Retrieve the resource object from the SDX appliance
ns[] returned_ns = ns.get(nitroservice);

//Extract the properties of the resource from the object
Console.WriteLine(returned_ns[i].ip_address);
Console.WriteLine(returned_ns[i].netmask);

检索资源统计信息

SDX 设备会收集其功能使用情况的统计信息。您可以使用 NITRO 检索这些统计信息。
以下示例代码检索 ID 为 123456a 的 NetScaler 实例的统计信息：
ns obj = new ns();
obj.id = "123456a";
ns stats = ns.get(nitroservice, obj);
Console.WriteLine("CPU Usage:" + stats.ns_cpu_usage);
Console.WriteLine("Memory Usage:" + stats.ns_memory_usage);
Console.WriteLine("Request rate/sec:" +stats.http_req);

更新资源

要更新设备上现有资源的属性，请执行以下操作：
  1. 将 id 属性设置为要更新的资源的 ID。
  2. 使用相应的属性名称设置资源的必需属性值。结果是一个资源对象。 注意：这些值在客户端本地设置。在对象上传之前，这些值不会反映在设备上。
  3. 使用 update() 方法将资源对象上传到设备。
以下示例代码将 ID 为 123456a 的 NetScaler 实例的名称更新为“ns_instance_new”：
ns update_obj = new ns();

//Set the ID of the NetScaler to be updated
update_obj.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.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.id = "123456a";
ns.delete(nitroservice, obj);

批量操作

您可以同时查询或更改多个资源，从而最大限度地减少网络流量。例如，您可以在同一操作中添加多个 NetScaler SDX 设备。
每个资源类都有用于添加、更新和删除资源的接受资源数组的方法。要执行批量操作，请在本地指定每个操作的详细信息，然后一次性将详细信息发送到服务器。
为了处理批量操作中某些操作的失败，NITRO 允许您配置以下行为之一：
  • 退出。 当遇到第一个错误时，执行停止。错误之前运行的命令将被提交。
  • 继续。 即使某些命令失败，列表中的所有命令也会运行。
注意： 在与设备建立连接时，通过设置 onerror 参数，在 nitro_service() 方法中配置所需行为。
以下示例代码在一个操作中添加两个 ADC 设备：
ns[] newns = new ns[2];

//Specify details of first NetScaler
newns[0] = new ns();
newns[0].name = "ns_instance1";
newns[0].ip_address = "10.70.136.5";
newns[0].netmask = "255.255.255.0";
newns[0].gateway = "10.70.136.1";
...
...

//Specify details of second NetScaler
newns[1] = new ns();
newns[1].name = "ns_instance2";
newns[1].ip_address = "10.70.136.8";
newns[1].netmask = "255.255.255.0";
newns[1].gateway = "10.70.136.1";
...
...

//upload the details of the ADC appliances to the NITRO server
ns[] result = ns.add(nitroservice, newns);

异常处理

错误代码字段指示操作的状态。
  • 错误代码为 0 表示操作成功。
  • 非零错误代码表示处理 NITRO 请求时出错。
错误消息字段提供了简要说明和故障性质。
com.citrix.sdx.nitro.exception.nitro_exception 类捕获 NITRO API 执行中的所有异常。要获取有关异常的信息，可以使用 getErrorCode() 方法。
有关错误代码的更详细说明，请参阅 <NITRO_SDK_HOME>/doc 文件夹中提供的 API 参考。