Manipulador da função do AWS Lambda em Node.js - AWS Lambda

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Manipulador da função do AWS Lambda em Node.js

O manipulador da função do Lambda é o método no código da função que processa eventos. Quando sua função é invocada, o Lambda executa o método do manipulador. A função é executada até que o manipulador retorne uma resposta, seja encerrado ou atinja o tempo limite.

O exemplo de função a seguir registra o conteúdo do objeto de evento e retorna a localização dos registros.

nota

Esta página exibe exemplos de manipuladores de módulos CommonJS e ES. Para saber mais sobre a diferença entre esses dois tipos de manipulador, consulte Designar um manipulador de funções como módulo ES.

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

Quando você configura uma função, o valor da configuração do manipulador é o nome do arquivo e o nome do módulo do manipulador exportado, separados por um ponto. O padrão no console e nos exemplos deste guia é index.handler. Isso indica o método do handler que é exportado do arquivo index.js.

O runtime transmite argumentos para o método do handler. O primeiro argumento é o objeto event, que contém informações do chamador. O invocador passa essas informações como uma string no formato JSON ao chamar Invoke, e o runtime as converte em um objeto. Quando um serviço da AWS invoca a sua função, a estrutura do evento varia de acordo com o serviço.

O segundo argumento é o objeto de contexto, que contém informações sobre a invocação, a função e o ambiente de execução. No exemplo anterior, a função obtém o nome do fluxo de logs do objeto de contexto e o retorna para o invocador.

Também é possível usar um argumento de retorno de chamada, que é uma função que você pode chamar nos manipuladores não assíncronos para enviar uma resposta. Recomendamos o uso de async/await em vez dos retornos de chamada. Async/await oferece melhor legibilidade, tratamento de erros e eficiência. Para obter mais informações sobre as diferenças entre async/await e retornos de chamada, consulte Usar retornos de chamada.

Usar async/await

Se o código realizar uma tarefa assíncrona, use o padrão async/await para garantir que a execução do manipulador seja finalizada. Async/await é uma forma concisa e legível de escrever código assíncrono em Node.js, sem a necessidade de retornos de chamada aninhados ou promessas de encadeamento. Com async/await, é possível escrever um código que seja lido como código síncrono e, ao mesmo tempo, seja assíncrono e sem bloqueio.

A palavra-chave async marca uma função como assíncrona, e a palavra-chave await pausa a execução da função até que uma Promise seja resolvida.

nota

Aguarde a conclusão dos eventos assíncronos. Se a função retornar antes que os eventos assíncronos sejam concluídos, a função poderá falhar ou causar um comportamento inesperado em sua aplicação. Isso pode acontecer quando um loop forEach contiver um evento assíncrono. Os loops forEach esperam uma chamada síncrona. Para obter mais informações, consulte Array.prototype.forEach() na documentação do Mozilla.

CommonJS module handler
exemplo – Solicitação HTTP com 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; };
ES module handler
exemplo – Solicitação HTTP com async/await

Este exemplo usa fetch, que está disponível no runtime 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; } };

O próximo exemplo usa async/await para listar buckets do Amazon Simple Storage Service.

nota

Antes de usar esse exemplo, verifique se o perfil de execução da sua função tem permissões de leitura do Amazon S3.

CommonJS module handler
exemplo – AWS SDK v2 com async/await

Este exemplo usa AWS SDK for JavaScript v2, que está incluído no runtime do Lambda para 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 }
ES module handler
exemplo – AWS SDK v3 com async/await

Este exemplo usa AWS SDK for JavaScript v3, que está disponível no runtime 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; };

Usar retornos de chamada

Recomendamos usar async/await para declarar o manipulador da função em vez de usar retornos de chamada. Async/await é a melhor opção por vários motivos:

  • Legibilidade: o código async/await é mais fácil de ler e entender do que o código de retorno de chamada, que pode logo se tornar difícil de seguir e transformar o retorno de chamada em um tormento.

  • Depuração e tratamento de erros: pode ser difícil depurar código baseado em retorno de chamada. A pilha de chamadas pode se tornar difícil de acompanhar, e os erros podem ser facilmente ignorados. Com async/await, você pode usar blocos try/catch para manipular erros.

  • Eficiência: retornos de chamada muitas vezes exigem alternância entre diferentes partes do código. O async/await pode reduzir o número de alternâncias de contexto, resultando em um código mais eficiente.

Quando você usa retornos de chamada no manipulador, a função continua em execução até que o loop de evento esteja vazio ou o tempo da função se esgote. A resposta não é enviada para o chamador até que todas as tarefas de loop de evento estejam concluídas. Se a função expirar, um erro será retornado. Você pode configurar o tempo de execução para enviar a resposta imediatamente definindo o contexto. callbackWaitsForEmptyEventLoopmuito falso.

A função de retorno de chamada usa dois argumentos: um Error e uma resposta. O objeto de resposta deve ser compatível com JSON.stringify.

O exemplo de função a seguir verifica um URL e retorna o código de status para o invocador.

CommonJS module handler
exemplo – Solicitação HTTP com 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)); }); };
ES module handler
exemplo – Solicitação HTTP com 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)); }); }

No próximo exemplo, a resposta do Amazon S3 é retornada ao invocador assim que fica disponível. O tempo limite em execução no loop de evento é congelado e continuará sendo executado na próxima vez que a função for invocada.

nota

Antes de usar esse exemplo, verifique se o perfil de execução da sua função tem permissões de leitura do Amazon S3.

CommonJS module handler
exemplo — AWS SDK v2 com callbackWaitsFor EmptyEventLoop

Este exemplo usa AWS SDK for JavaScript v2, que está incluído no runtime do Lambda para 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); };
ES module handler
exemplo — AWS SDK v3 com callbackWaitsFor EmptyEventLoop

Este exemplo usa AWS SDK for JavaScript v3, que está disponível no runtime 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); };