Una función Atlas es un fragmento de código JavaScript del lado del servidor que se escribe para definir el comportamiento de la aplicación. Puedes llamar a las funciones de la aplicación directamente desde una aplicación cliente o definir servicios que las integren y las llamen automáticamente.
Las funciones pueden llamar a otras funciones e incluyen un cliente integrado para trabajar con datos en clústeres de MongoDB Atlas. También incluyen útiles utilidades globales, son compatibles con módulos integrados comunes de Node.js y permiten importar y usar paquetes externos desde el registro de npm.
exports = function(name) { return `Hello, ${name ?? "stranger"}!` }
Las funciones no tienen servidor
Cuando se llama a una función, la aplicación dirige la solicitud a un servidor de aplicaciones administrado que evalúa el código y devuelve el resultado. Este modelo permite que las funciones funcionen sin servidor, lo que significa que no es necesario implementar ni administrar un servidor para ejecutar el código. En su lugar, se escribe el código fuente de la función y la aplicación gestiona el entorno de ejecución.
Las funciones tienen contexto
Una función se ejecuta en un contexto que refleja su entorno de ejecución. El contexto incluye el usuario que la llamó, cómo la llamó y el estado de la aplicación en ese momento. Puedes usar el contexto para ejecutar código específico del usuario y trabajar con otras partes de la aplicación.
Para obtener más información sobre cómo trabajar con el contexto de función, consulte Contexto.
Las funciones pueden llamar a servicios externos
Puede crear una función que realice solicitudes HTTP salientes (por ejemplo, utilizando el
http paquete externo) para acceder a datos fuera de su organización para usarlos dentro de su función.
Nota
Direcciones IP de salida
Un servicio externo puede tener un firewall que limita el acceso a llamadas desde ciertas direcciones IP. En este caso, deberá configurar la lista de IP aprobadas para ese servicio. Para obtener más información, consulte Acceso IP saliente de seguridad de funciones.
Cuándo utilizar funciones
Las funciones pueden ejecutar cualquier código JavaScript que definas, lo que significa que puedes utilizarlas para casi cualquier cosa. Los casos de uso comunes incluyen tareas de baja latencia y corta duración, como movimiento de datos, transformaciones y validación. También puedes usarlas para conectarte a servicios externos y abstraer detalles de implementación de tus aplicaciones cliente.
Los disparadores invocan automáticamente funciones para gestionar eventos específicos. Por ejemplo, cuando un disparador de base de datos detecta un evento de cambio, invoca su función asociada con dicho evento como argumento. En la función del disparador, se puede acceder a la información del evento de cambio y responder adecuadamente.
Nota
Los activadores de base de datos y programados siempre se ejecutan en el contexto de un usuario del sistema.
Cómo escribir una función
El código de una función es básicamente un archivo fuente JavaScript con nombre, lo que significa que se pueden definir varias funciones JavaScript en un solo archivo. El archivo debe exportar una sola función JavaScript que sirva como punto de entrada para las llamadas entrantes. Al llamar a una función por su nombre, se llama a la función JavaScript asignada a exports en el archivo fuente de la función.
Por ejemplo, aquí hay una función simple que acepta un argumento name, agrega un mensaje de registro y devuelve un saludo para el nombre proporcionado:
exports = function Hello(name) { console.log(`Said hello to ${name}`); return `Hello, ${name}!`; };
Puedes utilizar la sintaxis moderna de JavaScript e importar paquetes para definir funciones más complejas:
// You can use ES6 arrow functions const uppercase = (str) => { return str.toUpperCase(); }; // You can use async functions and await Promises exports = async function GetWeather() { // You can get information about the user called the function const city = context.user.custom_data.city; // You can import Node.js built-ins and npm packages const { URL } = require("url"); const weatherUrl = new URL("https://example.com"); weatherUrl.pathname = "/weather"; weatherUrl.search = `?location="${city}"`; // You can send HTTPS requests to external services const weatherResponse = await context.http.get({ url: url.toString(), headers: { Accept: ["application/json"], }, }); const { current, forecasts } = JSON.parse(weatherResponse.body.text()); return [ `Right now ${uppercase(city)} is ${current.temperature}°F and ${current.weather}.`, `Here's the forecast for the next 7 days:`, forecasts .map((f) => `${f.day}: ${f.temperature}°F and ${f.weather}`) .join("\n "), ].join("\n"); };
Right now NEW YORK CITY is 72°F and sunny. Here's the forecast for the next 7 days: Tuesday: 71°F and sunny Wednesday: 72°F and sunny Thursday: 73°F and partly cloudy Friday: 71°F and rainy Saturday: 77°F and sunny Sunday: 76°F and sunny Monday: 74°F and sunny
Las funciones serializan automáticamente los valores devueltos a JSON extendido. Esto es útil para preservar la información de tipo, pero puede no ser lo que tu aplicación espera.
Por ejemplo, los valores del objeto devuelto por la siguiente función se convierten en valores EJSON estructurados:
exports = function() { return { pi: 3.14159, today: new Date(), } }
{ "pi": { "$numberDouble": "3.14159" }, "today": { "$date": { "$numberLong": "1652297239913" } } }
Para devolver un valor como JSON estándar, llame a JSON.stringify() en el valor y luego devuelva el resultado en formato cadena:
exports = function() { return JSON.stringify({ pi: 3.14159, today: new Date(), }) }
"{\"pi\":3.14159,\"today\":\"2022-05-11T19:27:32.207Z\"}"
Definir una función
Puede crear y administrar funciones en su aplicación desde la interfaz de usuario de Atlas o importando la configuración de la función y el código fuente mediante la CLI de App Services o la implementación de GitHub.
Puede definir una nueva función del lado del servidor desde la interfaz de usuario de Atlas:
En Atlas, vaya a la Triggers Página para su proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Triggers en la sección Streaming Data.
Nombrar la nueva función
Introduzca un nombre para la función en el campo Name. Este nombre debe ser único respecto a las demás funciones de la aplicación.
Tip
Puedes definir funciones dentro de carpetas anidadas. Los nombres de las funciones son rutas separadas por barras, por lo que una función llamada utils/add se asigna a functions/utils/add.js en los archivos de configuración de la aplicación.
Configurar la autenticación de usuario
Las funciones en Atlas siempre se ejecutan en el contexto de un usuario específico de la aplicación o como un usuario del sistema que omite las reglas. Para configurar el usuario de ejecución de la función, especifique el tipo de autenticación que Atlas debe usar.
Nota
Las funciones para base de datos y disparadores programados siempre se ejecutan en el contexto de un usuario del sistema.
Tipo de autenticación | Descripción |
|---|---|
Autenticación de aplicaciones (obsoleta) | Obsoleto. Este tipo de autenticación configura una función para ejecutarse en el contexto del usuario de la aplicación existente que inició sesión cuando la aplicación cliente llamó a la función. Si la función fue llamada desde otra función, entonces hereda el usuario de ejecución de esa función. |
Sistema | Este tipo de autenticación configura una función para ejecutarse como un usuario del sistema que tiene acceso completo a las API de CRUD y agregación de MongoDB y no se ve afectado por ninguna regla, rol o permiso. |
ID de usuario (obsoleto) | Obsoleto. Este tipo de autenticación configura una función para que siempre se ejecute como un usuario específico de la aplicación. |
Guión | Este tipo de autenticación configura una función para que se ejecute como un usuario específico de la aplicación, determinado según el resultado de una función personalizada que usted defina. La función debe devolver la cadena |
Especificar una expresión de autorización
Puede autorizar solicitudes dinámicamente según el contenido de cada una definiendo una Can Evaluate expresión. Atlas evalúa la expresión cada vez que se llama a la función. Si no especifica una expresión, Atlas autoriza automáticamente todas las solicitudes entrantes autenticadas.
La expresión puede expandir variables de expresión estándar, incluidas las expansiones %%request %%user y.
Configurar el nivel de privacidad de la función
De forma predeterminada, se puede llamar a una función desde aplicaciones cliente, así como a otras funciones de la misma aplicación. Puede evitar que las aplicaciones cliente vean o llamen a una función estableciendo Private en true.
Aún puedes llamar a una función privada desde una expresión y otras funciones, incluidos webhooks y activadores entrantes.
Escribe el código de función
Después de haber creado y configurado la nueva función, puede escribir el código JavaScript que se ejecuta cuando llama a la función.
Puede escribir el código directamente en la interfaz de usuario de Atlas utilizando el editor de funciones.
Desde la página Create Function, haga clic en la pestaña Function Editor.
Agregue código JavaScript a la función. Como mínimo, el código debe asignar una función a
exports, como en el siguiente ejemplo:exports = function() { return "Hello, world!"; }; Nota
Puede utilizar la mayoría de las funciones modernas de JavaScript (ES6+) en Funciones, incluidas async/await, desestructuración y literales de plantilla.
Autenticar un usuario de MongoDB Atlas
Utilice su clave API de administración de MongoDB Atlas para iniciar sesión en la CLI de App Services:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"
Extraiga los últimos archivos de configuración de su aplicación
Ejecute el siguiente comando para obtener una copia local de sus archivos de configuración:
appservices pull --remote=<App ID>
De forma predeterminada, el comando extrae los archivos al directorio de trabajo actual. Puede especificar una ruta de directorio con el indicador opcional --local.
Escriba el código fuente de la función
Las funciones Atlas ejecutan funciones JavaScript ES6+ estándar que se exportan desde archivos individuales.
Crea un archivo
.jsen el directoriofunctionso en un subdirectorio.El nombre del archivo debe coincidir con el nombre de la función. Use barras diagonales en el nombre del archivo para indicar la ruta de un subdirectorio.
touch functions/<FunctionName>.js
Tip
Puedes definir funciones dentro de carpetas anidadas en el directorio functions. Usa barras diagonales en el nombre de una función para indicar su ruta de directorio. Por ejemplo, una función llamada utils/add se asigna a functions/utils/add.js.
Escriba el código fuente de la función en el archivo creado.
Por ejemplo, la siguiente función hello.js devuelve un saludo para el nombre proporcionado:
exports = async function hello(...args) { // Write your function logic here! You can... // Import dependencies const assert = require("assert") assert(typeof args[0] === "string") // Use ES6+ syntax const sayHello = (name = "world") => { console.log(`Hello, ${name}.`) } // Return values back to clients or other functions return sayHello(args[0]) }
Nota
Puede utilizar la mayoría de las funciones modernas de JavaScript (ES6+) en Funciones, incluidas async/await, desestructuración y literales de plantilla.
Configurar la función
En el functions directorio de su aplicación local, abra el config.json archivo y agregue un objeto de configuración para su nueva Función a la matriz.
El objeto debe tener la siguiente forma:
{ "name": "<Function Name>", "private": <Boolean>, "can_evaluate": { <JSON Expression> }, "disable_arg_logs": <Boolean>, "run_as_system": <Boolean>, "run_as_user_id": "<App Services User ID>", "run_as_user_id_script_source": "<Function Source Code>" }
Configurar la autenticación del usuario:
Las funciones en Atlas siempre se ejecutan en el contexto de un usuario específico de la aplicación o como un usuario del sistema que omite las reglas. Para configurar el usuario de ejecución de la función, especifique el tipo de autenticación que Atlas debe usar.
Nota
Las funciones para base de datos y disparadores programados siempre se ejecutan en el contexto de un usuario del sistema.
Usuario del sistema: para ejecutar la función como usuario del sistema, utilice la siguiente configuración:
Configuración de usuario del sistema{ "run_as_system": true, "run_as_user_id": "", "run_as_user_id_script_source": "" } Script: Para ejecutar la Función como un usuario que regresa de otra Función, utilice la siguiente configuración:
Configuración del script{ "run_as_system": false, "run_as_user_id": "", "run_as_user_id_script_source": "<Function Source Code>" } Usuario (obsoleto): para ejecutar una función como un usuario específico, utilice la siguiente configuración:
Configuración de ID de usuario (obsoleta){ "run_as_system": false, "run_as_user_id": "<App Services User Id>", "run_as_user_id_script_source": "" }
Configurar los registros de funciones:
Para incluir los argumentos que la función recibió en la entrada de registro para cada ejecución de la función, establezca
disable_arg_logsenfalse.Especifique una expresión de autorización:
Puede autorizar solicitudes dinámicamente según el contenido de cada una definiendo una Can Evaluate expresión. Atlas evalúa la expresión cada vez que se llama a la función. Si no especifica una expresión, Atlas autoriza automáticamente todas las solicitudes entrantes autenticadas.
La expresión puede expandir variables de expresión estándar, incluidas las expansiones
%%request%%usery.Por ejemplo, la siguiente expresión solo autoriza solicitudes entrantes si la dirección IP del remitente no está incluida en la lista de direcciones especificada:
Ejemplo de expresión de autorización{ "%%request.remoteIPAddress": { "$nin": [ "248.88.57.58", "19.241.23.116", "147.64.232.1" ] } } Configurar el nivel de privacidad:
Para evitar que las aplicaciones cliente vean o llamen a la función, configure
privateentrue.
Implementar sus cambios:
Sube la configuración y el código fuente de la función para implementarla en tu aplicación. Puedes empezar a usarla inmediatamente.
Ejecute el siguiente comando para implementar sus cambios:
appservices push
Llamar a una función
Puede llamar a una función desde otra función o utilizando la CLI de App Services.
Los ejemplos de esta sección demuestran cómo llamar a una función simple llamada sum que toma dos argumentos, los suma y devuelve el resultado:
// sum: adds two numbers exports = function sum(a, b) { return a + b; };
Llamada desde una función
Puedes llamar a una función desde otra mediante la interfaz context.functions, disponible como variable global en cualquier función. La función llamada se ejecuta en el mismo contexto que la función que la llamó.
// difference: subtracts b from a using the sum function exports = function difference(a, b) { return context.functions.execute("sum", a, -1 * b); };
Llamada desde la CLI de servicios de aplicaciones
Se puede llamar una función desde la App Services CLI con el comando function ejecutar. El comando devuelve el resultado de la función en EJSON junto con cualquier mensaje de registro o de error.
appservices function run \ --name=sum \ --args=1 --args=2
De forma predeterminada, las funciones se ejecutan en el contexto del sistema. Para llamar a una función en el contexto de un usuario específico, incluya su ID de usuario en el --user argumento.
appservices function run \ --name=sum \ --args=1 --args=2 \ --user=61a50d82532cbd0de95c7c89
Restricciones
Las funciones están limitadas a 300 segundos de tiempo de ejecución por solicitud, después de lo cual la función expirará y fallará.
Las funciones pueden utilizar hasta 350MB de memoria en cualquier momento.
Las funciones están limitadas a 1000 operaciones asincrónicas.
Las funciones6son compatibles con las características más comunes de ES + y los módulos integrados de Node.js. Sin embargo, algunas características poco comunes o inadecuadas para cargas de trabajo sin servidor no son compatibles. Para más información, consulte Compatibilidad con JavaScript.
Una función puede abrir un máximo de 25 sockets utilizando el módulo de red integrado.
Las solicitudes entrantes tienen un límite de tamaño máximo de 18 MB. Este límite se aplica al tamaño total de todos los argumentos pasados a la función.