NOTA IMPORTANTE: ‘Funciones raw’ es una opción avanzada para usuarios con más experiencia usando el módulo de UbiFunctions.
1. Introducción
Por defecto, UbiFunctions no admite rutas personalizadas, configurar el código de respuesta o recibir/enviar encabezados personalizados. Pero, ¿qué pasa si tu aplicación necesita ese nivel de personalización?
Las UbiFunctions raw ofrecen un nivel avanzado de personalización para usuarios experimentados. Esta guía te guiará a través del uso de estas funciones para personalizar rutas de endpoints, encabezados y códigos de respuesta.
2. ¿Qué son las funciones raw?
Las funciones raw te permiten:
Usar una ruta de endpoint personalizada además de la nativa de UbiFunction. Esto permite ejecutar diferentes rutinas según la ruta del endpoint.
Recibir y responder con encabezados personalizados. Por ejemplo, encabezados de autorización.
Configurar códigos de respuesta personalizados 20X, 40X, 50X, más allá del estándar 200 en UbiFunctions. Esto permite que el cliente HTTP sepa el resultado exacto de la ejecución.
Recibir y responder con encabezados Content-Type personalizados para el cuerpo de la solicitud y la respuesta: application/json, plain/text, etc.
3. Habilitar funciones raw
Para habilitar ‘funciones raw’, simplemente activa la opción en el panel izquierdo de la UbiFunction.
4. Entendiendo la estructura de argumentos en funciones raw
Una vez activado, el argumento “args“ recibido en la función principal de la UbiFunction seguirá la siguiente estructura:
{
"path" : "/prv/<YOUR_USERNAME>/<FUNCTION_NAME>/<YOUR_PATH>",
"headers":{
"Content-Type":"plain/text"
},
"body":"A2BF0D"
}
Donde:
Clave | Valor/Tipo | Ejemplo |
Path | String representando la ruta raw de UbiFunction. Por defecto es:
/prv/<YOUR_USERNAME>/<FUNCTION_NAME> | /prv/john-doe/get-measurements/temperature
|
Headers | Diccionario con todos los encabezados en la solicitud que activó la función. | {"Content-Type":"plain/text", "X-Auth-Token":"BBFF-XXYYZZ"}
|
Body | Contiene el cuerpo con el que se emitió la solicitud, analizado como una cadena. | "A2BF0D" |
5. Ruta de la UbiFunction Raw
Al momento de realizar la solicitud a la UbiFunction, su estructura básica de URL debe permanecer intacta, de lo contrario, la solicitud apuntará a una UbiFunction diferente.
Por ejemplo, supongamos que tienes la siguiente URL de UbiFunction: https://parse.ubidots.com/prv/iot-expo/raw-function/API/Login
Aquí, 'https://parse.ubidots.com/prv/iot-expo/raw-function' es la URL típica de UbiFunction.
La parte '
/API/Login' es la ruta personalizada que podrás acceder y analizar a voluntad desde el código en la clave “path” de “args”.
Con esto, podrías, por ejemplo, ejecutar múltiples lógicas diferentes en función de la ruta recibida.
Considera que quieres ofrecer tres lógicas diferentes en este endpoint, un login, un logout y una lógica principal, según la ruta que se use para realizar la solicitud. Podrías hacer algo como:
def main(args):
if args["path"] == "prv/iot-expo/raw-function":
return main_page_logic()
elif args["path"] == "prv/iot-expo/raw-function/API/login":
return login_function(args["body"])
elif args["path"] == "prv/iot-expo/raw-function/API/logout":
return log_out_function()
return {
"status_code": int,
"headers": object,
"body": string,
}
Entonces, para ejecutar la lógica de la página principal, todo lo que se necesita es hacer la solicitud HTTP a:
https://parse.ubidots.com/prv/iot-expo/raw-function/
Para la lógica de login:
https://parse.ubidots.com/prv/iot-expo/raw-function/login
Y, por último, para la lógica de logout:
https://parse.ubidots.com/prv/iot-expo/raw-function/logout
6. Argumentos entrantes en la clave body
El contenido del cuerpo en la solicitud HTTP se analiza como una cadena. Por ejemplo:
Considera la siguiente solicitud a la UbiFunction mencionada anteriormente:
curl -X POST "https://parse.ubidots.com/prv/iot-expo/raw-function/" \
-H "Content-Type: plain/text" \
-d 24
Ten en cuenta que el número 24 se envió en el cuerpo (-d opción), sin embargo, lo que llega en los argumentos a la UbiFunction es en realidad dicho número convertido a una cadena, tal como:
{"body" : "24"}Supongamos ahora que es necesario enviar una cadena hexadecimal como AFD0E1. Tendrías que hacer la solicitud como:
curl -X POST "https://parse.ubidots.com/prv/iot-expo/raw-function/" \
-H "Content-Type: plain/text" \
-d "AFD0E1"
Entonces, la clave body se verá en Ubidots como:
{"body" : "AFD0E1"}
En resumen, puedes enviar cualquier contenido en el cuerpo de la solicitud, siempre que se analice como una cadena, y la UbiFunction lo recibirá como tal.
7. Respuesta de las UbiFunctions Raw
En el caso de una UbiFunction no-raw, cuando finaliza su ejecución, normalmente responderá con sus códigos de respuesta predefinidos. Sin embargo, con las funciones Raw, puedes personalizar el código de respuesta, el cuerpo y los encabezados a voluntad, de esa manera, el cliente HTTP que realiza la solicitud sabrá el resultado preciso de la ejecución.
La siguiente es la estructura JSON para personalizar la respuesta:
{
"status_code": 200,
"headers": {"Content-Type": "application/json"},
"body": string,
}Clave | Valor (valores posibles)/Tipo | Ejemplo |
status_code | Número entero:
200, 20x, 40x, 50x | "status_code" : 200 |
headers | Diccionario que contiene encabezados de respuesta. | {"Content-Type": "text/plain"} |
body | Cadena de valor. | {"body" : "[INFO] Successful request"} |
Por ejemplo, si la solicitud es válida y la ejecución exitosa, la respuesta JSON sería así:
{
"status_code": 200,
"headers": {"Content-Type": "plain/text"},
"body": "[INFO] Successful request",
}Por otro lado, si según tu lógica de código la solicitud no es válida, debería responder con un código de respuesta 400, y la respuesta JSON debería verse así:
{
"status_code": 400,
"headers": {"Content-Type": "plain/text"},
"body": "[ERROR] Bad Request, please check your request",
}