Introducción a la API de REST
Instalación y configuración de la API de REST
En la Guía de instalación de Paragon Active Assurance se describe cómo descargar la API de REST, cómo instalarla en el servidor del centro de control y cómo configurarla para su uso. Consulte este documento.
Es vital establecer el SITE_URL parámetro correctamente en /etc/netrounds/netrounds.conf. Esto es para proporcionar una dirección URL pública en la que se puede acceder a la API de REST.
Configuración de la vida útil de los tokens de autorización REST
La vida útil de los tokens de autorización de API de REST es limitada y es de 10 años de forma predeterminada. Esto se rige por el parámetro REST_TOKEN_LIFETIME del archivo /etc/netrounds/netrounds.conf.
Cuando tenga la intención de usar la API de REST, debe cambiar el valor de este parámetro a lo que sea necesario.
Obtención de un token de autorización
Antes de que pueda comenzar a usar la API de REST, debe crear un token de autorización para ella. Esto se puede hacer en la GUI web del centro de control o desde la línea de comandos mediante el ncc comando. Consulte a continuación.
Deberá incluir este token en todo el código que llama a la API de REST; consulte este fragmento de código para ver un ejemplo.
Obtención de un token de autorización en la INTERFAZ gráfica de usuario web
- En la webapp, haga clic en el nombre de usuario de Paragon Active Assurance en la esquina superior derecha y seleccione Editar perfil en el menú emergente.
- Seleccione la pestaña tokens de API .
- Haga clic en el botón Agregar token de API.
- Se genera un nuevo token y se agrega a la lista (se pueden definir varios tokens). Asigne un nombre como desee en la columna Nombre .
El valor del token de API solo es visible en el momento de creación. Por lo tanto, debe anotarlo para poder usar el token más adelante.
Creación y administración de tokens de autorización desde la línea de comandos
Puede crear un token de API con el siguiente comando:
ncc rest-create-token --email <user email> [--accounts <list of accounts>] [--full-access] [--name <name of token>] [--force]
Tenga en cuenta que solo los administradores de cuentas y superusuarios pueden crear tokens de API.
Ya sea --accounts <list of accounts> que se proporcione o --full-access se debe proporcionar.
La --accounts opción especifica a qué cuentas debe tener acceso el token. El token solo tendrá acceso a las cuentas especificadas.
Si, en su lugar, especifica --full-access, entonces:
- si su usuario es un administrador de cuenta, el token funcionará para todas las cuentas a las que tenga acceso y tendrá el permiso admin en;
- si el usuario es Superusuario, el token tendrá acceso a todo el sistema. Esto significa que todas las cuentas, incluso si el usuario no es miembro explícito de todas ellas.
La --full-access opción da acceso al token a todas las cuentas. Se le pedirá que confirme esto. Utilice la opción para omitir la --force confirmación.
La --name opción le permite nombrar el token. Esto es opcional.
Puede enumerar todos los tokens de API con
ncc rest-list-tokens
Puede eliminar un token de API con
ncc rest-delete-token [--id <token id>] [--name <token name>]
id donde se obtiene enumerando los tokens.
Tenga en cuenta que los tokens de API creados en la GUI siempre están vinculados a una sola cuenta de forma predeterminada. Debe usar la herramienta de línea de ncc comandos para crear tokens con acceso más amplio.
Acceso al navegador de LA API de REST
Una vez que haya instalado y configurado la API de REST, puede acceder a un explorador de API para la API de REST en SITE_URL/rest/ (donde SITE_URL se define en /etc/netrounds/netrounds.conf). El navegador de API es interactivo y le permite probar las operaciones de LA API DE REST manualmente. También proporciona documentación de las características de la API de REST. Además, se vincula a un esquema JSON que describe exhaustivamente la API de REST (/rest/apispec_1.json). Vea la imagen a continuación. El propio navegador de LA API de REST se generó a partir de este esquema, y es posible generar código de cliente basado en él.
Antes de que pueda llamar a la API de REST desde el navegador de API, debe autorizar dichas acciones proporcionando el token de autorización que ha obtenido (como se explica en la sección Obtención de un token de autorización).
- Haga clic en el botón Autorizar .
- En el diálogo que se abre, escriba su token de autorización en Valor y haga clic en el botón Autorizar en el cuadro de diálogo. A continuación, cierre el cuadro de diálogo.
Ahora puede realizar operaciones de API de REST repetidamente desde esta página web. Sin embargo, si vuelve a cargar la página en su navegador, deberá repetir el procedimiento de autorización anterior.
En la práctica, las llamadas a la API de REST suelen ser secuencias de comandos desde un orquestador. En este documento, el orquestador está representado principalmente por código de Python que llama a la API de REST. Sin embargo, debe destacarse que se puede utilizar cualquier idioma aplicable. El token de autorización debe incluirse en cualquier código que haga llamadas a la API de REST.