NetScaler SDX

Servicios web REST

May 4, 2023

Contribución de:

REST (Transferencia de estado representacional) es un estilo arquitectónico basado en solicitudes y respuestas HTTP simples entre el cliente y el servidor. REST se usa para consultar o cambiar el estado de los objetos en el lado del servidor. En REST, el lado del servidor se modela como un conjunto de entidades en el que cada entidad se identifica mediante una URL única.

Cada recurso también tiene un estado en el que se pueden realizar las siguientes operaciones:

Crear. Los clientes pueden crear nuevos recursos del lado del servidor en un recurso “contenedor”. Puede pensar en los recursos contenedores como carpetas y en los recursos secundarios como archivos o subcarpetas. El cliente que llama proporciona el estado para que se cree el recurso. El estado se puede especificar en la solicitud mediante el formato XML o JSON. El cliente también puede especificar la URL única que identifica el nuevo objeto. Alternativamente, el servidor puede elegir y devolver una URL única que identifique el objeto creado. El método HTTP utilizado para crear solicitudes es POST.
Lee. Los clientes pueden recuperar el estado de un recurso especificando su URL con el método HTTP GET. El mensaje de respuesta contiene el estado del recurso, expresado en formato JSON.
Actualización. Puede actualizar el estado de un recurso existente; para ello, especifique la dirección URL que identifica ese objeto y su nuevo estado en JSON o XML, o bien utilice el método PUT HTTP.
Borrar. Puede destruir un recurso que exista en el lado del servidor mediante el método HTTP DELETE y la URL que identifica el recurso que se va a eliminar.

Además de estas cuatro operaciones CLAE (Crear, Leer, Actualizar y Eliminar), los recursos pueden admitir otras operaciones o acciones. Estas operaciones utilizan el método HTTP POST, en el que el cuerpo de la solicitud en JSON especifica la operación que se va a realizar y los parámetros para esa operación.

Las API de SDX NITRO se clasifican según el alcance y el propósito de las API en API del sistema y API de configuración.

APIs del sistema

El primer paso para utilizar NITRO es establecer una sesión con el dispositivo SDX y, a continuación, autenticar la sesión mediante las credenciales del administrador.

Especifique el nombre de usuario y la contraseña en el objeto de inicio de sesión. El identificador de sesión que se crea debe especificarse en el encabezado de solicitud de todas las operaciones posteriores de la sesión.

Nota: Debe tener una cuenta de usuario en ese dispositivo. Las configuraciones que puede realizar están limitadas por la función administrativa asignada a su cuenta.

Para conectarse a un dispositivo SDX con la dirección IP 10.102.31.16 mediante el protocolo HTTPS:

URL https://10.102.31.16/nitro/v2/config/login/
Método HTTP POST
Solicitar
- Header
```
 Content-Type:application/vnd.com.citrix.sdx.login+json
 
```
  Nota: También se pueden utilizar tipos de contenido como “application/x-www-form-urlencoded” que se admitían en versiones anteriores de NITRO. Asegúrese de que la carga útil sea la misma que la utilizada en versiones anteriores. Las cargas útiles proporcionadas en esta documentación solo son aplicables si el tipo de contenido es de la forma ‘application/vnd.com.citrix.sdx.login + json’.
- Payload
```
 {
     "login":
     {
         "username":"nsroot",
         "password":"verysecret"
     }
 }
 
```

Carga útil de respuesta

Header

 HTTP/1.0 201 Created
 Set-Cookie:
 NITRO_AUTH_TOKEN=##87305E9C51B06C848F0942; path=/nitro/v2
 <!--NeedCopy-->

Nota: Utilice el ID de sesión en todas las operaciones de NITRO posteriores en el dispositivo.

Nota: De forma predeterminada, la conexión con el dispositivo caduca después de 30 minutos de inactividad. Puede modificar el período de tiempo de espera especificando un nuevo período de tiempo de espera (en segundos) en el objeto de inicio de sesión. Por ejemplo, para modificar el período de tiempo de espera a 60 minutos, la carga útil de la solicitud es:

{
    "login":
    {
        "username":"nsroot",
        "password":"verysecret",
        "timeout":3600
    }
}
<!--NeedCopy-->

También puede conectarse al dispositivo para realizar una sola operación, especificando el nombre de usuario y la contraseña en el encabezado de solicitud de la operación. Por ejemplo, para conectarse a un dispositivo mientras se crea una instancia de NetScaler:

URL
HTTP (método)

Solicitar

Header

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

Payload

 {
     "ns":
     {
         ...
     }
 }
 <!--NeedCopy-->

Respuesta.
- Header
```
 HTTP/1.0 201 Created
 
```

Para desconectarse del dispositivo, utilice el método DELETE:

URL
Método HTTP DELETE

Solicitar

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.login+json
 <!--NeedCopy-->

API de configuración

El protocolo NITRO se puede usar para configurar los recursos del dispositivo SDX.

Cada recurso SDX tiene una URL única asociada, según el tipo de operación que se vaya a realizar. Las URL de las operaciones de configuración tienen el siguiente formato: http://<IP>/nitro/v2/config/<resource_type>

Crear un recurso

Para crear un recurso (por ejemplo, una instancia de NetScaler) en el dispositivo SDX, especifique el nombre del recurso y otros argumentos relacionados en el objeto de recurso específico. Por ejemplo, para crear una instancia de NetScaler llamada vpx1:

URL
HTTP (método)

Solicitar

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "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"
             }
         ]
     }
 }
 <!--NeedCopy-->

Recuperar datos y estadísticas de los recursos

Los detalles de los recursos SDX se pueden recuperar de la siguiente manera:

Para recuperar los detalles de un recurso específico en el dispositivo SDX, especifique el identificador del recurso en la URL.
Para recuperar las propiedades de los recursos en función de algún filtro, especifique las condiciones del filtro en la URL.

La URL tiene el siguiente formato: http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>
Si es probable que su solicitud devuelva muchos recursos del dispositivo, puede recuperar estos resultados en fragmentos dividiéndolos en “páginas” y recuperándolos página por página.

Por ejemplo, suponga que desea recuperar todas las instancias de NetScaler en un SDX que tenga 53 de ellas. En lugar de recuperar las 53 en una respuesta grande, configure los resultados para que se dividan en páginas de 10 instancias de NetScaler cada una (6 páginas en total). A continuación, recuperarlos del servidor página por página.

Especifique el recuento de páginas con el parámetro de cadena de consulta de tamaño de página y use el parámetro de cadena de consulta de número de página para especificar el número de página que quiere recuperar. La URL tiene el siguiente formato: http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

No tiene que recuperar todas las páginas ni recuperar las páginas en orden. Cada solicitud es independiente e incluso puede cambiar la configuración del tamaño de página entre solicitudes.

Nota: Para tener una idea de la cantidad de recursos que es probable que devuelva una solicitud, puede usar el parámetro de cadena de consulta count para solicitar que se devuelva un recuento de los recursos, en lugar de los recursos en sí. Para obtener el número de instancias de NetScaler disponibles, la URL sería http://<IP>/nitro/v2/config/<resource_type>?count=yes

Para recuperar la información de configuración de la instancia de NetScaler con ID 123456a:

URL
Método HTTP GET

Actualizar un recurso

Para actualizar un recurso SDX existente, use el método PUT HTTP. En la carga útil de la solicitud HTTP, especifique el nombre y los demás argumentos que se deben cambiar. Por ejemplo, para cambiar el nombre de la instancia de NetScaler con el ID 123456a a vpx2:

URL
HTTP (método)

Solicitar carga útil

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Payload

 {
     "ns":
     {
         "name":"vpx2",
         "id":"123456a"
     }
 }
 <!--NeedCopy-->

Eliminar un recurso

Para eliminar un recurso existente, especifique el nombre del recurso que se eliminará en la URL. Por ejemplo, para eliminar una instancia de NetScaler con ID 123456a:

URL
HTTP (método)

Solicitar

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 <!--NeedCopy-->

Operaciones a granel

Puede consultar o cambiar varios recursos simultáneamente y, por lo tanto, minimizar el tráfico de red. Por ejemplo, puede agregar varios dispositivos NetScaler SDX en la misma operación. También puede agregar recursos de diferentes tipos en una solicitud.

Para tener en cuenta el error de algunas operaciones dentro de la operación masiva, NITRO le permite configurar uno de los siguientes comportamientos:

Salida. Cuando se encuentra el primer error, la ejecución se detiene. Se confirman los comandos que se ejecutaron antes del error.
Continúe. Todos los comandos de la lista se ejecutan incluso si algunos comandos fallan.

Nota: Configure el comportamiento requerido en el encabezado de la solicitud mediante el parámetro X-NITRO-ONERROR.

Para agregar 2 recursos de NetScaler en una operación y continuar si falla un comando:

URL.
Método HTTP.

Solicitar carga útil.

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 X-NITRO-ONERROR:continue
 <!--NeedCopy-->

Payload

 {
     "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"
         }
     ]
 }
 <!--NeedCopy-->

Para añadir varios recursos (NetScaler y dos usuarios de MPS) en una operación y continuar si se produce un error en un comando:

URL.
Método HTTP. POST

Solicitar carga útil.

Header

 Cookie:NITRO_AUTH_TOKEN=tokenvalue
 Content-Type:application/vnd.com.citrix.sdx.ns+json
 X-NITRO-ONERROR:continue
 <!--NeedCopy-->

Payload

 {
     "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"
         }
     ]
 }
 <!--NeedCopy-->

Gestión de excepciones

El campo errorcode indica el estado de la operación.

Un código de error de 0 indica que la operación se ha realizado correctamente.
Un código de error distinto de cero indica un error en el procesamiento de la solicitud NITRO.

El campo de mensaje de error proporciona una breve explicación y la naturaleza del error.

La versión oficial de este contenido está en inglés. Para mayor comodidad, parte del contenido de la documentación de Cloud Software Group solo tiene traducción automática. Cloud Software Group no puede controlar el contenido con traducción automática, que puede contener errores, imprecisiones o un lenguaje inadecuado. No se ofrece ninguna garantía, ni implícita ni explícita, en cuanto a la exactitud, la fiabilidad, la idoneidad o la precisión de las traducciones realizadas del original en inglés a cualquier otro idioma, o que su producto o servicio de Cloud Software Group se ajusten a cualquier contenido con traducción automática, y cualquier garantía provista bajo el contrato de licencia del usuario final o las condiciones de servicio, o cualquier otro contrato con Cloud Software Group, de que el producto o el servicio se ajusten a la documentación no se aplicará en cuanto dicha documentación se ha traducido automáticamente. Cloud Software Group no se hace responsable de los daños o los problemas que puedan surgir del uso del contenido traducido automáticamente.

¿Le ha resultado útil?

Servicios web REST

May 4, 2023

Contribución de:

May 4, 2023

Contribución de:

¿Le ha resultado útil?