Citrix ADC SDX 13.0

Servicios web de REST

REST (Representational State Transfer) es un estilo arquitectónico basado en solicitudes HTTP simples y respuestas entre el cliente y el servidor. REST se utiliza 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 donde 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 del contenedor como carpetas, y los recursos secundarios como archivos o subcarpetas. El cliente que realiza la llamada proporciona el estado del recurso que se va a crear. El estado se puede especificar en la solicitud mediante el formato XML o JSON. El cliente también puede especificar la URL única que identificará 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 dirección 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.
  • Suprimir. Puede destruir un recurso que existe en el lado del servidor mediante el método DELETE HTTP y la dirección URL que identifica el recurso que se va a quitar.

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, con el cuerpo de la solicitud en JSON especificando 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 las API del sistema y las API de configuración.

API 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.

Debe especificar 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
  • Petición
    • Encabezado

       Content-Type:application/vnd.com.citrix.sdx.login+json
      

      Nota: También se pueden usar tipos de contenido como ‘application/x -www-form-urlencoded’ que se admitían en versiones anteriores de NITRO. Debe asegurarse de que la carga útil es 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’.

    • Carga útil

       {
           "login":
           {
               "username":"nsroot",
               "password":"verysecret"
           }
       }
      
  • Carga útil de respuesta
    • Encabezado

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

Nota: Debe utilizar el ID de sesión en todas las operaciones de NITRO adicionales del 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
    }
}

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 Citrix ADC:

  • URL
  • Método HTTP
  • Petición
    • Encabezado

       X-NITRO-USER:nsroot
       X-NITRO-PASS:verysecret
       Content-Type:application/vnd.com.citrix.sdx.ns+json
      
    • Carga útil

       {
           "ns":
           {
               ...
           }
       }
      
  • Respuesta.
    • Encabezado

       HTTP/1.0 201 Created
      

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

  • URL
  • Método HTTP DELETE
  • Petición
    • Encabezado

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

API de configuración

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

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

Creación de un recurso

Para crear un nuevo recurso (por ejemplo, una instancia de Citrix ADC) 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 Citrix ADC denominada vpx1:

  • URL
  • Método HTTP
  • Petición
    • Encabezado

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
      
    • Carga útil

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

Recuperación de detalles y estadísticas de recursos

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

  • Para recuperar detalles de un recurso específico en el dispositivo SDX, especifique el identificador del recurso en la dirección URL.

  • Para recuperar las propiedades de los recursos sobre la base de algún filtro, especifique las condiciones de filtro en la URL.

    La URL tiene la forma:http://<IP>/nitro/v2/config/<resource_type>?filter=<property1>:<value>,<property2>:<value>

  • Si es probable que su solicitud produzca un gran número de recursos devueltos desde el dispositivo, puede recuperar estos resultados en fragmentos dividiéndolos en “páginas” y recuperándolos página por página.

    Por ejemplo, suponga que quiere recuperar todas las instancias Citrix ADC en un SDX que tenga 53 de ellas. En lugar de recuperar los 53 en una gran respuesta, puede configurar los resultados para que se dividan en páginas de 10 instancias de Citrix ADC cada una (6 páginas en total) y 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 utilice el parámetro de cadena de consulta “pageno” para especificar el número de página que quiere recuperar. La URL tiene la forma:http://<IP>/nitro/v2/config/<resource_type>?pageno=<value>&pagesize=<value>

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

    Nota: Si quiere tener una idea del número de recursos que es probable que devuelvan una solicitud, puede utilizar el parámetro de cadena de consulta de recuento para solicitar un recuento de los recursos que se devuelvan, en lugar de los propios recursos. Para obtener el número de instancias de Citrix ADC disponibles, la dirección URL sería http://<IP>/nitro/v2/config/<resource_type>?count=yes

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

  • URL
  • Método HTTP GE T

Actualización de un recurso

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

  • URL
  • Método HTTP
  • Solicitar carga útil
    • Encabezado

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
      
    • Carga útil

       {
           "ns":
           {
               "name":"vpx2",
               "id":"123456a"
           }
       }
      

Eliminación de un recurso

Para eliminar un recurso existente, especifique el nombre del recurso que se va a eliminar en la dirección URL. Por ejemplo, para eliminar una instancia de Citrix ADC con ID 123456a:

  • URL
  • Método HTTP
  • Petición
    • Encabezado

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

Operaciones en bloque

Puede consultar o cambiar varios recursos simultáneamente y, por lo tanto, minimizar el tráfico de red. Por ejemplo, puede agregar varios dispositivos Citrix ADC 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:

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

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

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

  • URL.
  • Método HTTP.
  • Solicitar carga útil.
    • Encabezado

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       X-NITRO-ONERROR:continue
      
    • Carga útil

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

Para agregar varios recursos (Citrix ADC y dos usuarios MPS) en una operación y continuar si falla un comando:

  • URL.
  • Método HTTP. POST
  • Solicitar carga útil.
    • Encabezado

       Cookie:NITRO_AUTH_TOKEN=tokenvalue
       Content-Type:application/vnd.com.citrix.sdx.ns+json
       X-NITRO-ONERROR:continue
      
    • Carga útil

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

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 al procesar la solicitud NITRO.

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

Servicios web de REST