Overview
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, admiten módulos comunes integrados 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.
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.
Además de las funciones que invoca directamente, también escribe funciones para varios servicios como puntos finales HTTPS, activadores y solucionadores personalizados de GraphQL (los puntos finales GraphQL y HTTPS están obsoletos. Para obtener más información, consulte Obsolescencia de funciones).
Estos servicios 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.
Cómo escribir una función
El código de una función es esencialmente 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 para que sirva como punto de entrada para las llamadas entrantes. Al llamar a una función por su nombre, en realidad se llama a la función JavaScript asignada a ella.
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\"}"
Funciones de usuario y del sistema
Una función puede ejecutarse en dos contextos dependiendo de cómo se configure y se llame:
Una función de usuario se ejecuta en el contexto de un usuario específico de la aplicación. Normalmente, este es el usuario conectado que la llamó. Las funciones de usuario están sujetas a reglas y validación de esquemas.
Una función del sistema se ejecuta como el usuario del sistema en lugar de un usuario específico de la aplicación. Las funciones del sistema tienen acceso completo a las API CRUD y de agregación de MongoDB y omiten todas las reglas y la validación del esquema.
Nota
Referencias dinámicas de context.user
Las referencias a context.user siempre se resuelven al usuario autenticado que llamó a una función, si la hubo, incluso si la función se ejecuta como una función del sistema. Para determinar si una función se ejecuta como una función del sistema, llame context.runningAsSystem() a.
Si una función se ejecuta sin ser llamada por un usuario autenticado, como en un disparador o webhook, las referencias dinámicas se resuelven en el usuario del sistema que no tiene id u otros datos asociados.
Definir una función
Puede crear y administrar funciones en su aplicación desde la interfaz de usuario de App Services o importando la configuración de la función y el código fuente con la CLI de App Services o la implementación de GitHub.
Nombrar la nueva función
Introduzca un nombre único e identificativo para la función en el campo Name. Este nombre debe ser distinto al de 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 de App Services siempre se ejecutan en el contexto de un usuario de aplicación específico 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 App Services debe usar.
Tipo de autenticación | Descripción |
|---|---|
Autenticación de aplicaciones | Este tipo de autenticación configura una función para que se ejecute 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, 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 | Este tipo de autenticación configura una función para que siempre se ejecute como un usuario de aplicación específico. |
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 de un usuario específico |
Especificar una expresión de autorización
Puede autorizar solicitudes dinámicamente según el contenido de cada solicitud al definir una Can Evaluate expresión. App Services evalúa la expresión cada vez que se llama a la función. Si no especificas una expresión, aplicación Services autorizará 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 desde otras funciones de la misma aplicación. Puede impedir 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
Una vez creada y configurada la nueva función, es hora de escribir el código JavaScript que se ejecuta al llamarla. Puedes escribir el código directamente en la interfaz de usuario de App Services mediante el editor de funciones.
Nota
Puede utilizar la mayoría de las características modernas de JavaScript (ES6+) en funciones, incluidas async/await, desestructuración y literales de plantilla.
Desde la página Settings de la función:
Haz 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!"; };
Escriba el código fuente de la función
Las funciones Atlas ejecutan funciones JavaScript estándar de ES6+ que se exportan desde archivos individuales. Cree un archivo .js con el mismo nombre que la función en el directorio functions o en uno de sus subdirectorios.
touch functions/myFunction.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.
Una vez que haya creado el archivo .js de la función, escriba el código fuente de la función, por ejemplo:
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 funciones modernas de6JavaScript (ES +) en funciones, como async/await, desestructuración y literales de plantilla. Para ver si App Services admite una función específica, consulta Compatibilidad con JavaScript.
Configurar la función
En el functions directorio de su aplicación, abra el config.json archivo y agregue un objeto de configuración para su nueva función a la matriz. El objeto debe tener el siguiente formato:
{ "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>" }
Establecer autenticación de usuario
Las funciones de App Services siempre se ejecutan en el contexto de un usuario específico de la aplicación o como un usuario del sistema (lo que omite las reglas). Para configurar el usuario de ejecución de la función, especifique el tipo de autenticación que App Services debe usar:
Sistema
Para ejecutar una función como usuario del sistema, utilice la siguiente configuración:
{ "run_as_system": true, "run_as_user_id": "", "run_as_user_id_script_source": "" } Usuario
Para ejecutar una función como un usuario específico, utilice la siguiente configuración:
{ "run_as_system": false, "run_as_user_id": "<App Services User Id>", "run_as_user_id_script_source": "" } Guión
La tercera forma de ejecutar una función es especificar otra función que devuelva un ID de usuario. La función se ejecutará como este usuario. Para ello, utilice la siguiente configuración:
{ "run_as_system": false, "run_as_user_id": "", "run_as_user_id_script_source": "<Function Source Code>" }
Establecer registro de ejecución
Para incluir cualquier valor que la función reciba como argumento en su entrada de registro,disable_arg_logs establezca false en.
Especificar una expresión de autorización
Puede autorizar solicitudes dinámicamente según el contenido de cada solicitud al definir una Can Evaluate expresión. App Services evalúa la expresión cada vez que se llama a la función. Si no especificas una expresión, aplicación Services autorizará automáticamente todas las solicitudes entrantes autenticadas.
La expresión puede expandir variables de expresión estándar, incluidas las expansiones %%request %%user y.
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.
{ "%%request.remoteIPAddress": { "$nin": [ "248.88.57.58", "19.241.23.116", "147.64.232.1" ] } }
Configurar el nivel de privacidad de la función
De forma predeterminada, se puede llamar a una función desde aplicaciones cliente, así como desde otras funciones de la misma aplicación. Puede impedir que las aplicaciones cliente vean o llamen a una función estableciendo private en true.
Puede llamar a una función privada desde una expresión de regla u otra función, incluidos los puntos finales y activadores HTTPS.
Llamar a una función
Puede llamar a una función desde otras funciones, desde una aplicación cliente conectada o con 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 función a través de la interfaz context.functions, la cual está disponible como variable global en cualquier función. Esto incluye endpoints HTTPS, activadores y resolutores personalizados GraphQL (desaprobado, más información). La función llamada se ejecuta en el mismo contexto que la función que la invocó.
// 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 App Services
Puedes llamar a una función mediante la CLI de App Services con el comando function run. Este comando devuelve el resultado de la función como EJSON, así como cualquier mensaje de registro o 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
Llamada desde Expresiones de reglas
Puedes llamar a una función desde una expresión de regla usando el operador. Este operador evalúa el valor de retorno de la función. Si la función genera un error, la %function expresión false evalúa.
{ "numGamesPlayed": { "%function": { "name": "sum", "arguments": [ "%%root.numWins", "%%root.numLosses" ] } } }
Llamada desde los SDK de Realm
Importante
Asegúrese de desinfectar los datos del cliente para protegerlos contra la inyección de código al usar funciones.
Puede llamar a una función desde aplicaciones cliente conectadas con un SDK de Realm o mediante un protocolo de red. Para ver ejemplos de código que muestran cómo llamar a una función desde una aplicación cliente, consulte la documentación de los SDK de Realm:
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 usando la red módulo incorporado.
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, así como a los encabezados o la carga útil de la solicitud si la función se llama a través de un punto final HTTPS.