Controlador de la función AWS Lambda en Node.js

El controlador de la función de Lambda es el método del código de la función que procesa eventos. Cuando se invoca una función, Lambda ejecuta el método del controlador. La función se ejecuta hasta que el controlador devuelve una respuesta, se cierra o se agota el tiempo de espera.

La siguiente función de ejemplo registra el contenido del objeto de evento y devuelve la ubicación de los registros.

nota

Esta página muestra ejemplos de controladores de módulos CommonJS y ES. Para obtener más información sobre la diferencia entre estos dos tipos de controladores, consulte Designación de un controlador de funciones como módulo de ES.

ES module handler

export const handler = async (event, context) => {
  console.log("EVENT: \n" + JSON.stringify(event, null, 2));
  return context.logStreamName;
};

CommonJS module handler

exports.handler = async function (event, context) {
  console.log("EVENT: \n" + JSON.stringify(event, null, 2));
  return context.logStreamName;
};

Al configurar una función, el valor del controlador es el nombre del archivo y el nombre del método del controlador exportado, separados por un punto. El valor predeterminado en la consola y para ejemplos de esta guía es index.handler. Esto indica el método handler que se exporta desde el archivo index.js.

El tiempo de ejecución pasa argumentos al método del controlador. El primer argumento es el objeto event, que contiene información del invoker. El invocador pasa esta información como una cadena con formato JSON cuando llama a Invoke y el runtime la convierte en un objeto. Cuando un servicio de AWS invoca su función, la estructura del evento varía en función del servicio.

El segundo argumento es el objeto context, que incluye información sobre la invocación, la función y el entorno de ejecución. En el ejemplo anterior, la función obtiene el nombre de flujo de registro del objeto context y lo devuelve al invocador.

También puede utilizar un argumento de devolución de llamada, una función a la que puede llamar en los controladores non-async para enviar una respuesta. Le recomendamos que utilice async/await en lugar de devolución de llamadas. Async/await mejora la legibilidad, el manejo de errores y la eficiencia. Para obtener información sobre las diferencias entre async/await y las devoluciones de llamadas, consulte Uso de devolución de llamadas.

Denominación

Al configurar una función, el valor del controlador es el nombre del archivo y el nombre del método del controlador exportado, separados por un punto. El valor predeterminado de las funciones creadas en la consola y de los ejemplos de esta guía es index.handler. Esto indica el método handler que se exporta desde el archivo index.js o index.mjs.

Si crea una función en la consola con un nombre de archivo o un nombre de controlador de funciones diferente, debe editar el nombre del controlador predeterminado.

Para cambiar el nombre de controlador de la función (consola)

1. Abra la página Funciones de la consola de Lambda y elija su función.

2. Elija la pestaña Código.

3. Desplácese hacia abajo hasta el panel Configuración del tiempo de ejecución y elija Editar.

4. En Controlador, ingrese el nuevo nombre del controlador de funciones.

5. Elija Guardar.

Uso de async/await

Si su código realiza una tarea asíncrona, utilice el patrón async/await para asegurarse de que el controlador termina de ejecutarse. Async/await es una forma concisa y legible de escribir código asíncrono en Node.js, sin necesidad de devoluciones de llamadas anidadas ni promesas encadenadas. Con async/await, puedes escribir código que se lea como código sincrónico, sin dejar de ser asíncrono y sin bloqueo.

La palabra clave async marca una función como asíncrona y la palabra clave await detiene la ejecución de la función hasta que se resuelva una Promise.

nota

Asegúrese de esperar a que se completen los eventos asincrónicos. Si la función regresa antes de que se completen los eventos asincrónicos, podría fallar o causar un comportamiento inesperado en la aplicación. Esto puede suceder cuando un bucle forEach contiene un evento asincrónico. Los bucles forEach esperan una llamada sincrónica. Para obtener más información, consulte Array.prototype.forEach() en la documentación de Mozilla.

ES module handler

ejemplo — solicitud HTTP con async/await

En este ejemplo se usa fetch, que está disponible en el tiempo de ejecución de nodejs18.x.

const url = "https://aws.amazon.com/";

export const handler = async(event) => {
    try {
        // fetch is available with Node.js 18
        const res = await fetch(url);
        console.info("status", res.status);
        return res.status;
    }
    catch (e) {
        console.error(e);
        return 500;
    }
};

CommonJS module handler

ejemplo — solicitud HTTP con async/await

const https = require("https");
let url = "https://aws.amazon.com/";

exports.handler = async function (event) {
  let statusCode;
  await new Promise(function (resolve, reject) {
    https.get(url, (res) => {
        statusCode = res.statusCode;
        resolve(statusCode);
      }).on("error", (e) => {
        reject(Error(e));
      });
  });
  console.log(statusCode);
  return statusCode;
};

En el siguiente ejemplo, se usa async/await para enumerar los buckets de Amazon Simple Storage Service.

nota

Antes de usar este ejemplo, asegúrese de que el rol de ejecución de la función tenga permisos de lectura de Amazon S3.

ES module handler

ejemplo — SDK de AWS v3 con async/await

En este ejemplo se usa AWS SDK for JavaScript v3, que está disponible en el tiempo de ejecución de nodejs18.x.

import {S3Client, ListBucketsCommand} from '@aws-sdk/client-s3';
const s3 = new S3Client({region: 'us-east-1'});
   
export const handler = async(event) => {
  const data = await s3.send(new ListBucketsCommand({}));
  return data.Buckets;
        
};

CommonJS module handler

ejemplo — SDK de AWS v2 con async/await

En este ejemplo se usa AWS SDK for JavaScript v2, que está disponible en el tiempo de ejecución de Lambda nodejs16.x.

const AWS = require('aws-sdk')
const s3 = new AWS.S3()
   
exports.handler = async function(event) {
  const buckets = await s3.listBuckets().promise()
  return buckets
}

Uso de devolución de llamadas

Le recomendamos que utilice async/await para declarar el controlador de funciones en lugar de utilizar devolución de llamadas. Async/await es una mejor opción por diversas razones:

• Legibilidad: el código async/await es más fácil de leer y entender que el código de devolución de llamada, que puede volverse difícil de seguir con rapidez y provocar un caos de devolución de llamadas.

• Depuración y gestión de errores: depurar código basado en devoluciones de llamadas puede resultar difícil. La pila de llamadas puede resultar difícil de seguir y los errores se pueden pasar por alto con facilidad. Con async/await, puede utilizar bloques try/catch para gestionar los errores.

• Eficiencia: las devoluciones de llamadas a menudo requieren cambiar entre diferentes partes del código. Async/await puede reducir la cantidad de cambios de contexto, lo que resulta en un código más eficiente.

Cuando utiliza devoluciones de llamadas en su controlador, la función prosigue con su ejecución hasta que el bucle de eventos está vacío o se agota el tiempo de espera de la función. La respuesta no se envía al invoker hasta que todas las tareas de bucle de eventos hayan terminado. Si el tiempo de espera de la función se agota, se devolverá un error en su lugar. Puede configurar el tiempo de ejecución para enviar la respuesta inmediatamente estableciendo context.callbackWaitsForEmptyEventLoop en false.

La función de devolución de llamada toma dos argumentos: un Error y una respuesta. El objeto de respuesta debe ser compatible con JSON.stringify.

La siguiente función de ejemplo comprueba una URL y devuelve el código de estado al invocador.

ES module handler

ejemplo — solicitud HTTP con callback

import https from "https";
let url = "https://aws.amazon.com/";

export function handler(event, context, callback) {
  https.get(url, (res) => {
      callback(null, res.statusCode);
    }).on("error", (e) => {
      callback(Error(e));
    });
}

CommonJS module handler

ejemplo — solicitud HTTP con callback

const https = require("https");
let url = "https://aws.amazon.com/";

exports.handler = function (event, context, callback) {
  https.get(url, (res) => {
      callback(null, res.statusCode);
    }).on("error", (e) => {
      callback(Error(e));
    });
};

En el siguiente ejemplo, la respuesta desde Amazon S3 se devolverá al invocador tan pronto como esté disponible. El tiempo de espera que se ejecuta en el bucle de eventos se ha detenido y continuará ejecutándose la próxima vez que se invoque la función.

nota

Antes de usar este ejemplo, asegúrese de que el rol de ejecución de la función tenga permisos de lectura de Amazon S3.

ES module handler

ejemplo – SDK de AWS v3 con callbackWaitsForEmptyEventLoop

En este ejemplo se usa AWS SDK for JavaScript v3, que está disponible en el tiempo de ejecución de nodejs18.x.

import AWS from "@aws-sdk/client-s3";
const s3 = new AWS.S3({});

export const handler = function (event, context, callback) {
  context.callbackWaitsForEmptyEventLoop = false;
  s3.listBuckets({}, callback);
  setTimeout(function () {
    console.log("Timeout complete.");
  }, 5000);
};

CommonJS module handler

ejemplo — SDK de AWS v2 con callbackWaitsForEmptyEventLoop

En este ejemplo se usa AWS SDK for JavaScript v2, que está disponible en el tiempo de ejecución de Lambda nodejs16.x.

const AWS = require("aws-sdk");
const s3 = new AWS.S3();

exports.handler = function (event, context, callback) {
  context.callbackWaitsForEmptyEventLoop = false;
  s3.listBuckets(null, callback);
  setTimeout(function () {
    console.log("Timeout complete.");
  }, 5000);
};