Una Atlas Function es un fragmento de código JavaScript del lado del servidor que escribes para definir el comportamiento de tu aplicación. Puedes llamar a las Functions de tu aplicación directamente desde una aplicación cliente o definir servicios que integren y llamen a las Functions 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 herramientas globales, son compatibles con módulos de funcionalidad incorporada comunes de Node.js, y pueden importar y usar paquetes externos del registro de npm.
exports = function(name) { return `Hello, ${name ?? "stranger"}!` }
Las funciones son sin servidor
Cuando se invoca una función, tu aplicación enruta la solicitud a un servidor de aplicaciones gestionado que evalúa tu código y devuelve el resultado. Este modelo hace que Functions sea sin servidor, lo que significa que no tienes que desplegar ni administrar un servidor para ejecutar el código. En su lugar, escribes el código fuente de la función y tu aplicación se encarga del 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 invocó la Function, cómo la invocó y el estado de tu aplicación cuando lo hizo. Puedes usar el contexto para ejecutar código específico del usuario y trabajar con otras partes de tu aplicación.
Para obtener más información sobre cómo trabajar con contexto de función, consulta 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 tu organización y usarlos dentro de tu 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 Usar 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 llaman automáticamente a las funciones para gestionar eventos específicos. Por ejemplo, cada vez que un activador de base de datos observa un evento de cambio, llama a su Función asociada con el evento de cambio como argumento. En la función de activador, podrás acceder a la información del evento de cambio y responder de manera adecuada.
Nota
La base de datos y los activadores programados se ejecutan siempre en el contexto de un usuario del sistema.
Cómo escribir una función
El código de una Function es esencialmente un archivo fuente JavaScript con nombre, lo que significa que puede definir múltiples funciones JavaScript en un solo archivo Function. El archivo debe exportar una única función JavaScript para que sirva como punto de entrada para las llamadas entrantes. Cuando llamas a una Function por nombre, realmente estás llamando a la función JavaScript asignada a exports en el archivo fuente de la Function.
Por ejemplo, aquí hay una función sencilla que acepta un argumento name, añade 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, llama a JSON.stringify() sobre el valor y luego devuelve el resultado como string:
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.
Puedes definir una nueva función del lado del servidor desde la interfaz de usuario de Atlas:
En Atlas, ve a Triggers página para tu 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.
Name the New Function
Introduce un nombre para la Función en el campo Name. Este nombre debe ser único entre todas las demás funciones de la aplicación.
Tip
Puedes definir Funciones dentro de carpetas anidadas. Los nombres de 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 usuarios
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, especifica el tipo de autenticación que debe usar Atlas.
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) | En desuso. Este tipo de autenticación configura una función para que se ejecute siempre como un usuario de aplicación específico. |
Guión | Este tipo de autenticación configura una Función para ejecutarse como un usuario de aplicación específico, determinado en función del resultado de una Función personalizada que se define. La función debe devolver la cadena |
Especifica una expresión de autorización
Puede autorizar dinámicamente las solicitudes en función del contenido de cada solicitud definiendo una Can Evaluate expresión. Atlas evalúa la expresión cada vez que se llama a la función. Si no especificas 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.
Configura el nivel de privacidad de la función
Por defecto, puedes llamar a una Función desde aplicaciones de cliente, así como a otras Funciones en la misma aplicación. Se puede evitar que las aplicaciones cliente vean o llamen a una función configurando Private en true.
Aún puedes llamar a una función privada desde una expresión y otras funciones, incluidos webhooks y activadores entrantes.
Write the Function Code
Después de crear y configurar la nueva Función, puedes escribir el código JavaScript que se ejecuta cuando se 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 de Create Function, haz clic en la pestaña Function Editor.
Añadir 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
Puedes usar la mayoría de las funcionalidades modernas de JavaScript (ES6+) en Funciones, incluyendo async/await, destructuring y template literals.
Autenticar a 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.
Escribe el código fuente de la función
Las funciones Atlas ejecutan funciones estándar de JavaScript ES6+ que exportas 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. Utilice barras en el nombre del archivo para indicar una ruta de subdirectorio.
touch functions/<FunctionName>.js
Tip
Puedes definir funciones dentro de carpetas anidadas en el directorio functions. Utilice barras 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
Puedes usar la mayoría de las funcionalidades modernas de JavaScript (ES6+) en Funciones, incluyendo async/await, destructuring y template literals.
Configura la Función
En el directorio functions de tu aplicación local, abre el archivo config.json y añade un objeto de configuración para tu nueva función en el arreglo.
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>" }
Configura 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, especifica el tipo de autenticación que debe usar Atlas.
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 (en desuso): para ejecutar una función como un usuario específico, utiliza 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.Especifica una expresión de autorización:
Puede autorizar dinámicamente las solicitudes en función del contenido de cada solicitud definiendo una Can Evaluate expresión. Atlas evalúa la expresión cada vez que se llama a la función. Si no especificas 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:
Expresión de autorización de ejemplo{ "%%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, configura
privateentrue.
Implementa tus 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 sencilla llamada sum que toma dos argumentos, los suma y devuelve el resultado:
// sum: adds two numbers exports = function sum(a, b) { return a + b; };
Llamar desde una función
Puede llamar a una función desde otra función a través de la interfaz context.functions, la cual está disponible como variable global en cualquier Función. La función que se llama 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 App Services CLI
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 usar hasta 350MB de memoria en cualquier momento.
Las funciones están limitadas a 1000 operaciones asíncronas.
Functions support most commonly used ES6+ features and Node.js built-in modules. However, some features that are uncommon or unsuited to serverless workloads are not supported. For more information, see JavaScript Support.
Una función puede abrir un máximo de 25 sockets usando el módulo de funcionalidad incorporada net.
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.