Java SDK

Last published : Sep 23, 2026
SDX NITRO APIs werden je nach Umfang und Zweck der APIs in System-APIs und Konfigurations-APIs kategorisiert. Sie können auch Fehler bei NITRO-Operationen beheben.
Related information

System-APIs

Der erste Schritt zur Verwendung von NITRO besteht darin, eine Sitzung mit der SDX-Appliance herzustellen und die Sitzung dann mithilfe der Anmeldeinformationen des Administrators zu authentifizieren.
Erstellen Sie ein Objekt der Klasse nitro_service, indem Sie die IP-Adresse der Appliance und das Protokoll für die Verbindung mit der Appliance (HTTP oder HTTPS) angeben. Anschließend verwenden Sie dieses Objekt und melden sich bei der Appliance an, indem Sie den Benutzernamen und das Kennwort des Administrators angeben.
Hinweis: Sie müssen über ein Benutzerkonto auf dieser Appliance verfügen. Die Konfigurationsoperationen, die Sie ausführen können, werden durch die Ihrem Konto zugewiesene Administratorrolle eingeschränkt.
Der folgende Beispielcode stellt eine Verbindung zu einer SDX-Appliance mit der IP-Adresse 10.102.31.16 unter Verwendung des HTTPS-Protokolls her:
//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");
Hinweis: Verwenden Sie das nitro_service-Objekt bei allen weiteren NITRO-Operationen auf der Appliance.
Zum trennen von der Appliance rufen Sie die logout() Methode wie folgt auf:
nitroservice.logout();

Konfigurations-APIs

Das NITRO-Protokoll kann verwendet werden, um die Ressourcen der SDX-Appliance zu konfigurieren.
Die APIs zur Konfiguration einer Ressource sind in Pakete oder Namespaces gruppiert, die das Format com.citrix.sdx.nitro.resource.config.<resource_type> haben. Jedes dieser Pakete oder Namespaces enthält eine Klasse namens <resource_type>, die die APIs zur Konfiguration der Ressource bereitstellt.
Zum Beispiel verfügt die NetScaler-Ressource über das Paket oder den Namespace com.citrix.sdx.nitro.resource.config.ns.
Eine Ressourcenklasse bietet APIs, um viele andere Operationen auszuführen. Diese Operationen können das Erstellen einer Ressource, das Abrufen von Ressourcendetails und Statistiken, das Aktualisieren einer Ressource, das Löschen von Ressourcen und das Ausführen von Massenoperationen für Ressourcen sein.

Erstellen einer Ressource

Um eine Ressource (z. B. eine NetScaler-Instanz) auf der SDX-Appliance zu erstellen, gehen Sie wie folgt vor:
  1. Legen Sie den Wert für die erforderlichen Eigenschaften der Ressource mithilfe des entsprechenden Eigenschaftsnamens fest. Das Ergebnis ist ein Ressourcenobjekt, das die für die Ressource erforderlichen Details enthält. Hinweis: Diese Werte werden lokal auf dem Client festgelegt. Die Werte werden erst auf der Appliance angezeigt, wenn das Objekt hochgeladen wurde.
  2. Laden Sie das Ressourcenobjekt mithilfe der statischen Methode add() auf die Appliance hoch.
Der folgende Beispielcode erstellt eine NetScaler-Instanz namens „ns_instance“ auf der SDX-Appliance:
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);

Abrufen von Ressourcendetails

Um die Eigenschaften einer Ressource auf der SDX-Appliance abzurufen, gehen Sie wie folgt vor:
  1. Rufen Sie die Konfigurationen von der Appliance mithilfe der Methode get() ab. Das Ergebnis ist ein Ressourcenobjekt.
  2. Extrahieren Sie die erforderliche Eigenschaft aus dem Objekt mithilfe des entsprechenden Eigenschaftsnamens.
Der folgende Beispielcode ruft die Details aller NetScaler®-Ressourcen ab:
//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());

Abrufen von Ressourcenstatistiken

Eine SDX-Appliance sammelt Statistiken über die Nutzung ihrer Funktionen. Sie können diese Statistiken mithilfe von NITRO abrufen.
Der folgende Beispielcode ruft die Statistiken einer NetScaler-Instanz mit der ID 123456a ab:
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());

Aktualisieren einer Ressource

Um die Eigenschaften einer vorhandenen Ressource auf der Appliance zu aktualisieren, gehen Sie wie folgt vor:
  1. Legen Sie die Eigenschaft „id“ auf die ID der zu aktualisierenden Ressource fest.
  2. Legen Sie den Wert für die erforderlichen Eigenschaften der Ressource mithilfe des entsprechenden Eigenschaftsnamens fest. Das Ergebnis ist ein Ressourcenobjekt. Hinweis: Diese Werte werden lokal auf dem Client festgelegt. Die Werte werden erst auf dem Gerät widergespiegelt, wenn das Objekt hochgeladen wurde.
  3. Laden Sie das Ressourcenobjekt mithilfe der Methode update() auf das Gerät hoch.
Der folgende Beispielcode aktualisiert den Namen der NetScaler-Instanz mit der ID 123456a auf '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);

Löschen einer Ressource

Um eine vorhandene Ressource zu löschen, rufen Sie die statische Methode delete() für die Ressourcenklasse auf und übergeben Sie die ID der zu entfernenden Ressource als Argument.
Der folgende Beispielcode löscht eine NetScaler-Instanz mit der ID 1:
ns obj = new ns();
obj.set_id("123456a");
ns.delete(nitroservice, obj);

Massenoperationen

Sie können mehrere Ressourcen gleichzeitig abfragen oder ändern und so den Netzwerkverkehr minimieren. Sie können beispielsweise mehrere NetScaler SDX-Appliances in derselben Operation hinzufügen.
Jede Ressourcenklasse verfügt über Methoden, die ein Array von Ressourcen zum Hinzufügen, Aktualisieren und Entfernen von Ressourcen entgegennehmen. Um eine Massenoperation durchzuführen, geben Sie die Details jeder Operation lokal an und senden Sie die Details dann gleichzeitig an den Server.
Um das Fehlschlagen einiger Operationen innerhalb der Massenoperation zu berücksichtigen, können Sie in NITRO eines der folgenden Verhaltensweisen konfigurieren:
  • Beenden. Wenn der erste Fehler auftritt, wird die Ausführung gestoppt. Die vor dem Fehler ausgeführten Befehle werden übernommen.
  • Fortfahren. Alle Befehle in der Liste werden ausgeführt, auch wenn einige Befehle fehlschlagen.
Hinweis: Konfigurieren Sie das erforderliche Verhalten beim Herstellen einer Verbindung mit dem Gerät, indem Sie den onerror Parameter in der nitro_service()-Methode festlegen.
Der folgende Beispielcode fügt zwei ADC-Appliances in einem Vorgang hinzu:
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);

Ausnahmebehandlung

Das Fehlercode-Feld gibt den Status des Vorgangs an.
  • Ein Fehlercode von 0 zeigt an, dass der Vorgang erfolgreich war.
  • Ein Fehlercode ungleich Null zeigt einen Fehler bei der Verarbeitung der NITRO-Anfrage an.
Das Fehlermeldungsfeld liefert eine kurze Erklärung und die Art des Fehlers.
Die Klasse com.citrix.sdx.nitro.exception.nitro_exception fängt alle Ausnahmen bei der Ausführung von NITRO-APIs ab. Um Informationen über die Ausnahme zu erhalten, können Sie die getErrorCode() Methode verwenden.
Für eine detailliertere Beschreibung der Fehlercodes siehe die API-Referenz, die im <NITRO_SDK_HOME>/doc Ordner verfügbar ist.