Primeros Pasos (con Onesait Platform CloudLab)
Introducción
El objetivo de este post es familiarizarse con Onesait Platform, con su modelo de desarrollo LowCode.
Para seguir la guía usaremos Onesait Platform CloudLab, una entorno Cloud de la plataforma gratuito donde desarrolladores y usuarios potenciales pueden realizar sus pruebas.
Paso 1: Registro y acceso a Plataforma
Acceso a Entorno CloudLab y creación de usuario
Abre en un navegador la URL del Entorno CloudLab: https://lab.onesaitplatform.com/controlpanel
En primer lugar, debes crear un usuario. Para ello, en la pantalla de login, debes seleccionar la opción Sign Up para crear un usuario introduciendo un id, contraseña, nombre, y e-mail.
Si deseas acceder a la plataforma como developer, debes seleccionar la opción Developer.
Si el proceso de creación ha sido correcto, te redirigirá a la página de login indicando que chequees tu mail para completar el registro.
Recibirás un correo como éste. Para completar el registro basta con que pinches en el link:
Tras hacerlo aparecerá:
y ya podrás acceder con tu usuario y password.
Acceso Control Panel
Una vez que accedas al Control Panel con tu usuario, te encontrarás con una UI como ésta:
La página principal muestra:
Un menú de opciones en el lateral izquierdo de la pantalla con todas las opciones para el usuario. Este menú está organizado en submenús.
Una cabecera donde puedes acceder a tu perfil, idioma, hacer logout y además acceder a las APIs de gestión de plataforma o buscar en el Portal del desarrollador.
El acceso a My Environment, con todos los conceptos gestionados por plataforma. Al acabar de crear el usuario, sólo tendrás una entidad Audit_<nombreusuario> en la que la plataforma automáticamente registra todas las acciones del usuario:
Paso 2: Crear Entidad/Ontología en Plataforma
Onesait Platform es una plataforma Data Centric, donde los datos son el activo principal y permanente, mientras que las aplicaciones van y vienen. En estas arquitecturas el modelo de datos precede a la implementación de cualquier aplicación dada y será válido mucho después de que se reemplacen. En Plataforma estos datos o entidades se denominan Ontologías.
El primer paso para desarrollar sobre plataforma una será modelar la Entidad (Ontología). Para hacer esto, selecciona la opción del menú DEVELOPMENT>My Ontologies.
Tras esto se mostrará un listado con tus Entidades/Ontologías (si quieres visualizar las ontologías a las que tengas autorizaciones o sean públicas deberás desmarcar la opción Show only my ontologies situado sobre el listado).
Para crear una nueva ontología, selecciona la opción Create, situada en la parte superior derecha.
A continuación nos aparecerá una UI con diversas opciones, donde seleccionarás Creation Step by Step:
En la siguiente pantalla, completa la información inicial necesaria para crear la Ontología:
esto es:
Name: para dar un nombre único a la Entidad/Ontología. No puedes crear ontologías con un nombre ya existente (así que puedes poner como sufijo el nombre de usuario para el ejemplo)
Meta-Information: para asignar palabras clave para clasificar las ontologías.
Active: para marcar la entidad como Activa y poder usarla (las ontologías desactivadas no pueden ser utilizadas).
Public: si marcas la entidad como pública, todos los usuarios podrán consultar sus datos (pero no modificar la entidad o insertar datos).
Description: para dar una descripción que puede ayudar a identificar el objetivo de la ontología.
Para este ejemplo, crea la Ontología con estos datos:
Puedes moverte por las opciones a la hora de crear la Entidad. Si vas a ADVANCED SETTINGS, puedres ver diversas opciones, entre ellas que la Entidad/Ontología se almacenará en una base de datos MONGO gestionada por plataforma. No toques nada por el momento.
Una vez completada la información inicial de la Entidad, sigue completando la información para crearla. Lo siguiente es crear esta Entidad desde una Plantilla. Esto permite reusar Data Models estandarizados (como el GSMA Data Model) de modo que una Entidad que representa un Elemento (por ejemplo un Parking) siempre se modele de la misma forma.
En este caso, como quieres modelar una Entidad simple, parte del Template EmptyBase que se encuentra en la pestaña GENERAL y que es una plantilla base vacía para modelar la Entidad a medida. Si pinchas dos veces sobre el elemento, aparecerá un desplegable para CONFIRMAR que quieres usar ese template o Data Model.
Puedes ver que me aparece una definición vacía, lo siguiente será ir añadiendo las propiedades de tu Entidad:
Para el ejemplo modela tu Entidad/Ontología con tres propiedades:
idDevice (STRING): representa el identificador del dispositivo para el que se toma la medida.
type (STRING): representa el tipo de medida, por ejemplo HUMEDAD, TEMPERATURA.
measure (NUMBER): representa la medida en formato numérico.
timestamp (DATE): representa la fecha y hora en la que se tomó la medida.
Cuando hayas terminado de añadir las propiedades, pulsa la opción UPDATE SCHEMA. Esto muestra la representación de esa Entidad en Plataforma. La Plataforma usa JSON-Schema para representar la estructura de las entidades, de forma independiente a donde se estén persistiendo (por ejemplo aunque esta Entidad/Ontología estuviese almacenada en una BD relacional la representación sería la misma):
Puedes editar la estructura de tu Entidad también desde aquí.
Si pulsas el botón GENERATE INSTANCE, se muestra la estructura de una instancia de la Ontología en plataforma. Igual que se usa JSON-Schema para representar estas Entidades/Ontologías se usa JSON para representar las instancias de cada Entidad/Ontología, de forma independiente a la persistencia que haya detrás (de nuevo, aunque por debajo la ontología se almacene en una BD relacional, la plataforma la manejará así)
Un ejemplo de JSON con la estructura definida sería esta:
Para finalizar, guarda la Entidad/Ontología creada pulsando el botón NEW situado al final de la página.
Paso 3: API REST para acceder a tu Entidad/Ontología
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: