En esta guía se va a utilizar Onesait Platform CloudLab, una instalación cloud gratuita de la plataforma 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

Abriré 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, se debe seleccionar la opción Sign Up para crear un usuario introduciendo un id, contraseña, nombre, y e-mail.

Si se desea acceder a la plataforma como developer se debe 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 este, 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 acceda al Control Panel con mi usuario me encontraré con una UI como esta:

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é 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 seleccionaremos 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 seleccionaremos la opción Create, situada en la parte superior derecha.

A continuación nos aparecerá una UI con diversas opciones, donde seleccionaré Creation Step by Step:

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

esto es:

• Name: para dar un nombre único a la Entidad/Ontología. No puedo crear ontologías con un nombre ya existente (así que puedo 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 marcamos la entidad como pública todos los usuarios podrán consultar sus datos (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 mi ejemplo crearé la Ontología con estos datos:

Puedo moverme por las opciones a la hora de crear la Entidad, si voy a ADVANCED SETTING puedo ver diversas opciones, entre ellas que la Entidad/Ontología se almacenará en una base de datos MONGO gestionada por plataforma. No tocaré nada por el momento.

Una vez completada la información inicial de la Entidad seguiré 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 quiero modelar una Entidad simple partiré 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 pincho 2 veces sobre el elemento me aparecerá un desplegable para CONFIRMAR que quiero usar ese template o Data Model.

Puedo ver que me aparece una definición vacía, lo siguiente será ir añadiendo las propiedades de mi Entidad:

Para el ejemplo modelaré mi Entidad/Ontología con 3 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 hayamos terminado de añadir las propiedades, pulsaremos la opción UPDATE SCHEMA. Esto me muestra la representación de esa Entidad en Plataforma. 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):

Puedo editar la estructura de mi Entidad también desde aquí.

Si pulso el botón GENERATE INSTANCE se muestra la estructura de una instancia de 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, plataforma la manejará así)

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

Para finalizar guardaré la Entidad/Ontología creada pulsando el botón NEW situado al final de la página.

Paso 3: API REST para acceder a mi Entidad/Ontología

Crear API REST

Una vez creada la Entidad/Ontología que representa la información que quiero manejar en el sistema puedo hacer diferentes procesamientos en plataforma, puedo 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 puedo 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 iré al Listado de APIS a las que tiene acceso mi usuario, como podemos ver tengo accesible 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 nuestro caso queremos crear una nueva API, así que seleccionaré el botón CREATE.

Esto me lleva a un interfaz como este:

Para crear un API completaré 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 nuestro caso hemos seleccionado esta info para el API:

Si continuamos con la UI veremos la sección de Operations, que representa las operaciones que quiero 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 nuestro caso habilitaremos las opciones por defecto (para ver cómo crear una QUERY CUSTOM puedes consultar esta guía /wiki/spaces/PT/pages/2043871259

Y seleccionamos NEW.

En la UI de Listado de Mis APIs veré la nueva API creada:

Al crear un API en Plataforma, esta se crea en Estado CREATED. Las APIs tienen un ciclo de vida específico (ver /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 2 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.

Puedo acceder a mi Token desde la UI de My APIs que se encuentra en la sección USER TOKENS:

Desde ahí veré un Token, también puede eliminar ese Token o generar varios:

NOTA: El Token OAuth2 generado en el Control Panel para el usuario puede encontrarse pinchando en los 3 puntos y luego en la sección APIs:

Una vez tenemos los tokens, volvemos a My APIs y al API que queremos invocar y seleccionamos el botón SWAGGER.

Tras esto veremos una UI como esta:

Ahora mismo no tengo medidas registradas, así que empezaré por insertar una invocado el POST / para el create. Al selecionarlo me aparecerá esto:

Si pincho el botón Try it out se me habilitará el UI para introducir una medida. Como vimos 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é una salida como esta, en la que se indica el ID del registro insertado:

Insertaré unas cuantas medidas más desde esta misma UI.

Tras esto probaré el método del API que me permite recuperar todas las medidas, el GET /

Al invocarlo obtendré como salida el listado con todas las medidas:

Puede verse que para cada medida además del registro de medida se obtiene una sección denominada contextData. Esta sección la complet 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 obtengo la petición que debo hacer desde un curl o desde otro cliente:

Completar el API REST creada

Hasta ahora tenemos un API con las operaciones básicas, como tenemos el API en estado DEVELOPMENT aún puedo modificarla, ahora crearé un método que me devuelva las medidas de un único idDevice.

Para eso desde My APIs seleccionaré EDIT sobre mi API:

en la siguiente UI navegaré hasta el final y pincharé 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 pincho sobre el botón EXECUTE QUERY puedo ver que obtengo estas medidas:

También puedo formatear la query que obtengo para por ejemplo no obtener la info del ContextData. Para esto cambio 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 esta tipo:

Para acabar haré parametrizable 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 pincho la opción SAVE CHANGES y luego EDIT en el API ya tendré un nuevo método en mi API que puedo invocar como antes:

y obtendré:

Paso 4: Uso del Query Tool

Para acabar con este Getting Started accederemos a una herramienta muy importante en el desarrollo con Plataforma, esta es el QUERY TOOL, accesible desde la opción de menú TOOLS>Query Tool:

Al acceder veré un UI como este:

donde puedo seleccionar la Ontología/Entidad sobre la que quiero 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 nuestra Entidad se almacena en Mongo y sin embargo puedo consultarla en SQL: