SDK Java
Les API SDX NITRO sont classées en fonction de leur portée et de leur objectif en API système et en API de configuration. Vous pouvez également résoudre les problèmes liés aux opérations NITRO.
API système
La première étape pour utiliser NITRO consiste à établir une session avec l’appliance SDX, puis à authentifier la session à l’aide des informations d’identification de l’administrateur.
Créez un objet de la classe nitro_service en spécifiant l’adresse IP de l’appliance et le protocole pour se connecter à l’appliance (HTTP ou HTTPS). Vous pouvez ensuite utiliser cet objet et vous connecter à l’appliance en spécifiant le nom d’utilisateur et le mot de passe de l’administrateur.
Remarque : Vous devez disposer d’un compte d’utilisateur sur cette appliance. Les opérations de configuration que vous pouvez effectuer sont limitées par le rôle administratif attribué à votre compte.
L’exemple de code suivant se connecte à un dispositif SDX dont l’adresse IP est 10.102.31.16 à l’aide du protocole HTTPS :
//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");
<!--NeedCopy-->
Remarque : Utilisez l’objet nitro_service dans toutes les autres opérations NITRO sur l’appliance.
Pour vous déconnecter de l’appliance, appelez la logout() méthode comme suit :
nitroservice.logout();
<!--NeedCopy-->
API de configuration
Le protocole NITRO peut être utilisé pour configurer les ressources de l’appliance SDX.
Les API permettant de configurer une ressource sont regroupées en packages ou espaces de noms au format com.citrix.sdx.nitro.resource.config.
Par exemple, la ressource NetScaler possède le package ou l’espace de noms com.citrix.sdx.nitro.resource.config.ns.
Une classe de ressources fournit des API pour effectuer de nombreuses autres opérations. Ces opérations peuvent être la création d’une ressource, la récupération de détails et de statistiques sur les ressources, la mise à jour d’une ressource, la suppression de ressources et l’exécution d’opérations en bloc sur les ressources.
Création d’une ressource
Pour créer une ressource (par exemple, une instance NetScaler) sur l’appliance SDX, procédez comme suit :
- Définissez la valeur des propriétés requises de la ressource en utilisant le nom de propriété correspondant. Le résultat est un objet de ressource qui contient les détails requis pour la ressource. Remarque : Ces valeurs sont définies localement sur le client. Les valeurs ne sont pas reflétées sur l’appliance tant que l’objet n’est pas chargé.
- Téléchargez l’objet de ressource sur l’appliance, à l’aide de la méthode statique add ().
L’exemple de code suivant crée une instance NetScaler nommée « ns_instance » sur l’appliance SDX :
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);
<!--NeedCopy-->
Extraction des détails sur les ressources
Pour récupérer les propriétés d’une ressource sur l’appliance SDX, procédez comme suit :
- Récupérez les configurations de l’appliance à l’aide de la méthode get (). Le résultat est un objet de ressource.
- Extrayez la propriété requise de l’objet en utilisant le nom de propriété correspondant.
L’exemple de code suivant récupère les détails de toutes les ressources 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());
<!--NeedCopy-->
Extraction des statistiques sur les ressources
Une appliance SDX collecte des statistiques sur l’utilisation de ses fonctionnalités. Vous pouvez récupérer ces statistiques à l’aide de NITRO.
L’exemple de code suivant extrait les statistiques d’une instance NetScaler portant l’ID 123456a :
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());
<!--NeedCopy-->
Mettre à jour une ressource
Pour mettre à jour les propriétés d’une ressource existante sur l’appliance, procédez comme suit :
- Définissez la propriété id sur l’ID de la ressource à mettre à jour.
- Définissez la valeur des propriétés requises de la ressource en utilisant le nom de propriété correspondant. Le résultat est un objet de ressource. Remarque : Ces valeurs sont définies localement sur le client. Les valeurs ne sont pas reflétées sur l’appliance tant que l’objet n’est pas chargé.
- Téléchargez l’objet de ressource sur l’appliance, à l’aide de la méthode update ().
L’exemple de code suivant met à jour le nom de l’instance NetScaler portant l’ID 123456a en « 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);
<!--NeedCopy-->
Supprimer une ressource
Pour supprimer une ressource existante, appelez la méthode statique delete () sur la classe de ressources, en passant l’ID de la ressource à supprimer, en tant qu’argument.
L’exemple de code suivant supprime une instance NetScaler portant l’ID 1 :
ns obj = new ns();
obj.set_id("123456a");
ns.delete(nitroservice, obj);
<!--NeedCopy-->
Opérations en vrac
Vous pouvez interroger ou modifier plusieurs ressources simultanément et ainsi réduire le trafic réseau. Par exemple, vous pouvez ajouter plusieurs appliances NetScaler SDX au cours de la même opération.
Chaque classe de ressources possède des méthodes qui prennent un tableau de ressources pour ajouter, mettre à jour et supprimer des ressources. Pour effectuer une opération en bloc, spécifiez les détails de chaque opération localement, puis envoyez les détails en une seule fois au serveur.
Pour tenir compte de l’échec de certaines opérations au sein de l’opération en bloc, NITRO vous permet de configurer l’un des comportements suivants :
- Quitter. Lorsque la première erreur est rencontrée, l’exécution s’arrête. Les commandes qui ont été exécutées avant l’erreur sont validées.
- Continuer. Toutes les commandes de la liste sont exécutées même si certaines commandes échouent.
Remarque : Configurez le comportement requis lors de l’établissement d’une connexion avec l’appliance, en définissant
onerror le paramètre dans la méthode
nitro_service ().
L’exemple de code suivant ajoute deux dispositifs ADC en une seule opération :
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);
<!--NeedCopy-->
Gestion des exceptions
Le champ Code d’erreur indique l’état de l’opération.
- Un code d’erreur de 0 indique que l’opération a réussi.
- Un code d’erreur différent de zéro indique une erreur dans le traitement de la demande NITRO.
Le champ du message d’erreur fournit une brève explication et la nature de l’échec.
La classe com.citrix.sdx.nitro.exception.nitro_exception intercepte toutes les exceptions dans l’exécution des API NITRO. Pour obtenir des informations sur l’exception, vous pouvez utiliser la getErrorCode() méthode.
Pour une description plus détaillée des codes d’erreur, consultez la référence de l’API disponible dans le <NITRO_SDK_HOME>/doc dossier.