SDK .NET
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.
Vous devez créer 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 à une appliance SDX dont l’adresse IP est 10.102.31.16 à l’aide du protocole HTTPS :
``` pre codeblock //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”);
Remarque : Vous devez utiliser l'objet
nitro_service dans toutes les autres opérations NITRO sur l'appliance.
Pour vous déconnecter de l'appliance, appelez la méthode logout () comme suit :
``` pre codeblock
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. <resource_type>. Chacun de ces packages ou espaces de noms contient une classe nommée <resource_type>qui fournit les API pour configurer la ressource.
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 d’autres opérations telles que la création d’une ressource, la récupération de ressources et de propriétés de ressource, 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 nouvelle ressource (par exemple, une instance Citrix ADC) sur l’appliance SDX :
- 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 Citrix ADC nommée « ns_instance » sur l’appliance SDX :
``` pre codeblock 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 Citrix ADC instance ns result = ns.add(nitroservice, newns);
### Récupération des détails
Pour récupérer les propriétés d'une ressource sur l'appliance SDX, procédez comme suit :
1. Récupérez les configurations de l'appliance à l'aide de la méthode get (). Le résultat est un objet de ressource.
2. 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 :
``` pre codeblock
//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);
<!--NeedCopy-->
Récupération des statistiques
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 récupère les statistiques d’une instance Citrix ADC portant l’ID 123456a :
``` pre codeblock 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);
### Mettre à jour une ressource
Pour mettre à jour les propriétés d'une ressource existante sur l'appliance, procédez comme suit :
1. Définissez la propriété id sur l'ID de la ressource à mettre à jour.
2. 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é.
3. 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 Citrix ADC portant l'ID 123456a en « ns_instance_new » :
``` pre codeblock
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);
<!--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 Citrix ADC portant l’ID 1 :
``` pre codeblock ns obj = new ns(); obj.id = “123456a”; ns.delete(nitroservice, obj);
### 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 :
- **Sortir.** 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 : Vous devez configurer le comportement requis lors de l'établissement d'une connexion avec l'appliance, en définissant le paramètre
onerror dans la méthode
nitro_service ().
L'exemple de code suivant ajoute deux NetScaler en une seule opération :
``` pre codeblock
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 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.
Toutes les exceptions dans l’exécution des API NITRO sont détectées par la classe com.citrix.sdx.nitro.exception.nitro_exception. Pour obtenir des informations sur l’exception, vous pouvez utiliser la méthode getErrorCode ().
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>dossier /doc.