NetScaler SDX

REST Web Services

May 4, 2023

Contributeur:

REST (Representational State Transfer) est un style architectural basé sur de simples requêtes et réponses HTTP entre le client et le serveur. REST est utilisé pour interroger ou modifier l’état des objets côté serveur. Dans REST, le côté serveur est modélisé comme un ensemble d’entités où chaque entité est identifiée par une URL unique.

Chaque ressource possède également un état dans lequel les opérations suivantes peuvent être effectuées :

Créez. Les clients peuvent créer de nouvelles ressources côté serveur sur une ressource « conteneur ». Les ressources de conteneur peuvent être considérées comme des dossiers et les ressources enfants comme des fichiers ou des sous-dossiers. Le client appelant fournit l’état de la ressource à créer. L’état peut être spécifié dans la demande en utilisant le format XML ou JSON. Le client peut également spécifier l’URL unique qui identifiera le nouvel objet. Le serveur peut également choisir et renvoyer une URL unique identifiant l’objet créé. La méthode HTTP utilisée pour les demandes de création est POST.
Lisez. Les clients peuvent récupérer l’état d’une ressource en spécifiant son URL à l’aide de la méthode HTTP GET. Le message de réponse contient l’état de la ressource, exprimé au format JSON.
Mise à jour. Vous pouvez mettre à jour l’état d’une ressource existante en spécifiant l’URL qui identifie cet objet et son nouvel état au format JSON ou XML, à l’aide de la méthode HTTP PUT.
Supprimer. Vous pouvez détruire une ressource qui existe côté serveur à l’aide de la méthode HTTP DELETE et de l’URL identifiant la ressource à supprimer.

Outre ces quatre opérations CRUD (créer, lire, mettre à jour et supprimer), les ressources peuvent prendre en charge d’autres opérations ou actions. Ces opérations utilisent la méthode HTTP POST, le corps de la requête en JSON spécifiant l’opération à effectuer et les paramètres de cette opération.

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.

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 spécifier le nom d’utilisateur et le mot de passe dans l’objet de connexion. L’ID de session créé doit être spécifié dans l’en-tête de demande de toutes les autres opérations de la session.

Remarque : Vous devez disposer d’un compte d’utilisateur sur cette appliance. Les configurations que vous pouvez effectuer sont limitées par le rôle administratif attribué à votre compte.

Pour vous connecter à un dispositif SDX dont l’adresse IP est 10.102.31.16 à l’aide du protocole HTTPS :

URL https://10.102.31.16/nitro/v2/config/login/
Méthode HTTP POST
Demander
- En-tête
  
  pre codeblock Content-Type:application/vnd.com.citrix.sdx.login+json 
  
  Remarque : Les types de contenu tels que « application/x-www-form-urlencoded » qui étaient pris en charge dans les versions antérieures de NITRO peuvent également être utilisés. Vous devez vous assurer que la charge utile est la même que celle utilisée dans les versions précédentes. Les charges utiles fournies dans cette documentation ne s’appliquent que si le type de contenu est de la forme « application/vnd.com.citrix.sdx.login+json ».
- Charge utile
  
  pre codeblock { "login": { "username":"nsroot", "password":"verysecret" } } 
Charge utile de réponse
- En-tête
  
  pre codeblock HTTP/1.0 201 Created Set-Cookie: NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2

Remarque : Vous devez utiliser l’ID de session dans toutes les autres opérations NITRO sur l’appliance.

Remarque : Par défaut, la connexion à l’appliance expire après 30 minutes d’inactivité. Vous pouvez modifier le délai d’expiration en spécifiant un nouveau délai d’expiration (en secondes) dans l’objet de connexion. Par exemple, pour modifier le délai d’expiration à 60 minutes, la charge utile de la demande est la suivante :

``` pre codeblock { “login”: { “username”:”nsroot”, “password”:”verysecret”, “timeout”:3600 } }

Vous pouvez également vous connecter à l'appliance pour effectuer une seule opération, en spécifiant le nom d'utilisateur et le mot de passe dans l'en-tête de demande de l'opération. Par exemple, pour vous connecter à un dispositif lors de la création d'une instance Citrix ADC :

-  **URL**
-  **Méthode HTTP**
-  **Demander**
    -  **En-tête**

        ``` pre codeblock
        X-NITRO-USER:nsroot
        X-NITRO-PASS:verysecret
        Content-Type:application/vnd.com.citrix.sdx.ns+json
        <!--NeedCopy-->

-  **Charge utile**

    ``` pre codeblock
    {
        "ns":
        {
            ...
        }
    }
    <!--NeedCopy--> ```

Réponse.
- En-tête
  
  pre codeblock HTTP/1.0 201 Created

Pour vous déconnecter de l’appliance, utilisez la méthode DELETE :

URL
Méthode HTTP DELETE
Demander
- En-tête
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.login+json

API de configuration

Le protocole NITRO peut être utilisé pour configurer les ressources de l’appliance SDX.

Chaque ressource SDX est associée à une URL unique, selon le type d’opération à effectuer. Les URL pour les opérations de configuration ont le format suivant : http://<IP>/nitro/v2/config/<resource_type>

Création d’une ressource

Pour créer une nouvelle ressource (par exemple, une instance Citrix ADC) sur l’appliance SDX, spécifiez le nom de la ressource et d’autres arguments associés dans l’objet de ressource spécifique. Par exemple, pour créer une instance Citrix ADC nommée vpx1 :

URL
Méthode HTTP
Demander
- En-tête
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json 
- Charge utile
  
  pre codeblock { "ns": { "name":"vpx1", "ip_address":"192.168.100.2", "netmask":"255.255.255.0", "gateway":"192.168.100.1", "image_name":"nsvpx-9.3-45_nc.xva", "vm_memory_total":2048, "throughput":1000, "pps":1000000, "license":"Standard", "profile_name":"ns_nsroot_profile", "username":"admin", "password":"admin", "network_interfaces": [ { "port_name":"10/1" }, { "port_name":"10/2" } ] } }

Extraction des détails et des statistiques sur les ressources

Les détails des ressources SDX peuvent être récupérés comme suit :

Pour récupérer les détails d’une ressource spécifique sur l’appliance SDX, spécifiez l’ID de la ressource dans l’URL.
Pour récupérer les propriétés des ressources sur la base de certains filtres, spécifiez les conditions du filtre dans l’URL.

L’URL se présente sous la forme suivante : http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>
Si votre demande est susceptible d’entraîner le renvoi d’un grand nombre de ressources par l’appliance, vous pouvez récupérer ces résultats par segments en les divisant en « pages » et en les récupérant page par page.

Par exemple, supposons que vous souhaitez récupérer toutes les instances Citrix ADC sur un SDX qui en possède 53. Au lieu de récupérer les 53 en une seule grande réponse, vous pouvez configurer les résultats pour qu’ils soient divisés en pages de 10 instances Citrix ADC chacune (6 pages au total) et les récupérer à partir du serveur page par page.

Vous spécifiez le nombre de pages avec le paramètre de chaîne de requête pagesize et utilisez le paramètre de chaîne de requête pageno pour spécifier le numéro de page que vous souhaitez récupérer. L’URL se présente sous la forme suivante : http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

Il n’est pas nécessaire de récupérer toutes les pages, ni de récupérer les pages dans l’ordre. Chaque demande est indépendante et vous pouvez même modifier le paramètre de taille de page entre les demandes.

Remarque : Si vous voulez avoir une idée du nombre de ressources susceptibles d’être renvoyées par une demande, vous pouvez utiliser le paramètre de chaîne de requête count pour demander le nombre de ressources à renvoyer, plutôt que les ressources elles-mêmes. Pour obtenir le nombre d’instances Citrix ADC disponibles, l’URL serait http://<IP>/nitro/v2/config/<resource_type>?count=yes

Pour récupérer les informations de configuration de l’instance Citrix ADC portant l’ID 123456a :

URL
Méthode HTTP GET

Mettre à jour une ressource

Pour mettre à jour une ressource SDX existante, utilisez la méthode HTTP PUT. Dans la charge utile de la requête HTTP, spécifiez le nom et les autres arguments qui doivent être modifiés. Par exemple, pour modifier le nom de l’instance Citrix ADC portant l’ID 123456a en vpx2 :

URL
Méthode HTTP
Charge utile de la demande
- En-tête
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json 
- Charge utile
  
  pre codeblock { "ns": { "name":"vpx2", "id":"123456a" } }

Supprimer une ressource

Pour supprimer une ressource existante, spécifiez le nom de la ressource à supprimer dans l’URL. Par exemple, pour supprimer une instance Citrix ADC portant l’ID 123456a :

URL
Méthode HTTP
Demander
- En-tête
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json

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. Vous pouvez également ajouter des ressources de différents types en une seule demande.

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 dans l’en-tête de demande à l’aide du paramètre X-NITRO-ONERROR.

Pour ajouter 2 ressources Citrix ADC en une seule opération et continuer en cas d’échec d’une commande :

URL.
Méthode HTTP.
Charge utile de la demande.
- En-tête
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue 
- Charge utile
  
  pre codeblock { "ns": [ { "name":"ns_instance1", "ip_address":"10.70.136.5", "netmask":"255.255.255.0", "gateway":"10.70.136.1" }, { "name":"ns_instance2", "ip_address":"10.70.136.8", "netmask":"255.255.255.0", "gateway":"10.70.136.1" } ] }

Pour ajouter plusieurs ressources (Citrix ADC et deux utilisateurs MPS) en une seule opération et continuer en cas d’échec d’une commande :

URL.
Méthode HTTP. POST
Charge utile de la demande.
- En-tête
  
  pre codeblock Cookie:NITRO_AUTH_TOKEN=tokenvalue Content-Type:application/vnd.com.citrix.sdx.ns+json X-NITRO-ONERROR:continue 
- Charge utile
  
  pre codeblock { "ns": [ { "name":"ns_instance1", "ip_address":"10.70.136.5", "netmask":"255.255.255.0", "gateway":"10.70.136.1" }, { "name":"ns_instance2", "ip_address":"10.70.136.8", "netmask":"255.255.255.0", "gateway":"10.70.136.1" } ], "mpsuser": [ { "name":"admin", "password":"admin", "permission":"superuser" }, { "name":"admin", "password":"admin", "permission":"superuser" } ] }

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 version officielle de ce document est en anglais. Certains contenus de la documentation Cloud Software Group ont été traduits de façon automatique à des fins pratiques uniquement. Cloud Software Group n'exerce aucun contrôle sur le contenu traduit de façon automatique, qui peut contenir des erreurs, des imprécisions ou un langage inapproprié. Aucune garantie, explicite ou implicite, n'est fournie quant à l'exactitude, la fiabilité, la pertinence ou la justesse de toute traduction effectuée depuis l'anglais d'origine vers une autre langue, ou quant à la conformité de votre produit ou service Cloud Software Group à tout contenu traduit de façon automatique, et toute garantie fournie en vertu du contrat de licence de l'utilisateur final ou des conditions d'utilisation des services applicables, ou de tout autre accord avec Cloud Software Group, quant à la conformité du produit ou service à toute documentation ne s'applique pas dans la mesure où cette documentation a été traduite de façon automatique. Cloud Software Group ne pourra être tenu responsable de tout dommage ou problème dû à l'utilisation de contenu traduit de façon automatique.

REST Web Services

May 4, 2023

Contributeur:

May 4, 2023

Contributeur: