Cómo empezar a trabajar con CloudLab

En la entrada de hoy queremos enseñaros los primeros pasos para empezar a usar y trabajar con el entorno CloudLab de la Onesait Platform, la instalación Cloud de la Plataforma que disponemos pública y gratuitamente para todo el mundo en el que desarrolladores y usuarios potenciales puedan llevar a cabo sus pruebas y conocer la Plataforma.

Registro y acceso a la Plataforma

En este apartado vamos a ver cómo podemos darnos de alta en la Plataforma y acceder al Control Panel. Para ello, lo primero que tendremos que hacer es acceder a la dirección del entorno pinchando en el siguiente botón:

Una vez que accedamos, veremos una pantalla que nos pedirá que accedamos con nuestro nombre de usuario y contraseña.

En caso de no tener aun usuario, podremos darnos de alta con uno nuevo pulsando en el enlace de «Regístrate». Nos saldrá entonces un formulario de registro, en donde podremos escoger el tipo de usuario que queremos tener.

Respecto a la contraseña a utilizar, ésta debe contener al menos una letra mayúscula, una letra minúscula y un número o símbolo. Además, la longitud debe estar comprendida entre 10 y 128 caracteres. Y ya sabemos qué se dice de las contraseñas…

Bien, si el proceso de creación de usuario ha sido correcto, se nos redirigirá a la página de acceso indicando que comprobemos nuestro correo electrónico para completar el registro (normalmente no suele caer en spam, pero si no lo recibís echad un ojo por si acaso).

Accediendo al enlace que recibimos por correo electrónico, activaremos nuestra cuenta, por lo que ya podremos acceder con ella a CloudLab.

Introduciendo nuestros datos, accederemos al Control Panel de CloudLab y nos encontraremos un interfaz de usuario como este:

En esta página inicial nos vamos a encontrar:

• 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, desde donde podremos acceder a nuestro perfil, idioma, cerrar sesión, acceder a las APIs de gestión de la Plataforma o buscar en el Portal del desarrollador.

• El acceso a Mi Universo, con todos los conceptos gestionados por la Plataforma. Con el usuario recién creado, únicamente tendremos una entidad llamada «Audit_mi_nombre_de_usuario», la cual sirve para registrar todas las acciones de nuestro usuario.

Creación de una Entidad/Ontología en la Plataforma

Ya hemos accedido al entorno y nos hemos registrado correctamente. ¿Qué podemos empezar a hacer? Pues vamos a crear nuestra primera ontología.

La 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 la Plataforma estos datos o entidades es lo que denominamos como «Ontologías».

Para crear nuestra primera ontología, vamos a navegar hasta el menú de «Desarrollo», y en él navegaremos hasta el submenú de «Mis Ontologías».

Tras acceder al submenú, veremos que se nos muestra un listado con nuestras Entidades/Ontologías. Tenemos la posibilidad de visualizar también las ontologías a las que tengamos autorizaciones, o que sean públicas. Para ello, deberemos desmarcar la opción de «Mostrar sólo mis ontologías», que se encuentra situada sobre el listado.

Para crear una nueva ontología, seleccionaremos la opción de «Nuevo», situada en la parte superior derecha de la pantalla.

Una vez que pulsemos, nos aparecerá un asistente de creación de la nueva ontología con diversas opciones:

• Creación paso a paso.
• Creación desde fichero.
• Creación desde una base de datos relacional.
• Creación desde un API REST.
• Creación KPI.
• Creación desde timeseries.

En nuestro caso, escogeremos la primera opción, la de «Creación paso a paso».

En la siguiente pantalla, completaremos la información inicial necesaria para crear la ontología:

• Nombre: para dar un nombre único a la Entidad/Ontología. No podemos crear ontologías con un nombre ya existente, por lo que una opción que se usa mucho es añadir como sufijo el nombre del usuario al nombre de la ontología.
• Meta-Información: para asignar palabras clave para clasificar las ontologías.
• Activa: para marcar la entidad como Activa y poder usarla (las ontologías desactivadas no pueden ser utilizadas).
• Pública: si marcamos la entidad como pública, todos los usuarios podrán consultar sus datos (pero no modificar la entidad o insertar datos).
• Descripción: para dar una descripción que puede ayudar a identificar el objetivo de la ontología.

Así, un ejemplo de ontología podría ser:

Podremos desplazarnos por las diversas opciones a la hora de crear la Entidad. Así, si vamos a «Opciones Avanzadas», podremos ver diversas opciones, entre ellas que la Entidad/Ontología se almacene en una base de datos MongoDB gestionada por la Plataforma. De momento, no tocaremos nada por aquí.

Una vez completada la información inicial de la Entidad, seguiremos completando la información para crearla. Lo siguiente será crear esta Entidad desde una Plantilla. Esto permite reutilizar modelos de datos estandarizados (como el GSMA Data Model), de modo que una Entidad que representa un Elemento (por ejemplo un aparcamiento) siempre se modele de la misma forma.

Para este ejemplo, como queremos modelar una Entidad simple, partiremos de una plantilla vacía, denominada como «Template EmptyBase», la cual se encuentra en la pestaña «General». Esta plantilla, como por su nombre imaginamos, es una plantilla base vacía en la que vamos a poder modelar la Entidad a medida.

Para cargarla, seleccionaremos la plantilla, y en el modal que aparecerá confirmaremos que queremos cargar dicha plantilla.

Hecho esto, podremos ver que nos aparece una definición vacía. Lo siguiente que haremos será ir añadiendo las propiedades de nuestra Entidad pulsando en «Nueva propiedad»:

Para la entidad de ejemplo, vamos a crear las siguientes 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 o temperatura.
• measure (NUMBER): representa la medida en formato numérico.
• timestamp (DATE): representa la fecha y hora en la que se tomó la medida.

Una vez que hayamos terminado de añadir las propiedades, pulsaremos en el botón de «Actualizar esquema». Esto nos muestra la representación de esa Entidad en la Plataforma. La Plataforma utiliza 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 base de datos relacional, la representación sería la misma).

Desde aquí también podemos editar la estructura de nuestra ontología, si no nos convence algo que hayamos incluido u omitido.

Si pulsamos en el botón de «Generar instancia», se mostrará la estructura de una instancia de la ontología en la 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 base de datos relacional, la Plataforma la manejará así).

Un ejemplo de JSON con la estructura definida sería este:

Para terminar, guardaremos la Entidad/Ontología creada pulsando el botón de «Nuevo» situado al final de la página.

Pues con esto ya tendríamos creada nuestro ontología, representando la información que queremos manejar en el sistema. Ahora, ¿qué podemos hacer con esto que hemos creado? A continuación vamos a crear un API REST para acceder a estos datos de forma sencilla y estandarizada para poder interactuar con ella.

API REST para acceder a mi Entidad/Ontología

Para generar un API REST de la ontología tenemos dos maneras de hacerlo; el primer modo es nada más al crear la ontología, seleccionar en el modal que nos la opción de «Crear nueva API REST para esta ontología».

La otra posibilidad es, desde el menú de «Desarrollo» seleccionar el submenú de «Mis APIs».

Sea la opción que sea la que escojamos, accederemos al listado de APIs a la que tiene acceso nuestro usuario. Podremos que comprobar que aunque nuestro usuario es nuevo, tiene acceso a muchos APIs; esto se debe a que otros usuarios hicieron públicas sus APIs, por lo que podemos tener acceso a ellas.

Para crear el nuevo API, pulsaremos en el botón de «Nuevo» situado en la parte superior derecha de la pantalla.

Se abrirá el asistente de creación del API, en donde al igual que en el caso de la ontología, tendremos que introducir cierta información:

• Identificación: es el nombre del API, debe ser único en la instancia de la Plataforma.
• Tipo de API: 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.
• Ontología: si selecciono el tipo de API Ontología, aquí seleccionaremos la ontología que maneja el API.
• Descripción: proporciona una descripción del API.
• Categoría: puedo catalogar el API en una categoría, de cara a su visualización y búsqueda.
• Pública: al marcar como pública un API, ésta queda visible para el resto de usuarios que podrán usarla.
• Meta-inf: permite asignar diferentes etiquetas al API.
• Imagen: permite asignar una imagen al API.

Para este ejemplo, vamos a rellenar dichos campos con algo como esto:

En la parte inferior del formulario veremos la sección de Operaciones, que representa las operaciones que queremos habilitar en el API. La Plataforma permite crear automáticamente las operaciones CRUD de un API, además de permitir 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

Para esta guía, vamos a habilitar las opciones por defecto (hay que añadir una descripción a cada opción). En caso de que queramos crear una consulta personalizada, en esta guía podemos encontrar toda la información de cómo crearla.

Una vez que tengamos las descripciones añadidas, pulsaremos en el botón de «Nuevo», y con ello tendremos el API generado.

Directamente regresaremos al listado de APIs, donde si miramos veremos que nuestra nueva API aparece listada.

Al crear un API en la Plataforma, esta se crea en Estado «Creada», ya que las APIs tienen un ciclo de vida específico. Para que otros usuarios puedan invocar el API, el estado de la misma debe de ser al menos de «Desarrollo», algo que podemos hacer pulsando el botón correspondiente:

Invocar el API REST creada

Para invocar las API de la Plataforma se necesita un Token de acceso. La Plataforma permite la invocación mediante dos tipos de Tokens:

• Tokens personalizados: estos tokens se generan para cada usuario, y es el mecanismo más sencillo para invocar a un API.
• Tokens OAuth2: estos tokens se generan por la Plataforma a través del ciclo de vida OAuth2.

¿Y cómo conseguimos estos tokens? Podemos acceder a ellos desde la pantalla de «Mis APIs», pulsando en el botón de «Tokens usuario»:

Aquí veremos los tokens personalizados que tenemos disponibles, pudiendo eliminarlo o crear nuevos pulsando en «Generar token».

Para obtener el token OAuth2 generado en el Control Panel para el usuario, lo podemos encontrar haciendo clic en los tres puntos que se encuentran al lado del nombre de usuario, y seleccionar la opción de «APIs»:

Se nos abrirá entonces un modal en el que encontraremos nuestro token OAuth2:

Una vez tenemos los tokens, podemos volver a «Mis APIs». Allí, buscaremos el API al que queremos invocar, y seleccionamos el botón «Swagger».

Las APIs de la Plataforma se publican siguiendo el estándar Open API 3. Dentro del Control Panel, se integra el interfaz de usuario de Swagger para poder invocar a estas APIs. Así, la pantalla que nos aparece es típica de Swagger.

Como la ontología se encuentra vacía -no se ha ingestado todavía ningún dato- vamos a empezar invocando el método POST para añadir algún dato. Pulsando sobre dicho método, nos aparecerá un formulario para probarlo:

Si pulsamos sobre el botón de «Try it out», se nos habilitará el interfaz para introducir un registro en la ontología. ¿Y cómo lo podemos hacer? Si recordamos, antes hemos comentado un ejemplo de la estructura que necesitamos:

Por tanto, únicamente tenemos que transcribir el objeto en la ventana de código:

"MyMeasures_lmgracia_dev":	{ 
	"idDevice":"MyWeatherStation",
	"type":"TEMPERATURE",
	"measure":28.6,
	"timestamp":"2014-06-27T19:28:00Z"
	}
}

Por último, introduciremos el token de usuario en la casilla de X-OP-APIKey, y pulsaremos en «Execute».

Si la inserción se ha realizado correctamente, recibiremos un mensaje como el siguiente, en el que se nos indica el ID del registro:

Para facilitar el siguiente paso a realizar, vamos a realizar algunas ingestas más, para tener más datos en la ontología (con tres o cuatro es más que suficiente).

Hecho esto, vamos a probar el método GET del API, para recuperar todas las medidas que hemos ingestado. Pulsaremos en el método y, como en el caso anterior, se nos abrirá el formulario para realizar la consulta. En este caso, únicamente tendremos que introducir nuestro token de usuario en la casilla de X-OP-APIKey, y pulsar en «Execute».

Al invocar el método, obtendremos como salida el listado con todos los registros de medidas que hemos ido introduciendo en la ontología previamente:

Para cada registro, además de la medida, se incluye un objeto con el nombre «contextData». Este objeto se crea automáticamente, registrándose el usuario que hizo la inserción, la hora a la que se realizó y el módulo de origen, por indicar algunas.

El resto de métodos del API se pueden probar de la misma forma, por lo que si nos animamos a ello, es ir probando cada método, conociendo lo que cabe esperar de ellos.

Por último, también indicar que desde dentro del interfaz Swagger, también podemos obtener la petición que debemos hacer desde un curl o desde otro cliente:

Completar la API REST creada

Hasta el momento, hemos creado una API con una serie de operaciones básicas. A continuación vamos a ver cómo crear un método personalizado que nos devuelva las medidas dado un único «idDevice». Esto podemos hacerlo porque la API aun se encuentra en estado de Desarrollo.

Para hacer esto, debemos editar nuestra API. Para ello, volveremos al menú de «Mis APIs», buscaremos nuestra API en el listado, y seleccionaremos la opción de «Editar».

Accederemos nuevamente al configurador del API. Allí, iremos hasta la parte baja, donde definíamos las operaciones disponibles del API, y pulsaremos sobre el botón de «Query(Custom)».

En el asistente que nos aparecerá, introduciremos una consulta del siguiente tipo:

Select * from MyMeasures_lmgracia_dev as c where c.MyMeasures_lmgracia_dev.idDevice='MyWeatherStation'

Si pulsamos sobre el botón de «Ejecutar consulta», podremos ver que obtenemos las medidas del registro.

También tenemos la posibilidad de formatear la consulta que obtenemos, para por ejemplo no obtener la información del contextData. Para esto, modificamos la consulta a otra de este tipo:

Select c.MyMeasures_lmgracia_dev as Measure from MyMeasures_lmgracia_dev as c
where c.MyMeasures_lmgracia_dev.idDevice='MyWeatherStation'

Hecho esto, obtenemos un registro como este:

Para terminar, vamos a parametrizar esta API de modo que el parámetro del «idDevice» se pueda pasar como parámetro. Para ello, bastará con incluir el parámetro con «{$<nombre_parametro>}» e indicar el tipo de parámetro, que en nuestro caso será uno de tipo «STRING».

Hecho esto, pulsamos en «Guardar cambios», y seguidamente en la ventana de la configuración del API, pulsaremos en «Editar». Con esto, ya tendremos disponible el nuevo método del API, que podremos invocar de igual manera que los anteriores desde el Swagger.

Tras ejecutar la consulta, obtendremos algo como lo siguiente:

Usando la Herramienta de Consultas

Para acabar con esta entrada de primeros pasos con la Onesait Platform, no queremos dejar de enseñar una herramienta muy importante a la hora de desarrollar con la Plataforma. Nos referimos a la Herramienta de Consultas, la cual es accesible desde el menú de «Herramientas», en el submenú de «Herramienta Consultas».

Accederemos al siguiente interfaz, desde donde podremos seleccionar la Ontología/Entidad sobre la que queremos hacer consultas y, de una forma sencilla, poder consultar la información gestionada por la Plataforma.

La Plataforma gestiona de forma transparente los repositorios donde se almacena la información. Así, aunque nuestra Entidad se almacena en Mongo, podemos ejecutar una consulta en SQL:

---

---

Bueno, pues con esto damos finalizada esta entrada de introducción de la Onesait Platform con los primeros pasos para empezar a trabajar con ella.

Esperamos que os haya parecido interesante y, ante cualquier duda que os surja, podéis visitar nuestro Portal del Desarrollador, o dejarnos un comentario con vuestra consulta.

✍🏻 Author(s)