Primeros Pasos (con Onesait Platform CloudLab)
- DevPortal Editor (Unlicensed)
- Onesait Platform
Introducción
El objetivo de este artículo es familiarizarse con Onesait Platform y su modelo de desarrollo low code.
Para seguir la guía usaremos Onesait Platform CloudLab, un entorno Cloud de la Plataforma gratuito, 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 CloudLab y creación del usuario
En primer lugar, desde un navegador iremos hasta la URL del entorno de CloudLab, que es: https://lab.onesaitplatform.com
Como aún no tenemos ningún usuario, lo primero que haremos será crearnos uno nuevo. Para ello, en la pantalla de iniciar sesión, tendremos que pulsar en el botón de «Register»:
Aparecerá entonces una formulario en donde tendremos que introducir nuestros datos: nombre, apellidos, correo electrónico, nombre de usuario y contraseña que vamos a querer utilizar (tendremos que confirmarla):
Una vez registrados, volveremos a la pantalla de inicio donde tendremos que introducir nuestro nombre de usuario y contraseña:
Acceso al Control Panel
Una vez que accedamos al Control Panel con nuestro usuario, nos encontraremos con una interfaz como esta:
La página principal muestra:
Un menú de opciones en el lateral izquierdo de la pantalla, con todas las opciones disponibles para nuestro usuario así como un buscador integrado. Este menú está organizado en submenús.
Una cabecera: en donde vamos a poder acceder a nuestro perfil, cambiar el idioma del interfaz, cerrar la sesión o acceder a las APIs de gestión de la Plataforma y otras opciones disponibles.
En el centro de la pantalla tenemos la sección de My Environment, con todos los conceptos gestionados por la Plataforma. Al acabar de crear el usuario, sólo tendremos una Entidad, de nombre «Audit_nombreusuario», 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
Crear API REST
Una vez creada la Entidad/Ontología que representa la información que quieres manejar en el sistema, puedes hacer diferentes procesamientos en plataforma: puedes crear visualizaciones con el Dashboard Engine, crear un Cliente para acceder a esta Entidad a través del Broker de Plataforma, o bien crear un API REST para acceder a estos datos de forma sencilla y estandarizada.
Para hacerlo, puedes ir a la opción Create New REST API for this Ontology que aparece al crear una Entidad o bien desde la opción de menú correspondiente DEVELOPMENT> My APIs.
Al seleccionar esta opción, ve al Listado de APIS a las que tiene acceso tu usuario. Como puedes ver, tienes acceso a un buen número de APIs. Esto es porque los usuarios que las crearon las marcaron como PUBLIC y por tanto están accesibles al resto de usuarios de la instancia:
En este caso, quieres crear una nueva API, así que seleccionarás el botón CREATE.
Esto te lleva a un interfaz como éste:
Para crear un API, completa esta información:
Identification: es el nombre del API, debe ser único en la instancia de plataforma.
API type: representa el tipo de API. La plataforma permite publicar un API REST a partir de una Ontología/Entidad o bien crear un API REST desde un descriptor Swagger para actuar de Proxy.
Ontology: si selecciono el tipo de API Ontology, aquí seleccionaré la ontología que maneja el API.
Description: proporciona una descripción el API.
Category: puedo catalogar el API en una categoría, cara a su visualización y búsqueda.
Public: al marcar como pública un API esta queda visible para el resto de usuarios que podrán usarla.
Meta-inf: permite asignar diferentes tags al API.
Image: permite asignar una imagen al API.
En este caso, seleccionado esta información para el API:
Si continuas con la UI, verás la sección de Operations, que representa las operaciones que quieres disponibilizar en el API.
La plataforma permite crear automáticamente las operaciones CRUD de un API: INSERT, UPDATE, DELETE, QUERY BY, QUERY ALL, además permite hacer consultas personalizadas.
QUERY(ALL): Petición GET, recupera todos los datos de una ontología/entidad.
QUERY(ID): Petición GET, recuperar una instancia a partir del id.
INSERT: Petición POST, permite insertar una nueva instancia.
UPDATE: Petición PUT ,permite actualizar una instancia.
DELETE(ID): Petición DELETE, permite eliminar una instancia a partir de su id.
QUERY CUSTOM: Petición GET, permite crear una query personalizada.
En este caso, habilita las opciones por defecto (para ver cómo crear una QUERY CUSTOM puedes consultar esta guía https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/2043871259 ).
Y selecciona NEW.
En la UI de Listado de Mis APIs, verás la nueva API creada:
Al crear un API en Plataforma, ésta se crea en Estado CREATED. Las APIs tienen un ciclo de vida específico (ver https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/2046296087 ). Para que otros usuarios puedan invocar el API a menos debe estar en estado DEVELOPMENT; para eso, basta con pulsar el botón correspondiente:
Invocar el API REST creada
Para invocar las API de Plataforma se necesita un Token de acceso. La plataforma permite la invocación con dos tipos de Tokens:
Tokens Custom: estos Tokens se generan para cada usuario, es el mecanismo más sencillo para invocar a un API.
Tokens OAuth2: estos tokens se generan por plataforma a través del ciclo de vida OAuth2.
Puedes acceder a tus Tokens desde la UI de My APIs que se encuentra en la sección USER TOKENS:
Desde ahí verás un Token. También puedes eliminar ese Token o generar varios:
NOTA: El Token OAuth2 generado en el Control Panel para el usuario puede encontrarse pinchando en los tres puntos y luego en la sección APIs:
Una vez tienes los tokens, vuelve a My APIs y al API que quieres invocar y selecciona el botón SWAGGER.
Las APIS de Plataforma 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.
Tras esto, verás una UI como ésta:
Ahora mismo no tienes medidas registradas, así que empieza por insertar una invocando el POST / para el create. Al selecionarlo, aparecerá esto:
Si pinchas el botón Try it out, se habilitará el UI para introducir una medida. Como viste al crear la Entidad, una entrada tenía este aspecto:
"MyMeasures_lmgracia_dev": {
"idDevice":"MyWeatherStation",
"type":"TEMPERATURE",
"measure":28.6,
"timestamp":"2014-06-27T19:28:00Z"
}
}Completando el User Token, el registro a insertar y pulsando EXECUTE:
obtendrás una salida como esta, en la que se indica el ID del registro insertado:
Inserta unas cuantas medidas más desde esta misma UI.
Tras esto, prueba el método del API que te permite recuperar todas las medidas, el GET /
Al invocarlo, obtendrás como salida el listado con todas las medidas:
Puedes ver que para cada medida además del registro de medida se obtiene una sección denominada contextData. Esta sección se completa automáticamente indicando en ella el usuario que hizo la insercción y la hora en la que se hizo además del módulo origen.
El resto de métodos del API se pueden probar de la misma forma.
Dentro del interfaz Swagger también obtienes la petición que debes hacer desde un curl o desde otro cliente:
Completar el API REST creada
Hasta ahora tenías un API con las operaciones básicas. Como tienes el API en estado DEVELOPMENT, aún puedes modificarla. Ahora crearás un método que devuelva las medidas de un único idDevice.
Para eso, desde My APIs, selecciona EDIT sobre tu API:
En la siguiente UI, navega hasta el final y pincha en QUERY(CUSTOM).
Empezaré por poner una query de este tipo (Select * from MyMeasures_lmgracia_dev as c where c.MyMeasures_lmgracia_dev.idDevice='MyWeatherStation')
Si pinchas sobre el botón EXECUTE QUERY, puedes ver que obtienes estas medidas:
También puedes formatear la query que obtienes para, por ejemplo, no obtener la info del ContextData. Para esto, cambia la query a esta:
Select c.MyMeasures_lmgracia_dev as Measure from MyMeasures_lmgracia_dev as c
where c.MyMeasures_lmgracia_dev.idDevice='MyWeatherStation'y con esto obtengo un registro de este tipo:
Para acabar, hazparametrizable este API de modo que el parámetro del idDevice se pueda pasar como parámetro. Para eso basta con incluir el parámetro con {$<nombre_parametro>} e indicar el tipo de parámetro; en nuestro caso es un STRING.
Si pinchas la opción SAVE CHANGES y luego EDIT en el API, ya tendrás un nuevo método en tu API que puedes invocar como antes:
y obtendrás:
Paso 4: Uso del Query Tool
Para acabar con este tutorial, accede a una herramienta muy importante en el desarrollo con Plataforma. Ésta es el QUERY TOOL, accesible desde la opción de menú TOOLS>Query Tool:
Al acceder verás un UI como este:
donde puedes seleccionar la Ontología/Entidad sobre la que quieres hacer consultas y de una forma sencilla poder consultar la información gestionada por plataforma.
La plataforma gestiona de forma transparente los repositorios donde realmente se almacena la información, por ejemplo tu Entidad se almacena en Mongo y sin embargo puedes consultarla en SQL: