Este artículo ofrece una introducción a UbiFunctions, cubriendo sus características clave, interfaz de usuario y uso básico para ayudarte a comenzar a mejorar tu experiencia con Ubidots.

Requisitos

Una cuenta de Ubidots con plan Industrial (o superior).
Se requiere un plan Enterprise para usar Propiedades Globales en UbiFunctions.

1. ¿Qué es una UbiFunction?

Una UbiFunction es un conjunto de funciones definidas por el usuario que se agrupan y ejecutan lógica específica bajo demanda. Puede ser activada de dos maneras principales:

Solicitud HTTP: Haciendo una solicitud HTTP GET o POST a la URL de la UbiFunction.
Ejecución Programada: Basada en un intervalo de repetición predefinido.

Una UbiFunction está estructurada de la siguiente manera:

Módulos: Estos son los bloques de construcción que tu función utiliza. Contienen código y funcionalidad reutilizables.
Punto de entrada: Esta es la función principal que sirve como punto de partida para ejecutar tu lógica de negocio. En el contexto de UbiFunctions, este punto de entrada se llama main.

2. ¿Cuándo usar UbiFunctions?

Puedes usar UbiFunctions para extender las capacidades de Ubidots con tu lógica personalizada. La mayoría de los casos de uso se agrupan en las siguientes tres categorías:

Extracción de datos de APIs de terceros
Personalización de tu propio gateway API HTTP
Transformación y análisis de datos de sensores

2.1. Extracción de datos de APIs de terceros

La mayoría de las aplicaciones web tienen una API y en la mayoría de los casos, podrás acceder a tus datos programáticamente sin mucha dificultad.

Puedes usar UbiFunctions para encender o apagar un clúster de Bitcoin basado en la relación entre el precio de Bitcoin/energía o analizar la relación entre los precios de las materias primas y las condiciones climáticas.

Ejemplo de extracción de datos meteorológicos:

Dispositivos AmbientWeather → Nube AmbientWeather → Ubidots (ver ejemplo)

2.2. Personalización de tu propio gateway API HTTP

En casos donde la comunicación HTTP con Ubidots es problemática o cambiar métodos HTTP, cargas útiles o URLs es difícil, UbiFunctions te permite crear APIs HTTP personalizadas para ingerir y transformar datos para ajustarse a los formatos esperados por Ubidots.

Dispositivos LoRaWAN --> Plataforma machineQ --> Ubidots (muéstrame cómo)
Dispositivos LoRaWAN --> The Things Network --> Ubidots (muéstrame cómo)

Dispositivos Sigfox -->Sigfox Cloud --> Ubidots (muéstrame cómo)

2.3. Transformación y análisis de datos de sensores

Con UbiFunctions, tienes acceso a muchas bibliotecas de Python y Node.js para la transformación y análisis de datos.

Aquí algunos posibles casos de uso para la transformación y análisis de datos:

Asignar una ubicación GPS a tus dispositivos, basado en los routers Wi-Fi vecinos o IDs de torres de celular. Ver un ejemplo.
Evaluar la probabilidad de un accidente en el piso de producción, basado en las propiedades de un trabajador (es decir, ciudad, proceso de producción, turno) y las variables de una máquina (es decir, velocidad, temperatura, presión, vibración).

3. Entendiendo el módulo de la función

3.1. Tabla de UbiFunctions

Accede al módulo de UbiFunctions desde "dispositivos" → "funciones":

Una vez que la página se carga, verás una tabla con todas tus funciones creadas previamente (en caso de que hayas creado algunas, claro) y el botón para crear una nueva:

La tabla de funciones tiene las siguientes características:

Una barra de búsqueda para encontrar funciones específicas basadas en su nombre.
El nombre de tus funciones.
La fecha en la que se crearon las funciones.
La URL de las funciones.
Un botón (representado con tres puntos) al lado de cada función con las siguientes opciones:
- Registros: Información detallada sobre las ejecuciones de tu función. Los registros se explican a continuación en esta guía.
- Editar: Las funciones pueden ser modificadas usando esta opción.
- Deshabilitar: Usado en caso de que necesites apagar temporalmente tu función, pero desees mantenerla para uso posterior.
- Eliminar: Usado para eliminar permanentemente tu función.

Al hacer clic en los botones “+” o de editar, accederás a la función y su configuración. Cada función se divide en tres pestañas principales que se explican a continuación.

3.2. Vista principal de UbiFunction

Las funciones tienen 3 pestañas o secciones:

Editor de código
Configuraciones de la función
Registros de la función

3.2.1. Editor de código

El editor de código tiene las siguientes características:

Método HTTP menú desplegable: Úsalo para hacer solicitudes GET o POST. Esta opción también se encuentra en la configuración de la función.
URL de la función: Siempre disponible para ser copiada fácilmente.
Guardar & Ejecutar Prueba botón: Prueba tu función con un JSON de prueba.
Guardar & Desplegar botón: Una vez que tu función esté lista, guarda tus últimos cambios y despliega la función.
Botón de modo oscuro: Cambia el color de fondo del editor de código entre modo claro y oscuro.
Botón de visibilidad de archivos: Expande o colapsa el panel de archivos.
Tiempo de ejecución: Elige entre las opciones disponibles de Python o Node. Esta opción también se encuentra en la configuración de la función.
Área del editor de código: Aquí es donde escribes el código.
Panel de archivos: Si está habilitado, los archivos y carpetas de la UbiFunction se mostrarán aquí. Al hacer clic en el icono "+", podrás crear un nuevo archivo o una carpeta. Además, usando el botón de 3 puntos, puedes renombrar y eliminar archivos o agregar archivos o carpetas (dentro de una carpeta).

3.2.2 Configuraciones de la función

Las siguientes son las configuraciones disponibles para definir cómo funciona una función:

Nombre: El identificador de tu función. Ten en cuenta que este nombre se convertirá más tarde en parte de la URL de la función. La URL no se puede cambiar más tarde, incluso si se modifica el nombre de la función.
Tiempo de ejecución: La versión de Python o Node que elijas para ejecutar tu función definirá, en gran medida, lo que tu función podrá hacer. Consulta los tiempos de ejecución disponibles y las bibliotecas que son compatibles para cada uno de ellos en esta guía.
Método HTTP: Se puede elegir GET o POST como método. Un método GET se utiliza para solicitar datos de un recurso específico, mientras que POST se utiliza para enviar datos a un servidor para crear/actualizar un recurso.
URL de endpoint HTTPS: Aquí va la URL de la plataforma de terceros a la que harás las solicitudes.
Host MQTT: Envía datos a esta función usando MQTT
Nombre de usuario MQTT: Logra la autenticación MQTT usando el nombre de usuario mostrado en este campo y uno de tus tokens como contraseña.
Tema MQTT: Las cargas útiles recibidas en este tema serán reenviadas a esta función
Token: Puedes usar el menú desplegable para seleccionar el token que autentificará tus solicitudes. Puedes llamarlo en el código de tu función usando la clave del token; esto te ahorra tener que copiar y pegar tokens de API directamente en el código.
Variables de entorno: Selecciona cualquier número de variables de entorno que hayas creado previamente a través del módulo de Propiedades Globales. Con estas propiedades, puedes almacenar fácilmente variables globales para acelerar el desarrollo y mantener los recursos organizados. Sigue la guía de Propiedades Globales para aprender a usarlas.
Tiempo máximo de ejecución: Si una función no se ejecuta dentro de este tiempo, se termina y se genera una respuesta 502. Por defecto, este tiempo es de 10 segundos y puede aumentarse dependiendo de tu plan, de la siguiente manera:
- Emprendedor: Hasta 30 segundos.
- Profesional: Hasta 30 segundos.
- Industrial: Hasta 60 segundos.
- Todos los niveles Enterprise: Hasta 60 segundos.
Disparador basado en tiempo: Si necesitas que tu función se ejecute en intervalos de tiempo periódicos, define un disparador basado en tiempo, expresado en minutos. El valor mínimo es 1 y el máximo es 60.
- Expresión de crontab: Especifica, basado en la fecha/hora, la frecuencia con la que se ejecutarán las funciones.
Función en bruto: Usa funciones en bruto para lograr un nivel avanzado de personalización. Las funciones en bruto te permiten:
- Usar una ruta de endpoint personalizada.
- Recibir y responder encabezados personalizados.
- Establecer códigos de respuesta personalizados.
- Recibir y responder encabezados de tipo de contenido personalizados para el cuerpo de la solicitud y la respuesta.
- Recibir cualquier tipo de estructura de datos (objeto, cadena, matriz, imágenes, etc.). Ten en cuenta, sin embargo, que se analizará como una cadena. Las funciones normales (aquellas que no usan en bruto) solo pueden recibir JSON en sus cuerpos.

Política CORS: Usada para habilitar que la función sea llamada desde URLs de navegadores web diferentes a parse.ubidots.com.

Notas:

Las funciones pueden tener "tiempos máximos de ejecución" superiores a 60 segundos si se acuerda entre el usuario y Ubidots. Sin embargo, si una de estas "funciones especiales" tarda más de 60 segundos en ejecutarse (incluso con su mayor “tiempo máximo de ejecución”), se convierte en asíncrona. Esto significa que la función se ejecutará, pero Ubidots no esperará su respuesta; la respuesta de una función asíncrona estará disponible en sus registros.
Si necesitas tiempos de ejecución más altos, contáctanos en sales@ubidots.com

3.2.3 Registros de la función

La página de registros está dividida en dos secciones, el panel izquierdo y el área de contenido. En ellas, encontrarás la siguiente información.

Lista de registros: Ubicada en el panel izquierdo, encontrarás la lista de registros de todas las ejecuciones de tu función. Cada elemento de la lista contiene la fecha y hora de la ejecución, el ID de la ejecución y el tiempo de ejecución de la función. Cada elemento de la lista se puede hacer clic para acceder a más información.
Resultados: Ubicados en el área de contenido, los resultados de la declaración de retorno de la función se mostrarán en este campo. Si tu función no tiene una declaración de retorno, se mostrará un mensaje de “null”.
Salida: Ubicada debajo del campo de resultados, lo que tu función imprima se mostrará aquí. Además, los mensajes del servidor también se mostrarán aquí cuando ocurra un error en el lado del servidor o la función se agote.

4. Detalles Técnicos

4.1. Tiempos de ejecución

UbiFunctions soporta NodeJS LTS o Python3. Esto significa que puedes usar JavaScript (Node.js) o Python, pero no ambos simultáneamente.

4.2. Argumentos de la función

El script main de la UbiFunction recibe los argumentos como un diccionario etiquetado como "args", al que puedes acceder en tu código para ejecutar la lógica deseada.

4.3. Modularidad del código

Como se mencionó anteriormente, UbiFunctions te permite usar múltiples archivos:

Archivos fuente: Estos archivos contienen código que puede ser ejecutado.
Archivos de configuración: Estos son típicamente archivos JSON o .conf cuyo contenido no es código ejecutable, sino datos y parámetros requeridos por tu lógica.
Archivos de datos: Por ejemplo, un archivo .CSV.

4.4. Retorno de UbiFunction

Una UbiFunction debe siempre retornar un diccionario, no se permite retornar una sola variable:

Retorno de la función	Permitido
`return {"message": "OK"}`	Sí
`return "ok"`	No

4.5. Punto de entrada de UbiFunction

Cada UbiFunction debe definir un script llamado main (independientemente del tiempo de ejecución, aunque conservando la extensión adecuada) que actuará como un punto de entrada para la lógica general. Este script debe hacer uso de todos los módulos, utilidades y archivos de configuración definidos en la UbiFunction para ejecutar la lógica requerida.

4.6. Bibliotecas soportadas

Para saber qué bibliotecas son actualmente soportadas por UbiFunctions, consulta este artículo UbiFunctions & Plugins: Bibliotecas soportadas.

5. Más casos de uso

5.1. Extracción de Datos

Con UbiFunctions, puedes ejecutar ejecuciones de código periódicas para consultar APIs de terceros para la extracción de datos. Cada ejecución puede ser programada para ejecutarse cada "x" cantidad de minutos, eliminando la necesidad de configurar y mantener un script cron en un servidor virtual o Raspberry Pi.

Para programar una función de extracción de datos, simplemente selecciona la opción "Ejecutar cada" en el lado izquierdo de la pantalla

5.2. Análisis de Datos

El análisis de datos se refiere al proceso de descomponer un bloque de datos en partes más pequeñas siguiendo un conjunto de reglas, para que pueda ser insertado en Ubidots en sus paquetes JSON esperados usando HTTP.

Con UbiFunctions, puedes crear tu propio endpoint API para ingerir datos IoT de dispositivos o servicios web externos. Aquí hay una lista de escenarios comunes:

Dispositivos Sigfox → Sigfox Cloud → Ubidots
Dispositivos Particle → Particle Cloud → Ubidots
Dispositivos mcThings → mcCloud → Ubidots
Dispositivos LoRaWAN → The Things Network → Ubidots
Dispositivos LoRaWAN → LoRaWAN Network Server → Ubidots
Dispositivos NB-IoT → T-Mobile Cloud → Ubidots

Mientras que la mayoría de las plataformas anteriores son lo suficientemente flexibles como para configurar webhooks HTTPS o callbacks en el formato JSON esperado por Ubidots API, puede haber instancias donde se requiera procesamiento adicional, y diseñamos UbiFunctions precisamente para estas instancias.

Los analizadores se programan más comúnmente usando Node.js. El siguiente diagrama muestra un escenario común donde los dispositivos IoT envían datos a una nube específica del fabricante, que luego se reenvían a un analizador usando HTTP:

5.3. Ciencia de Datos

Además de Node.js, UbiFunctions también se puede programar en Python. Con el soporte de Python 3, UbiFunctions te permite ejecutar métodos de estadísticas y aprendizaje automático para analizar tus datos e insertar métricas clave de salida en Ubidots.

Nuestro tiempo de ejecución de Python incluye las bibliotecas de ciencia de datos más populares:

NumPy
Pandas
SciKit-Learn

Estas bibliotecas te proporcionan los tipos de datos (vectores, matrices y marcos de datos) y herramientas para organizar y entender tus datos.

6. Facturación de UbiFunctions

UbiFunctions están incluidas en planes Industriales y superiores.

Las ejecuciones se agotan después de 30 o 60 segundos, según tu plan. Si deseas extender este tiempo, por favor contacta a nuestro equipo de soporte.
Si alguna ejecución supera los 2 segundos; se cuenta como 2 ejecuciones (o más, según la duración de la ejecución)
Las ejecuciones se facturan en incrementos de $5 por millón de ejecuciones.