Primeros Pasos (con Onesait Platform CloudLab)
Guía actualizada a la versión 7.0.0-Zelda
Introducción
El objetivo de este artículo es el de familiarizarse con Onesait Platform y su modelo de desarrollo low code.
Para seguir esta guía se va a usar Onesait Platform CloudLab, un entorno gratuito en la nube de la Plataforma, en donde desarrolladores y usuarios potenciales pueden realizar sus pruebas con una Plataforma completamente funcional.
Paso 1: registro y acceso a la Plataforma
Acceso al entorno de CloudLab y creación de un nuevo usuario
El primer paso será acceder al entorno de CloudLab. Para ello, desde un navegador web (se recomienda usar Google Chrome) se navegará a la URL de: https://lab.onesaitplatform.com
Para registrar un nuevo usuario, desde la pantalla de inicio de sesión se tendrá que pulsar en el botón de «Register»:
Se mostrará entonces una formulario en donde se tendrá que introducir los datos del usuario:
First name: para indicar el nombre del usuario
Last name: para los apellidos
Email: para indicar el correo electrónico de contacto. No se podrá reutilizar uno ya registrado.
Username: el nombre de usuario para identificarse. Deberá tener una longitud de, al menos, cuatro caracteres alfanuméricos, y no podrá tener espacios ni caracteres especiales más allá de «@», «.» o «_»
Password: deberá tener al menos diez caracteres, de los cuales al menos uno tendrá que ser una letra, otro un número y un caracter especial.
Para continuar con el registro se pulsará en el botón de «Register».
Si todo ha ido correctamente, se mostrará nuevamente la pantalla de inicio de sesión, con un mensaje en el que se indica que la información de la cuenta ha sido actualizada.
En el campo de username se mostrará el nombre de usuario previamente indicado. Introduciendo la contraseña escogida en el campo de password, se podrá iniciar la sesión pulsando en el botón de «Sign In».
Tras iniciar se sesión, se mostrará la pantalla principal de la Plataforma, el Control Panel.
Por defecto, los usuarios registrados tienen un rol de tipo «desarrollador». Para cambiar el rol del usuario, será necesario contactar con un administrador.
Se puede consultar la información sobre los roles de la Plataforma en el siguiente artículo:
Conociendo Control Panel
Control Panel es la consola web central para gestionar todos los conceptos de Onesait Platform.
Se encuentra construido con diversas capacidades que están prácticamente listas para usar, como accesibilidad, usabilidad, capacidades multilingües, etc., lo que facilita la gestión máxima de los usuarios de la Plataforma.
En el siguiente artículo se explica con detalle la funcionalidad de Control Panel:
Como resumen, en esta página se muestra la siguiente información:
Menú de acceso: localizado en el lateral izquierdo de la pantalla, el cual cuenta con todas las opciones disponibles para el usuario, así como un buscador integrado en la parte superior para localizar un módulo concreto. Cada menú se compone de submenús.
En el siguiente artículo se explica y desglosa el menú de acceso de la Plataforma y sus diferentes componentes:
Cabecera: desde donde se podrá acceder a dos menús:
Perfil de usuario: en donde se podrá cambiar el idioma, consultar los datos del usuario y sus prerefencias, así como cerrar la sesión.
Opciones: con acceso a los servicios de API REST de la Plataforma, los tokens de usuarios, así como el market de Assets y la solicitud de soporte.
Aplicaciones: localizado en el centro de la pantalla, se trata de un listado de las aplicaciones disponibles para el usuario. Un nuevo usuario no tendrá ninguna Aplicación a mostrar.
Pulsando en el interruptor de «Aplicaciones», situado en la parte superior derecha, se cambiará el modo de visualiación a «Mi universo».Mi universo: situado en el mismo lugar que las «Aplicaciones» en el centro de la pantalla, muestra todos los conceptos gestionados por la Plataforma.
Con un usuario recién registrado, sólo se tendrá una única Entidad, de nombre «Audit_
nombre de usuario», en la que la Plataforma registrará automáticamente todas las acciones del usuario:
Paso 2: crear una Entidad
Paso 3: API REST para acceder a una Entidad
Una vez creada la Entidad que representa la información que se quiere manejar en el sistema, es posible hacer diferentes procesamientos en Onesait Platform: se pueden crear visualizaciones con el Dashboard Engine, generar un cliente para acceder a esta Entidad a través del Broker de la Plataforma, o bien crear una API REST para acceder a estos datos de forma sencilla y estandarizada.
Crear una API REST
Para crear una API REST de una Entidad, se puede acceder al asistente de creación tanto desde la ventana que aparece tras crear la entidad, como desde el menú de Procesamiento > APIs.
Sin importar la forma por la que se acceda, se mostrará un listado con las APIs a las que tiene acceso el usuario, ya sean propias como compartidas por otros usuarios (las que se muestran como públicas).
Para crear la nueva API, se pulsará en el botón de «+» situado en la parte superior derecha de la pantalla.
Esto abrirá el asistente de creación de la API, en donde se tendrá que introducir una información básica:
Habrá que introducir la siguiente información:
Identificación: el nombre único con el que identificar a la API.
Versión: la versión actual de la API. Este valor es autogenerado.
Categoría: para definir la API y poder filtrarlo fácilmente a la hora de buscarlo.
Tipo de API REST: representa el tipo de API a crear. La Plataforma permite publicar una API REST a partir de una Entidad, o bien crear una API REST desde un descriptor Swagger para actuar de Proxy.
Entidad: este selector permitirá escoger una de las Entidades propias o autorizadas al usuario, sobre la que generar la API REST, si el tipo de API REST escogido es de tipo Entidad. En el desplegable se podrá filtrar por el nombre la Entidad de interés:
Meta-Información: etiquetas con las que caracterizar la Entidad, que servirán para su filtrado a la hora de hacer búsquedas.
EndPoint base: campo autogenerado con la URL de la API REST a crear.
EndPoint Swagger: la URL del Swagger de la API REST.
Descripción: texto descriptivo extendido de la API REST, como su uso, propiedades, características, etc.
Imagen: es posible cargar una imagen para caracterizar la API.
Pecitiones por segundo (QPS): es posible fijar el número de peticiones que acepta la API por segundo.
Tiempo de caché (minutos): el tiempo en minutos que mantendrá almacenada la información cacheada (más información).
Pública: si se quiere que la Entidad sea pública, o si se quiere privada.
Publicar a Gravitee: para publicar la API en el gestor de APIs de Gravitee.
Además, en la parte derecha de la pantalla se encuentra la sección de Operaciones, en donde se listan las operaciones a disponibilizar en la API:
La Plataforma permite crear automáticamente las operaciones CRUD de una API, así como hacer consultas personalizadas.
QUERY(ALL): petición GET, que recupera todos los datos de una Entidad.
QUERY(ID): petición GET, que recupera una instancia a partir del identificador único.
INSERT: petición POST, que permite inserta una nueva instancia.
UPDATE: petición PUT, que permite actualiza una instancia.
DELETE(ID): petición DELETE, que permite eliminar una instancia a partir de su identificador.
QUERY CUSTOM: petición GET, que permite crear una consulta personalizada.
Por defecto no hay ninguna disponible, por lo que habrá que pulsar en el botón de aquellas que interese habilitar. Por ejemplo, para permitir hacer una consulta a partir de un identificador, se habilitará la de «Query(ID)»:
En el campo «Descripción» se podrá introducir una pequeña descripción de la funcionalidad de la operación.
Una vez definidas las operaciones que interesan, se podrá terminar de crear la API REST pulsando en el botón de «Crear».
Tras pulsar el botón, el asistente de creación se cerrará y se volverá a la vista del listado de API REST, donde se podrá visualizar la nueva API creada, la cual aparecerá con el estado «Created».
Toda API tiene un ciclo de vida específico (más información). Esto afecta a la capacidad de otros usuarios de invorcar dicha API, por lo que debe de tener al menos el estado «Development» para ser accesible.
Para cambiar el estado de una API, en las opciones de la API se tendrá que desplegar el menú de opciones pulsando en el icono de «⋮», y seguidamente seleccionar la opción de «Desarrollo» (o «Publicar»).
Invocar la API REST
Para invocar las API de Plataforma es necesario utilizar un token de acceso. Existen dos tipos:
X-OP-APIKey: este es un token personalizado para cada usuario, el cual es más sencillo para invocar una API desde dentro de la Plataforma.
OAuth2: este token se genera automáticamente por la Plataforma dentro del ciclo de vida OAuth2. Este es el método recomendado cuando se invoca la API REST desde fuera de la Plataforma.
Para acceder al listado de tokens X-OP-APIKey de usuario, desde Control Panel se pulsará en el menú situado en la parte superior derecha de la pantalla y representado por el icono «⋮». De entre las distintas opciones, se seleccionará la de «User Tokens»:
Se mostrará entonces un listado con los tokens disponibles:
Si se quisiese generar un nuevo token, únicamente habría que pulsar en el botón de «Generar Token».
Se mostrará entonces un modal en el que introducer el identificador y descripción del token, algo útil para diferenciar para qué se usa cada token.
Para consultar el OAuth2, así como visualizar los tokens de X-OP-APIKey, desde el mismo menú de antes se seleccionará la opción de APIs:
Se mostrará entonces un modal con el token de OAuth2 y los tokens X-OP-APIKey disponibles para el usuario:
Una vez que se conoce dónde se encuentran los tokens, desde las opciones de la API REST se seleccionará la opción de «Swagger».
Las APIS de Onesait Platform se publican siguiendo el estándar Open API 3. Dentro del Control Panel se integra el UI de Swagger para poder invocar a estas APIs.
Se mostrará entonces una vista de Swagger con las operaciones disponibles para la API REST.
Lo primero que habrá que hacer es autorizar el Swagger. Para ello, se pulsará en el botón de «Authorize», lo que mostrará un modal en el que añadir el valor de X-OP-APIKey u OAuth2:
Tras introducir el tipo de token que se desee, se pulsará en el botón de «Authorize» para almacenar el token y autorizar las operaciones.
Hecho esto, únicamente habrá que escoger una de las operaciones, pulsar en el botón de «Try it out» y lanzar la operación con el botón de «Execute»:
En caso de una operación de POST/PUT, habrá que indicar un parámetro y/o un cuerpo en la operación.
Si la respuesta de la operación es correcta, se mostrará con un código 200 y un cuerpo con la información requerida:
Consultas personalizadas
Las consultas vistas hasta ahora son las genéricas. Sin embargo, es posible crear consultas personalizadas que permitan obtener información concreta.
Para ello, se editará la API desde el listado de APIs disponibles pulsando en el botón de «✎» (editar).
Para poder editar la API REST, ésta debe de estar en modo «Created» o «Development»; en caso contrario, no se podrá editar la API. En tal caso, habrá que modificar el estado a uno de los dos anteriores.
Una vez abierto el asistente de configuración, en la parte superior derecha se pulsará sobre el botón de «+ Query Custom»:
Se abrirá entonces un modal en el que preparar la consulta personalizada:
En dicha pantalla se tendrá que indicar la siguiente información:
Método: pudiendo escoger entre
PUT,POST,GETyDELETE.Nombre: el nombre del método con el que se invocará la consulta personalizada.
Consulta: la consulta para obtener la información de la Entidad.
Tipo de consulta: si la consulta se realiza en SQL o en nativo (MongoDB).
Descripción: texto descriptivo extendido del método, explicando lo que hace.
Activar procesado: activando este selector, se habilita una ventana en la que poder procesar la respuesta de la consulta usando JavaScript, en donde la variable «data» sería la respuesta de la consulta:
Parámetros en la consulta
A la hora de generar la consulta, es posible utilizar parámetros para hacer consultas dinámicas. Para ello, se introducirá el parámetro como: {$param}.
Por ejemplo, para la Entidad de «Restaurants», con la siguiente consulta se podrían obtener aquellos restaurantes cuya cocina sea de tipo americana:
SELECT c.Restaurant
FROM Restaurants AS c
WHERE c.Restaurant.cuisine = 'American'La consulta tendrá que estar definida como tipo GET.
Parametrizando el tipo de cocina, para poder indicar el tipo, la consulta quedaría así:
SELECT c.Restaurant
FROM Restaurants AS c
WHERE c.Restaurant.cuisine = {$cuisineType}Se actualizará entonces la sección de «Parámetros Query», mostrando el parámetro creado («cuisineType» en este caso) y puediendo configurar dos opciones:
Tipo: el tipo del parámetro; objeto, texto, número o fecha.
Localización: dónde se definirá el parámetro en la llamada; en el cuerpo, encabezado, parámetro de URL, etc.
Una vez incluido un parámetro, no se podrá ejecutar la consulta, por lo que para probar si todo funciona correctamente, habrá que introducir el valor de la consulta, y si funciona bien, ya cambiarlo a parámetro.
Una vez terminada de definir la consulta personalizada, se podrá guardar pulsando en el botón de «Guardar cambios».
Una vez guardados los cambios, la consulta personalizada aparecerá disponible en el listado de operaciones:
Si todo está conforme, se salvarán los cambios de la API REST pulsando en el botón de «Guardar cambios» situado en la parte superior derecha de la pantalla.
Regresando al Swagger, la nueva operación aparecerá listada:
Ejecutándola, e introduciendo como parámetro de entrada el tipo de cocina «Americana», se ejecuta correctamente la consulta:
Paso 4: Uso de la herramienta de consultas
La última herramienta que se va a ver en este tutorial es la herramienta de consultas, muy útil para conocer la información disponible en las Entidades.
Para acceder a ella hay que navegar al menú de Herramientas Dev > Herramientas de consultas.
Al acceder, se mostrará un vista en donde poder escoger qué se quiere analizar. Para ello, existen diferentes opciones:
Bases de datos: en el caso de los usuarios con roles de «analista» o «desarrollador», sólo estará disponible la Realtime DB, que es donde se almacenan las Entidades. En el caso de los usuarios con rol de tipo «administrador», además tendrán disponible la Config DB, donde se encuentran las tablas de datos de Onesait Platform.
Entidades/Tablas: en el caso de la base de datos Realtime DB, se podrá seleccionar la Entidad a la que consultar. Si se tiene acceso y se escoge la Config DB, permitirá consultar las tablas de configuración.
Mostrar sólo mis Entidades: para filtrar el listado de Entidades y mostrar únicamente las Entidades propietarias del usuario, lo que facilita la búsqueda.
Tras escoger una Entidad, se habilitarán nuevas opciones para realizar la consulta:
Tipo: lenguaje de la consulta. De partida está seleccionada la opción de
SQL, pero se puede escoger hacer las consultas en nativo (MongoDBpor defecto).Formato: el formato en el que se devolverá la respuesta. Está fijo en JSON.
Asistente para consultas: permite habilitar un asistente que ayude al usuario a generar la consulta.
En la parte inferior se muestra una ventana de código en donde se podrá introducir la consulta a realizar:
Por defecto, la consulta que sale siempre para cualquier Entidad es la la siguiente:
SELECT *
FROM nombre_entidad
LIMIT 3Esta consulta recupera datos de una Entidad. Se conforma de tres partes diferenciadas:
SELECT *: que selecciona todas las propiedades disponibles en la Entidad.FROM nombre_entidad: especifica la Entidad de donde se obtendrán los datos.LIMIT 3: restringe los resultados de la consulta a solo tres registros.
Como resultado, se recuperan las tres primeras filas completas de la Entidad especificada, mostrando todos los camposde cada registro.
Para ejecutarla, se pulsará en el botón de «Ejecutar Query»:
En la parte inferior de la pantalla, se mostrará una sección de código con la respuesta de la consulta:
