# Criar funções do Lambda com Node.js É possível executar o código JavaScript com Node.js no AWS Lambda. O Lambda fornece [runtimes](lambda-runtimes.md) para Node.js que executam seu código para processar eventos. Seu código é executado em um ambiente que inclui o AWS SDK para JavaScript, com as credenciais de uma função do AWS Identity and Access Management (IAM) que você gerencia. Para saber mais sobre as versões do SDK incluídas nos runtimes do Node.js, consulte [Versões do SDK incluídas no runtime](#nodejs-sdk-included). O Lambda oferece suporte aos runtimes Node.js a seguir. | Nome | Identificador | Sistema operacional | Data da substituição | Bloquear a criação de funções | Bloquear a atualização de funções | | --- | --- | --- | --- | --- | --- | | Node.js 24 | `nodejs24.x` | Amazon Linux 2023 | 30 de abril de 2028 | 1º de junho de 2028 | 1º de julho de 2028 | | Node.js 22 | `nodejs22.x` | Amazon Linux 2023 | 30 de abril de 2027 | 1º de junho de 2027 | 1º de julho de 2027 | | Node.js 20 | `nodejs20.x` | Amazon Linux 2023 | 30 de abril de 2026 | 31 de agosto de 2026 | 30 de setembro de 2026 | **Para criar uma função em Node.js.** 1. Abra o [console do lambda](https://console.aws.amazon.com/lambda). 1. Escolha a opção **Criar função**. 1. Configure as seguintes opções: + **Nome da função**: digite um nome para a função. + **Runtime**: escolha **Node.js 24.x**. 1. Escolha a opção **Criar função**. O console cria uma função do Lambda com um único arquivo de origem chamado `index.mjs`. É possível editar esse arquivo e adicionar mais arquivos no editor de códigos integrado. Na seção **DEPLOY**, escolha **Implantar** para atualizar o código da função. Em seguida, para executar seu código, escolha **Criar evento de teste** na seção **TEST EVENTS**. O arquivo `index.mjs` exporta uma função chamada `handler` que utiliza um objeto de evento e um objeto de contexto. Esta é a [função de manipulador](nodejs-handler.md) que o Lambda chama quando a função é invocada. O runtime da função do Node.js recebe eventos de invocação do Lambda e os transmite ao manipulador. Na configuração da função, o valor do manipulador é `index.handler`. Quando você salva seu código de função, o console do Lambda cria um pacote de implantação de arquivos .zip. Quando desenvolver o código de função fora do console (usando um IDE), você precisará [criar um pacote de implantação](nodejs-package.md) para carregar o código na função do Lambda. O runtime transmite um objeto de contexto para o manipulador, além do evento de invocação. O [objeto de contexto](nodejs-context.md) contém informações adicionais sobre a invocação, a função e o ambiente de execução. Outras informações estão disponíveis de variáveis de ambiente. Sua função do Lambda é fornecida com um grupo de logs do CloudWatch Logs. O runtime envia detalhes sobre cada invocação para o CloudWatch Logs. Ele retransmite quaisquer [logs que sua função produz](nodejs-logging.md) durante a invocação. Se a função retornar um erro, o Lambda formatará o erro e o retornará para o invocador. **Topics** + [ ## Versões do SDK incluídas no runtime ](#nodejs-sdk-included) + [ ## Usar o keep-alive para conexões TCP ](#nodejs-keep-alive) + [ ## Carregamento de certificado de CA ](#nodejs-certificate-loading) + [ ## Atributos experimentais do Node.js ](#nodejs-experimental-features) + [ # Definir o manipulador de função do Lambda em Node.js ](nodejs-handler.md) + [ # Implantar funções do Lambda em Node.js com arquivos .zip ](nodejs-package.md) + [ # Implantar funções do Lambda em Node.js com imagens de contêiner ](nodejs-image.md) + [ # Trabalho com camadas para funções do Lambda com Node.js ](nodejs-layers.md) + [ # Usar o objeto de contexto do Lambda para recuperar informações das funções em Node.js ](nodejs-context.md) + [ # Registrar em log e monitorar funções do Lambda em Node.js ](nodejs-logging.md) + [ # Instrumentação do código Node.js no AWS Lambda ](nodejs-tracing.md) ## Versões do SDK incluídas no runtime Todos os [runtimes Node.js do Lambda compatíveis](#nodejs-supported-runtimes) incluem uma versão secundária específica do AWS SDK para JavaScript v3, e não a [versão mais recente](https://github.com/aws/aws-sdk-js-v3/releases). A versão secundária específica incluída no runtime depende da versão do runtime e do seu Região da AWS. Para encontrar a versão específica do SDK incluída no runtime que você está usando, crie uma função do Lambda com o código a seguir. **Example index.mjs** ``` import packageJson from '@aws-sdk/client-s3/package.json' with { type: 'json' }; export const handler = async () => ({ version: packageJson.version }); ``` Uma resposta é retornada no seguinte formato: ``` { "version": "3.632.0" } ``` Para obter mais informações, consulte [Usar o SDK para JavaScript v3 em seu manipulador](nodejs-handler.md#nodejs-example-sdk-usage). ## Usar o keep-alive para conexões TCP O agente Node.js HTTP/HTTPS padrão cria uma nova conexão TCP para cada nova solicitação. Para evitar o custo de estabelecer novas conexões, o keep-alive é habilitado por padrão em todos os [runtimes Node.js com suporte](#nodejs-supported-runtimes). O Keep-alive pode reduzir os tempos de solicitação de funções do Lambda que fazem várias chamadas de API usando o SDK. Para desativar o keep-alive, consulte [Reusing connections with keep-alive in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html) no *Guia do desenvolvedor do AWS SDK para JavaScript 3.x*. Para obter mais informações sobre como usar o keep-alive, consulte [HTTP keep-alive is on by default in modular AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/http-keep-alive-is-on-by-default-in-modular-aws-sdk-for-javascript/) no Blog de ferramentas da AWS para o desenvolvedor. ## Carregamento de certificado de CA Até a versão do runtime do Node.js 18, o Lambda carrega automaticamente certificados de CA (autoridade de certificação) específicos da Amazon para facilitar a criação de funções que interagem com outros Serviços da AWS. Por exemplo, o Lambda inclui os certificados do Amazon RDS necessários para validar o [certificado de identidade do servidor](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html) instalado no banco de dados do Amazon RDS. Esse comportamento pode ter um impacto na performance durante inicializações a frio. A partir do Node.js 20, o Lambda não carrega mais certificados de CA adicionais por padrão. O runtime do Node.js 20 contém um arquivo de certificado com todos os certificados de CA da Amazon localizado em `/var/runtime/ca-cert.pem`. Para restaurar o mesmo comportamento do Node.js 18 e de runtimes anteriores, defina a [variável de ambiente](configuration-envvars.md) `NODE_EXTRA_CA_CERTS` como `/var/runtime/ca-cert.pem`. Para otimizar a performance, recomendamos que você agrupe somente os certificados de que precisa com o pacote de implantação e carregue-os usando a variável de ambiente `NODE_EXTRA_CA_CERTS`. O arquivo de certificados deve consistir em um ou mais certificados de CA raiz ou intermediários confiáveis no formato PEM. Por exemplo, para o RDS, inclua os certificados necessários junto com seu código como `certificates/rds.pem`. Em seguida, carregue os certificados configurando `NODE_EXTRA_CA_CERTS` como`/var/task/certificates/rds.pem`. ## Atributos experimentais do Node.js As versões upstream da linguagem Node.js habilitam certos recursos experimentais por padrão. O Lambda desabilita esses recursos para garantir estabilidade em runtime e performance consistente. A tabela a seguir lista os recursos experimentais desabilitados pelo Lambda. | Recurso experimental | Versões compatíveis do Node.js | Sinalizador do Node.js aplicado pelo Lambda | Sinalizador do Lambda para habilitar novamente | | --- | --- | --- | --- | | Suporte para importar módulos usando require em módulos do ES | Node.js 20, Node.js 22 | `--no-experimental-require-module` | `--experimental-require-module` | | Suporte para detecção automática de módulos do ES versus CommonJS | Node.js 22 | `--no-experimental-detect-module` | `--experimental-detect-module` | Para habilitar um recurso experimental desabilitado, defina o sinalizador de reativação na variável de ambiente `NODE_OPTIONS`. Por exemplo, para habilitar o suporte a require do módulo do ES, defina `NODE_OPTIONS` como `--experimental-require-module`. O Lambda detecta essa substituição e remove o sinalizador de desabilitação correspondente. **Importante** O uso de recursos experimentais pode resultar em instabilidade e problemas de performance. Esses recursos podem ser modificados ou removidos em futuras versões do Node.js. Funções que utilizam recursos experimentais não estão qualificadas para o Acordo de serviço (SLA) ou AWS Support do Lambda. # Definir o manipulador de função do 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. Esta página descreve como trabalhar com manipuladores de função do Lambda em Node.js, incluindo opções para a configuração de projeto, as convenções de nomenclatura e as práticas recomendadas. Além disso, esta página apresenta um exemplo de uma função do Lambda em Node.js que aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon Simple Storage Service (Amazon S3). Para obter mais informações sobre como implantar a função após gravá-la, consulte [Implantar funções do Lambda em Node.js com arquivos .zip](nodejs-package.md) ou [Implantar funções do Lambda em Node.js com imagens de contêiner](nodejs-image.md). **Topics** + [ ## Configuração do projeto de manipulador em Node.js ](#nodejs-handler-setup) + [ ## Exemplo de código da função do Lambda em Node.js ](#nodejs-example-code) + [ ## Módulos CommonJS e ES ](#nodejs-commonjs-es-modules) + [ ## Inicialização do Node.js ](#nodejs-initialization) + [ ## Convenções de nomenclatura para manipuladores ](#nodejs-handler-naming) + [ ## Definição e acesso ao objeto do evento de entrada ](#nodejs-example-input) + [ ## Padrões de manipulador válidos para funções Node.js ](#nodejs-handler-signatures) + [ ## Usar o SDK para JavaScript v3 em seu manipulador ](#nodejs-example-sdk-usage) + [ ## Acesso a variáveis de ambiente ](#nodejs-example-envvars) + [ ## Usar o estado global ](#nodejs-handler-state) + [ ## Práticas recomendadas de código para as funções do Lambda em Node.js ](#nodejs-best-practices) ## Configuração do projeto de manipulador em Node.js Há várias maneiras de inicializar um projeto Lambda em Node.js. Por exemplo, é possível criar um projeto Node.js padrão usando o `npm`, criar uma [aplicação do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/using-sam-cli-init.html#using-sam-cli-init-new), ou criar uma [aplicação do AWS CDK](lambda-cdk-tutorial.md#lambda-cdk-step-1). Para criar um projeto usando o `npm`: ``` npm init ``` Este comando inicializa seu projeto e gera um arquivo `package.json` que gerencia os metadados e as dependências do projeto. O código da função função reside em um arquivo JavaScript `.js` ou `.mjs`. No exemplo a seguir, chamamos esse arquivo de `index.mjs` porque ele usa um manipulador de módulo ES. O Lambda oferece suporte a manipuladores de módulo ES e CommonJS. Para obter mais informações, consulte [Módulos CommonJS e ES](#nodejs-commonjs-es-modules). Um projeto típico de função do Lambda em Node.js segue esta estrutura geral: ``` /project-root ├── index.mjs — Contains main handler ├── package.json — Project metadata and dependencies ├── package-lock.json — Dependency lock file └── node_modules/ — Installed dependencies ``` ## Exemplo de código da função do Lambda em Node.js O exemplo de código apresentado a seguir para uma função do Lambda em Node.js aceita informações sobre um pedido, produz um recibo em formato de texto e armazena esse arquivo em um bucket do Amazon S3. **Example Função do Lambda index.mjs** ``` import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; // Initialize the S3 client outside the handler for reuse const s3Client = new S3Client(); /** * Lambda handler for processing orders and storing receipts in S3. * @param {Object} event - Input event containing order details * @param {string} event.order_id - The unique identifier for the order * @param {number} event.amount - The order amount * @param {string} event.item - The item purchased * @returns {Promise} Success message */ export const handler = async(event) => { try { // Access environment variables const bucketName = process.env.RECEIPT_BUCKET; if (!bucketName) { throw new Error('RECEIPT_BUCKET environment variable is not set'); } // Create the receipt content and key destination const receiptContent = `OrderID: ${event.order_id}\nAmount: $${event.amount.toFixed(2)}\nItem: ${event.item}`; const key = `receipts/${event.order_id}.txt`; // Upload the receipt to S3 await uploadReceiptToS3(bucketName, key, receiptContent); console.log(`Successfully processed order ${event.order_id} and stored receipt in S3 bucket ${bucketName}`); return 'Success'; } catch (error) { console.error(`Failed to process order: ${error.message}`); throw error; } }; /** * Helper function to upload receipt to S3 * @param {string} bucketName - The S3 bucket name * @param {string} key - The S3 object key * @param {string} receiptContent - The content to upload * @returns {Promise} */ async function uploadReceiptToS3(bucketName, key, receiptContent) { try { const command = new PutObjectCommand({ Bucket: bucketName, Key: key, Body: receiptContent }); await s3Client.send(command); } catch (error) { throw new Error(`Failed to upload receipt to S3: ${error.message}`); } } ``` Este arquivo `index.mjs` contém as seguintes seções de código: + Bloco `import`: utilize este bloco para incluir as bibliotecas necessárias para a função do Lambda, como [clientes do AWS SDK](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/the-request-object.html). + Declaração de `const s3Client`: inicializa um [cliente do Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) fora da função do manipulador. Isso faz com que o Lambda execute esse código durante a [fase de inicialização](lambda-runtime-environment.md#runtimes-lifecycle-ib), e o cliente é preservado para [reutilização em várias invocações](lambda-runtime-environment.md#execution-environment-reuse). + Bloco de comentários JSDoc: defina os tipos de entrada e saída para seu manipulador usando [anotações JSDoc](https://jsdoc.app/about-getting-started). + `export const handler`: esta é a função de manipulação principal invocada pelo Lambda. Ao implantar sua função, especifique `index.handler` para a propriedade [Handler](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler). O valor da propriedade `Handler` é o nome do arquivo e o nome do método do manipulador exportado, separados por um ponto. + Função `uploadReceiptToS3`: uma função auxiliar referenciada pela função do manipulador principal. Para que esta função funcione corretamente, seu [ perfil de execução](lambda-intro-execution-role.md) deve permitir a ação `s3:PutObject`. Além disso, certifique-se de definir a variável de ambiente `RECEIPT_BUCKET`. Após uma invocação com êxito, o bucket do Amazon S3 deve conter um arquivo de recibo. ## Módulos CommonJS e ES O Node.js oferece suporte a dois sistemas de módulos, CommonJS e ECMAScript (módulos ES). O Lambda recomenda o uso de módulos ES, pois eles oferecem suporte à espera de alto nível, o que permite que tarefas assíncronas sejam concluídas durante a [inicialização do ambiente de execução](#nodejs-initialization). O Node.js trata arquivos com uma extensão de nome de arquivo `.cjs` como módulos CommonJS, enquanto uma extensão `.mjs` denota módulos ES. Por padrão, o Node.js trata arquivos com a extensão do nome de arquivo `.js` como módulos CommonJS. É possível configurar o Node.js para tratar arquivos `.js` como módulos ES especificando o `type` como `module` no arquivo `package.json` da função. É possível configurar o Node.js no Lambda para detectar automaticamente se um arquivo `.js` deve ser tratado como CommonJS ou como um módulo ES adicionando o sinalizador `—experimental-detect-module` à variável de ambiente `NODE_OPTIONS`. Para obter mais informações, consulte [Recursos experimentais do Node.js](lambda-nodejs.md#nodejs-experimental-features). Os exemplos a seguir mostram manipuladores de funções escritos usando módulos ES e módulos CommonJS. Todos os exemplos restantes nesta página usam módulos ES. ------ #### [ ES module example ] **Example – Manipulador de módulos ES** ``` const url = "https://aws.amazon.com/"; export const handler = async(event) => { try { const res = await fetch(url); console.info("status", res.status); return res.status; } catch (e) { console.error(e); return 500; } }; ``` ------ #### [ CommonJS module example ] **Example – Manipulador de módulos CommonJS** ``` 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; }; ``` ------ ## Inicialização do Node.js O Node.js utiliza um modelo de E/S sem bloqueio que oferece suporte a operações assíncronas eficientes usando um loop de eventos. Por exemplo, se o Node.js fizer uma chamada de rede, a função continuará processando outras operações sem bloquear uma resposta da rede. Quando a resposta da rede é recebida, ela é colocada na fila de retorno de chamada. As tarefas da fila são processadas quando a tarefa atual é concluída. O Lambda recomenda usar espera de alto nível para que as tarefas assíncronas iniciadas durante a inicialização do ambiente de execução sejam concluídas durante a inicialização. As tarefas assíncronas que não são concluídas durante a inicialização geralmente são executadas durante a primeira chamada da função. Isso pode causar comportamento inesperado ou erros. Por exemplo, sua inicialização de função pode fazer uma chamada de rede para buscar um parâmetro da AWS Parameter Store. Se essa tarefa não for concluída durante a inicialização, o valor poderá ser nulo durante uma invocação. Também pode haver um atraso entre a inicialização e a invocação, o que pode gerar erros em operações sensíveis a tempo. Em especial, as chamadas de serviço da AWS podem depender de assinaturas de solicitação sensíveis a tempo, resultando em falhas se a chamada de serviço não for concluída durante a fase de inicialização. A conclusão de tarefas durante a inicialização geralmente melhora a performance da inicialização a frio e a performance da primeira invocação ao usar a simultaneidade provisionada. Para obter mais informações, consulte a postagem no nosso blog [Uso de módulos ES do Node.js e de espera em nível superior no AWS Lambda](https://aws.amazon.com/blogs/compute/using-node-js-es-modules-and-top-level-await-in-aws-lambda). ## Convenções de nomenclatura para manipuladores Quando você [configura uma função](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-Handler), o valor da configuração do Handler é o nome do arquivo e o nome do módulo do handler exportado, separados por um ponto. O padrão para as funções criadas no console e para os exemplos deste guia é `index.handler`. Isso indica o método de `handler` que é exportado do arquivo `index.js` ou `index.mjs`. Se você criar uma função no console usando um nome de arquivo ou nome de manipulador de funções diferente, deverá editar o nome do manipulador padrão. **Para alterar o nome do manipulador de funções (console)** 1. Abra a página [Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e escolha sua função. 1. Escolha a guia **Código**. 1. Role para baixo até o painel **Configurações de runtime** e escolha **Editar**. 1. Em **Manipulador**, insira o novo nome para seu manipulador de funções. 1. Escolha **Salvar**. ## Definição e acesso ao objeto do evento de entrada O formato de entrada JSON é o mais comum e padrão para funções do Lambda. Neste exemplo, a função espera uma entrada semelhante à seguinte: ``` { "order_id": "12345", "amount": 199.99, "item": "Wireless Headphones" } ``` Ao trabalhar com funções do Lambda em Node.js, é possível definir o formato do evento de entrada esperado usando anotações JSDoc. Neste exemplo, definimos a estrutura de entrada no comentário JSDoc do manipulador: ``` /** * Lambda handler for processing orders and storing receipts in S3. * @param {Object} event - Input event containing order details * @param {string} event.order_id - The unique identifier for the order * @param {number} event.amount - The order amount * @param {string} event.item - The item purchased * @returns {Promise} Success message */ ``` Depois de definir esses tipos em seu comentário JSDoc, você poderá acessar os campos do objeto de evento diretamente no código. Por exemplo, `event.order_id` recupera o valor de `order_id` da entrada original. ## Padrões de manipulador válidos para funções Node.js Recomendamos usar [async/await](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-async-await.html) para declarar o manipulador da função em vez de usar [retornos de chamada](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/using-a-callback-function.html). O uso de async/await é uma forma concisa e legível de escrever código assíncrono em Node.js, sem a necessidade de usar 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. ### manipuladores de funções assíncronas (recomendados) 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. O manipulador aceita os seguintes argumentos: + `event`: contém os dados de entrada passados para sua função. + `context`: contém informações sobre a invocação, a função e o ambiente de execução. Para obter mais informações, consulte [Usar o objeto de contexto do Lambda para recuperar informações das funções em Node.js](nodejs-context.md). As assinaturas válidas para o padrão async/await são: ``` export const handler = async (event) => { }; ``` ``` export const handler = async (event, context) => { }; ``` ### Manipuladores de funções síncronas Quando sua função não executa nenhuma tarefa assíncrona, é possível usar um manipulador de função síncrona, usando uma das assinaturas de função a seguir: ``` export const handler = (event) => { }; ``` ``` export const handler = (event, context) => { }; ``` ### Manipuladores de função de streaming de resposta O Lambda oferece suporte ao streaming de resposta com Node.js. Os manipuladores de funções de streaming de resposta usam o decorador `awslambda.streamifyResponse()` e recebem 3 parâmetros: `event`, `responseStream` e `context`. A assinatura da função é: ``` export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => { }); ``` Para obter mais informações, consulte [Streaming de resposta para funções do Lambda](configuration-response-streaming.md). ### Manipuladores de funções baseadas em retorno de chamada **nota** Só há suporte para os manipuladores de funções baseadas em retorno de chamada até o Node.js 22. A partir do Node.js 24, as tarefas assíncronas devem ser implementadas usando manipuladores de funções assíncronas. Os manipuladores de funções baseadas em retorno de chamada devem usar os argumentos de evento, contexto e retorno de chamada. Exemplo: ``` export const handler = (event, context, callback) => { }; ``` A função de retorno de chamada espera um `Error` e uma resposta, que deve ser serializável em JSON. A função continuará em execução até que o [loop de evento](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/) 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. É possível configurar o runtime para enviar a resposta imediatamente, definindo [context.callbackWaitsForEmptyEventLoop](nodejs-context.md) como false. **Example – Solicitação HTTP com callback** O exemplo de função a seguir verifica um URL e retorna o código de status para o invocador. ``` import https from "https"; let url = "https://aws.amazon.com/"; export const handler = (event, context, callback) => { https.get(url, (res) => { callback(null, res.statusCode); }).on("error", (e) => { callback(Error(e)); }); }; ``` ## Usar o SDK para JavaScript v3 em seu manipulador Frequentemente, você usará as funções do Lambda para interagir com ou fazer atualizações em outros recursos da AWS. A maneira mais simples de interagir com esses recursos é usar o AWS SDK para JavaScript. Todos os [runtimes Node.js do Lambda compatíveis](lambda-nodejs.md#nodejs-supported-runtimes) incluem o [SDK para JavaScript versão 3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/). No entanto, recomendamos fortemente que você inclua os clientes do AWS SDK necessários em seu pacote de implantação. Isso maximiza a [compatibilidade com versões anteriores](runtimes-update.md#runtime-update-compatibility) durante futuras atualizações do runtime do Lambda. Confie apenas no SDK fornecido com o runtime quando não puder incluir pacotes adicionais (por exemplo, ao usar o editor de código do console do Lambda ou código embutido em um modelo do AWS CloudFormation). Para adicionar as dependências do SDK à sua função, use o comando `npm install` para os clientes específicos do SDK que você precisa. No código de exemplo, usamos o [cliente do Amazon S3](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/). Adicione essa dependência executando o seguinte comando no diretório que contém seu arquivos `package.json`: ``` npm install @aws-sdk/client-s3 ``` No código da função, importe o cliente e os comandos necessários, conforme demonstrado na função de exemplo: ``` import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; ``` Em seguida, inicialize um [cliente do Amazon S3:](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/) ``` const s3Client = new S3Client(); ``` Neste exemplo, inicializamos nosso cliente do Amazon S3 fora da função do manipulador principal para evitar a necessidade que inicializá-lo a cada vez que nossa função é invocada. Após inicializar o cliente do SDK, você poderá usá-lo para fazer chamadas de API para esse serviço da AWS. O código de exemplo chama a API [PutObject](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/PutObjectCommand/) do Amazon S3 da seguinte forma: ``` const command = new PutObjectCommand({ Bucket: bucketName, Key: key, Body: receiptContent }); ``` ## Acesso a variáveis de ambiente No código do manipulador, você pode fazer referência a quaisquer [variáveis de ambiente](configuration-envvars.md) usando o método `process.env`. Neste exemplo, referenciamos a variável de ambiente `RECEIPT_BUCKET` definida usando as seguintes linhas de código: ``` // Access environment variables const bucketName = process.env.RECEIPT_BUCKET; if (!bucketName) { throw new Error('RECEIPT_BUCKET environment variable is not set'); } ``` ## Usar o estado global O Lambda executa seu código estático durante a [fase de inicialização](lambda-runtime-environment.md#runtimes-lifecycle-ib) antes de invocar a função pela primeira vez. Os recursos criados durante a inicialização permanecem na memória entre as invocações, para que você possa evitar ter que criá-los toda vez que invocar sua função. No código de exemplo, o código de inicialização do cliente do S3 está fora do manipulador. O runtime inicializa o cliente antes que a função manipule seu primeiro evento e o cliente permanece disponível para reutilização em todas as invocações. ## Práticas recomendadas de código para as funções do Lambda em Node.js Siga estas diretrizes ao criar funções do Lambda: + **Separe o manipulador do Lambda da lógica central.** Isso permite que você crie uma função mais fácil para teste de unidade. + **Controle as dependências no pacote de implantação da função. ** O ambiente de execução do AWS Lambda contém várias bibliotecas. Para os runtimes em Node.js e Python, os AWS SDKs estão incluídos. Para habilitar o conjunto de recursos e atualizações de segurança mais recente, o Lambda atualizará periodicamente essas bibliotecas. Essas atualizações podem introduzir alterações sutis ao comportamento de sua função do Lambda. Para ter controle total das dependências usadas por sua função, empacote todas as dependências em seu pacote de implantação. + **Minimize a complexidade de suas dependências.** Prefira frameworks mais simples que sejam carregados rapidamente no startup do [ambiente de execução](lambda-runtime-environment.md). + **Minimize o tamanho do pacote de implantação para conter somente o necessário para o runtime. ** Isso reduzirá a quantidade de tempo necessária para que seu pacote de implantação seja obtido por download e desempacotado antes da invocação. **Aproveite a reutilização do ambiente de execução para melhorar a performance da função.** Inicialize clientes SDK e conexões de banco de dados fora do manipulador de funções e armazene em cache os ativos estáticos localmente no diretório `/tmp`. As invocações subsequentes processadas pela mesma instância da função podem reutilizar esses recursos. Isso economiza custos reduzindo o runtime da função. Para evitar possíveis vazamentos de dados entre invocações, não use o ambiente de execução para armazenar dados do usuário, eventos ou outras informações com implicações de segurança. Se sua função depende de um estado mutável que não pode ser armazenado na memória dentro do manipulador, considere criar uma função separada ou versões separadas de uma função para cada usuário. **Use uma diretiva de keep-alive para manter conexões persistentes.** O Lambda limpa conexões ociosas ao longo do tempo. A tentativa de reutilizar uma conexão ociosa ao invocar uma função resultará em um erro de conexão. Para manter sua conexão persistente, use a diretiva keep-alive associada ao runtime. Para obter um exemplo, consulte [Reutilizar conexões com keep-alive em Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-reusing-connections.html). **Use [variáveis de ambiente](configuration-envvars.md) para passar parâmetros operacionais para sua função.** Por exemplo, se estiver gravando em um bucket do Amazon S3, em vez fixar no código o nome do bucket em que você está gravando, configure o nome do bucket como uma variável de ambiente. **Evite usar invocações recursivas** em sua função do Lambda, em que a função invoca a si mesma ou inicia um processo que pode invocar a função novamente. Isso pode levar a um volume não intencional de invocações da função e a custos elevados. Se você observar um volume não intencional de invocações, defina a simultaneidade reservada da função como `0` imediatamente para limitar todas as invocações da função enquanto atualiza o código. **Não use APIs não documentadas e não públicas** no código da função do Lambda. Para os tempos de execução gerenciados pelo AWS Lambda, o Lambda aplica periodicamente atualizações funcionais e de segurança às APIs internas do Lambda. Essas atualizações internas da API podem ser incompatíveis com versões anteriores, gerando consequências não intencionais, como falhas de invocação, caso sua função tenha dependência nessas APIs não públicas. Consulte [a referência da API](https://docs.aws.amazon.com/lambda/latest/api/welcome.html) para obter uma lista de APIs disponíveis publicamente. **Escreva um código idempotente.** Escrever um código idempotente para suas funções garante que eventos duplicados sejam tratados da mesma maneira. Seu código deve validar eventos adequadamente e lidar corretamente com eventos duplicados. Para obter mais informações, consulte [Como torno minha função do Lambda idempotente?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-function-idempotent/). # Implantar funções do Lambda em Node.js com arquivos .zip O código da função do AWS Lambda compreende um arquivo .js ou .mjs contendo o código do manipulador da função, juntamente com quaisquer pacotes e módulos adicionais dos quais o código dependa. Para implantar o código dessa função no Lambda, você usa um *pacote de implantação*. Esse pacote pode ser um arquivo .zip ou uma imagem de contêiner. Para obter mais informações sobre como usar imagens de contêiner com Node.js, consulte [Implantar funções do Lambda em Node.js com imagens de contêiner](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-image.html). Para criar um pacote de implantação como arquivo .zip, você pode usar um utilitário de arquivo .zip integrado da ferramenta da linha de comando ou qualquer outro utilitário de arquivo .zip, como o [7zip](https://www.7-zip.org/download.html). Os exemplos mostrados nas seções a seguir pressupõem que você esteja usando uma ferramenta `zip` da linha de comando em um ambiente Linux ou MacOS. Para usar os mesmos comandos no Windows, você pode [instalar o Subsistema Windows para Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) para obter uma versão do Ubuntu e do Bash integrada ao Windows. Observe que o Lambda usa permissões de arquivo POSIX, então pode ser necessário [definir permissões para a pasta do pacote de implantação](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-deployment-package-errors/) antes da criação do arquivo .zip. **Topics** + [ ## Dependências de runtime em Node.js ](#nodejs-package-dependencies) + [ ## Criar um pacote de implantação .zip sem dependências ](#nodejs-package-create-no-dependencies) + [ ## Criar um pacote de implantação .zip com dependências ](#nodejs-package-create-dependencies) + [ ## Criar uma camada Node.js para suas dependências ](#nodejs-package-dependencies-layers) + [ ## Caminho de pesquisa de dependências e bibliotecas incluídas no runtime ](#nodejs-package-searchpath) + [ ## Criação e atualização de funções do Lambda em Node.js usando arquivos .zip ](#nodejs-package-create-update) ## Dependências de runtime em Node.js Para funções do Lambda que usam o runtime do Node.js, uma dependência pode ser qualquer módulo Node.js. O runtime do Node.js inclui várias bibliotecas conhecidas, bem como uma versão do AWS SDK para JavaScript. Todos os [runtime Node.js compatíveis](lambda-nodejs.md#nodejs-supported-runtimes) incluem a versão 3 do SDK. Para usar a versão 2 do SDK, você deve adicionar o SDK ao seu pacote de implantação de arquivo .zip. Para encontrar a versão específica do SDK incluída no tempo de execução que você está usando, consulte [Versões do SDK incluídas no runtime](lambda-nodejs.md#nodejs-sdk-included). O Lambda atualiza periodicamente as bibliotecas do SDK no runtime do Node.js para incluir os recursos e upgrades de segurança mais recentes. O Lambda também aplica patches de segurança e atualizações às outras bibliotecas inclusas no runtime. Para ter controle total das dependências em seu pacote, é possível adicionar a versão preferencial de qualquer dependência inclusa no runtime ao pacote de implantação. Por exemplo, se você deseja usar uma versão específica do SDK para JavaScript, pode incluí-la no arquivo .zip como uma dependência. Para obter mais informações sobre como adicionar dependências inclusas no runtime ao arquivo .zip, consulte [Caminho de pesquisa de dependências e bibliotecas incluídas no runtime](#nodejs-package-searchpath). No [modelo de responsabilidade compartilhada da AWS](lambda-runtimes.md#runtimes-shared-responsibility), você é responsável pelo gerenciamento de todas as dependências dos pacotes de implantação das suas funções. Isso inclui a aplicação de atualizações e patches de segurança. Para atualizar as dependências no pacote de implantação da função, primeiro crie um novo arquivo .zip e depois carregue esse arquivo no Lambda. Consulte [Criar um pacote de implantação .zip com dependências](#nodejs-package-create-dependencies) e [Criação e atualização de funções do Lambda em Node.js usando arquivos .zip](#nodejs-package-create-update) para obter mais informações. ## Criar um pacote de implantação .zip sem dependências Se o código de função não tiver dependências, exceto para as bibliotecas inclusas no runtime do Lambda, o arquivo .zip conterá somente o arquivo `index.js` ou `index.mjs` com o código do manipulador da função. Use seu utilitário zip preferencial para criar um arquivo .zip com o arquivo `index.js` ou `index.mjs` na raiz. Se o arquivo que contém o código do manipulador não estiver na raiz do arquivo .zip, o Lambda não poderá executar o código. Para saber como implantar o arquivo .zip para criar uma função do Lambda ou atualizar uma já existente, consulte  [Criação e atualização de funções do Lambda em Node.js usando arquivos .zip](#nodejs-package-create-update). ## Criar um pacote de implantação .zip com dependências Se o código de função depender de pacotes ou módulos que não estejam inclusos no runtime do Node.js do Lambda, é possível adicionar essas dependências ao arquivo .zip com o código de função ou usar uma [camada do Lambda](chapter-layers.md). As instruções desta seção mostram como incluir as dependências no pacote de implantação .zip. Para obter instruções sobre como incluir suas dependências em uma camada, consulte [Criar uma camada Node.js para suas dependências](#nodejs-package-dependencies-layers). Os comandos de exemplo da CLI a seguir criam um arquivo .zip denominado `my_deployment_package.zip` contendo o arquivo `index.js` ou `index.mjs` com o código do manipulador da função e as dependências. No exemplo, você instala as dependências usando o gerenciador de pacotes npm. **Para criar o pacote de implantação** 1. Navegue até o diretório do projeto que contém seu arquivo de código-fonte `index.js` ou `index.mjs`. Neste exemplo, o diretório se chama `my_function`. ``` cd my_function ``` 1. Instale as bibliotecas necessárias para a função no diretório `node_modules` usando o comando `npm install`. Neste exemplo, você instala o AWS X-Ray SDK for Node.js. ``` npm install aws-xray-sdk ``` Isso cria uma estrutura de pastas semelhante à seguinte: ``` ~/my_function ├── index.mjs └── node_modules ├── async ├── async-listener ├── atomic-batcher ├── aws-sdk ├── aws-xray-sdk ├── aws-xray-sdk-core ``` Também é possível adicionar módulos personalizados criados por você ao pacote de implantação. Crie um diretório em `node_modules` com o nome do seu módulo e salve seus pacotes personalizados gravados nesse diretório. 1. Crie um arquivo .zip que contenha o conteúdo da pasta do seu projeto na raiz. Use a opção `r` (recursiva) para garantir que zip compacte as subpastas. ``` zip -r my_deployment_package.zip . ``` ## Criar uma camada Node.js para suas dependências As instruções nesta seção mostram como incluir suas dependências em uma camada. Para obter instruções sobre como incluir suas dependências em seu pacote de implantação, consulte [Criar um pacote de implantação .zip com dependências](#nodejs-package-create-dependencies). Quando você adiciona uma camada a uma função, o Lambda carrega o conteúdo da camada no diretório `/opt` desse ambiente de execução. Para cada runtime do Lambda, a variável `PATH` já inclui caminhos de pasta específica no diretório `/opt`. Para garantir que o Lambda colete o conteúdo da camada, o arquivo .zip da camada deve ter suas dependências em um dos seguintes caminhos de pasta: + `nodejs/node_modules` + `nodejs/node18/node_modules (NODE_PATH)` + `nodejs/node20/node_modules (NODE_PATH)` + `nodejs/node22/node_modules (NODE_PATH)` Por exemplo, sua estrutura de arquivo .zip da sua camada pode ser assim: ``` xray-sdk.zip └ nodejs/node_modules/aws-xray-sdk ``` Além disso, o Lambda detecta automaticamente todas as bibliotecas no diretório `/opt/lib` e quaisquer binários no diretório `/opt/bin`. Para garantir que o Lambda encontre corretamente o conteúdo da sua camada, você também pode criar uma camada com a seguinte estrutura: ``` custom-layer.zip └ lib | lib_1 | lib_2 └ bin | bin_1 | bin_2 ``` Depois de empacotar sua camada, consulte [Criar e excluir camadas no Lambda](creating-deleting-layers.md) e [Adicionar camadas às funções](adding-layers.md) para concluir sua configuração de camada. ## Caminho de pesquisa de dependências e bibliotecas incluídas no runtime O runtime do Node.js inclui várias bibliotecas conhecidas, bem como uma versão do AWS SDK para JavaScript. Se você desejar usar uma versão diferente de uma biblioteca inclusa no runtime, poderá fazer isso ao empacotá-la com a função ou adicioná-la como uma dependência no pacote de implantação. Por exemplo, você pode usar uma versão diferente do SDK ao adicioná-la ao pacote de implantação .zip. Também é possível incluí-la em uma [camada do Lambda](chapter-layers.md) para a função. Quando você usa uma instrução `import` ou `require` em seu código, o runtime do Node.js pesquisa os diretórios no caminho `NODE_PATH` até localizar o módulo. Por padrão, o primeiro local que o runtime pesquisa é o diretório no qual o pacote de implantação .zip é descompactado e montado (`/var/task`). Se você incluir uma versão de uma biblioteca incluída no runtime do pacote de implantação, essa versão terá precedência sobre a versão incluída no runtime. As dependências do pacote de implantação também têm precedência sobre as dependências das camadas. Quando você adiciona uma dependência a uma camada, o Lambda a extrai para `/opt/nodejs/nodexx/node_modules`, em que `nodexx` representa a versão do runtime que você está usando. No caminho de pesquisa, esse diretório tem precedência sobre o diretório que contém as bibliotecas incluídas no runtime (`/var/lang/lib/node_modules`). As bibliotecas em camadas da função, portanto, têm precedência sobre as versões incluídas no runtime. É possível visualizar o caminho de pesquisa completo para a função do Lambda ao adicionar a linha de código a seguir. ``` console.log(process.env.NODE_PATH) ``` Você também pode adicionar dependências em uma pasta separada dentro do pacote .zip. Por exemplo, você pode adicionar um módulo personalizado a uma pasta no pacote .zip chamada `common`. Quando o pacote .zip é descompactado e montado, essa pasta é colocada dentro do diretório `/var/task`. Para usar uma dependência de uma pasta no pacote de implantação .zip em seu código, use uma instrução `import { } from` ou `const { } = require()`, com base no seu uso da resolução do módulo CJS ou ESM. Por exemplo: ``` import { myModule } from './common' ``` Se você empacotar o código com `esbuild`, `rollup` ou similares, as dependências usadas por sua função serão empacotadas em um ou mais arquivos. Recomendamos usar esse método para comercializar dependências sempre que possível. Em comparação com a adição de dependências ao pacote de implantação, o empacotamento do código resulta em melhor performance devido à redução nas operações de E/S. ## Criação e atualização de funções do Lambda em Node.js usando arquivos .zip Depois de criar o pacote de implantação .zip, você poderá usá-lo para criar uma função do Lambda ou atualizar uma existente. É possível implantar o pacote .zip usando o console do Lambda, a AWS Command Line Interface e a API do Lambda. Você também pode criar e atualizar funções do Lambda usando o AWS Serverless Application Model (AWS SAM) e o CloudFormation. O tamanho máximo de um pacote de implantação .zip para o Lambda é 250 MB (descompactado). Esse limite se aplica ao tamanho combinado de todos os arquivos que você carrega, inclusive qualquer camada do Lambda. O runtime do Lambda precisa de permissão para ler os arquivos no pacote de implantação. Na notação octal de permissões do Linux, o Lambda precisa de 644 permissões para arquivos não executáveis (rw-r--r--) e 755 permissões (rwxr-xr-x) para diretórios e arquivos executáveis. No Linux e no MacOS, use o comando `chmod` para alterar as permissões de arquivo em arquivos e diretórios do seu pacote de implantação. Por exemplo, para dar a um arquivo não executável as permissões corretas, execute o comando a seguir. ``` chmod 644 ``` Para alterar as permissões de arquivo no Windows, consulte [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) na documentação do Microsoft Windows. **nota** Se você não conceder ao Lambda as permissões necessárias para acessar diretórios no seu pacote de implantação, o Lambda definirá as permissões desses diretórios como 755 (rwxr-xr-x). ### Criar e atualizar funções com arquivos .zip usando o console Para criar uma nova função, você deve primeiro criar a função no console e depois carregar o arquivo .zip. Para atualizar uma função existente, abra a página da função e siga o mesmo procedimento para adicionar o arquivo .zip atualizado. Se o arquivo .zip for menor que 50 MB, você poderá criar ou atualizar uma função carregando o arquivo diretamente da máquina local. Para arquivos .zip maiores que 50 MB, você deve primeiro carregar o pacote para um bucket do Amazon S3. Para obter instruções sobre como carregar um arquivo para um bucket do Amazon S3 usando o Console de gerenciamento da AWS, consulte [Conceitos básicos do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html). Para carregar arquivos usando a AWS CLI, consulte [Mover objetos](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) no *Guia do usuário da AWS CLI*. **nota** Você não pode alterar o [tipo de pacote de implantação](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html#lambda-CreateFunction-request-PackageType) (.zip ou imagem de contêiner) de uma função existente. Por exemplo, você não pode converter uma função de imagem de contêiner para usar um arquivo compactado .zip. É necessário criar uma nova função. **Para criar uma função (console)** 1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e escolha **Criar função**. 1. Escolha **Author from scratch** (Criar do zero). 1. Em **Basic information** (Informações básicas), faça o seguinte: 1. Em **Nome da função**, insira o nome da função. 1. Em **Runtime**, selecione o runtime que você deseja usar. 1. (Opcional) Em **Arquitetura**, escolha a arquitetura do conjunto de instruções para a função. O valor da arquitetura padrão é X86\$164. Certifique-se de que o pacote de implantação .zip da função seja compatível com a arquitetura do conjunto de instruções que você escolheu. 1. (Opcional) Em **Permissões**, expanda **Alterar função de execução padrão**. Crie uma **função de execução** ou use uma existente. 1. Escolha a opção **Criar função**. O Lambda cria uma função básica “Hello world” usando o runtime escolhido. **Você pode carregar o arquivo .zip da máquina local (console)** 1. Na [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console Lambda, escolha a função para a qual você deseja carregar o arquivo .zip. 1. Selecione a guia **Código**. 1. No painel do **Código-fonte**, escolha **Carregar de**. 1. Escolha o **arquivo .zip**. 1. Para carregar o arquivo .zip, faça o seguinte: 1. Selecione **Carregar** e, em seguida, selecione o arquivo .zip no seletor de arquivos. 1. Escolha **Open (Abrir)**. 1. Escolha **Salvar**. **Para carregar um arquivo .zip de um bucket do Amazon S3 (console)** 1. Na [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda, escolha a função para a qual você deseja carregar um novo arquivo .zip. 1. Selecione a guia **Código**. 1. No painel do **Código-fonte**, escolha **Carregar de**. 1. Escolha **Local do Amazon S3**. 1. Cole o URL do link do Amazon S3 do arquivo .zip e escolha **Salvar**. ### Atualizar funções do arquivo .zip usando o editor de código do console Para algumas funções com pacotes de implantação .zip, você pode usar o editor de código integrado do console do Lambda para atualizar o código da função diretamente. Para usar esse recurso, a função deve atender aos seguintes critérios: + A função deve usar um dos runtimes da linguagem interpretada (Python, Node.js ou Ruby) + O pacote de implantação da função precisa ter menos de 50 MB (sem compactação). O código das funções com pacotes de implantação de imagens de contêiner não pode ser editado diretamente no console. **Para atualizar o código da função usando o editor de código do console** 1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda e selecione a função. 1. Selecione a guia **Código**. 1. No painel **Código-fonte**, selecione o arquivo de código-fonte e edite-o no editor de código integrado. 1. Na seção **DEPLOY**, escolha **Implantar** para atualizar o código da função: ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/getting-started-tutorial/deploy-console.png) ### Criar e atualizar funções com arquivos .zip usando a AWS CLI Você pode usar a [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) para criar uma função ou atualizar uma existente usando um arquivo .zip. Use os comandos [create-function](https://docs.aws.amazon.com/cli/latest/reference/lambda/create-function.html) e [update-function-code](https://docs.aws.amazon.com/cli/latest/reference/lambda/create-function.html) para implantar o pacote .zip. Se o arquivo .zip for menor que 50 MB, você poderá carregar o pacote .zip de um local do arquivo na máquina de compilação local. Para arquivos .zip maiores, você deve carregar o pacote .zip de um bucket do Amazon S3. Para obter instruções sobre como carregar um arquivo para um bucket do Amazon S3 usando a AWS CLI, consulte [Mover objetos](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) no *Guia do usuário da AWS CLI*. **nota** Se você carregar o arquivo .zip de um bucket do Amazon S3 usando a AWS CLI, o bucket deverá estar na mesma Região da AWS que sua função. Para criar uma função usando um arquivo .zip com a AWS CLI, você deve especificar o seguinte: + O nome da função (`--function-name`) + O runtime da função (`--runtime`) + O nome do recurso da Amazon (ARN) da [função de execução](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html) da função (`--role`) + O nome do método do manipulador no código da função (`--handler`) Você também deve especificar a local do arquivo .zip. Se o arquivo .zip estiver localizado em uma pasta da máquina de compilação local, use a opção `--zip-file` para especificar o caminho do arquivo, conforme mostrado no comando do exemplo a seguir. ``` aws lambda create-function --function-name myFunction \ --runtime nodejs24.x --handler index.handler \ --role arn:aws:iam::111122223333:role/service-role/my-lambda-role \ --zip-file fileb://myFunction.zip ``` Para especificar o local do arquivo .zip em um bucket do Amazon S3, use a opção `--code` conforme mostrado no comando do exemplo a seguir. Você só precisa usar o parâmetro `S3ObjectVersion` para objetos com versionamento. ``` aws lambda create-function --function-name myFunction \ --runtime nodejs24.x --handler index.handler \ --role arn:aws:iam::111122223333:role/service-role/my-lambda-role \ --code S3Bucket=amzn-s3-demo-bucket,S3Key=myFileName.zip,S3ObjectVersion=myObjectVersion ``` Para atualizar uma função existente usando a CLI, especifique o nome da função usando o parâmetro `--function-name`. Você também deve especificar o local do arquivo .zip que deseja usar para atualizar o código da função. Se o arquivo .zip estiver localizado em uma pasta da máquina de compilação local, use a opção `--zip-file` para especificar o caminho do arquivo, conforme mostrado no comando do exemplo a seguir. ``` aws lambda update-function-code --function-name myFunction \ --zip-file fileb://myFunction.zip ``` Para especificar o local do arquivo .zip em um bucket do Amazon S3, use as opções `--s3-bucket` e `--s3-key` conforme mostrado no comando do exemplo a seguir. Você só precisa usar o parâmetro `--s3-object-version` para objetos com versionamento. ``` aws lambda update-function-code --function-name myFunction \ --s3-bucket amzn-s3-demo-bucket --s3-key myFileName.zip --s3-object-version myObject Version ``` ### Criar e atualizar funções com arquivos .zip usando a API do Lamba Para criar e atualizar funções usando um arquivo .zip, use as seguintes operações de API: + [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) + [UpdateFunctionCode](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionCode.html) ### Criar e atualizar funções com arquivos .zip usando o AWS SAM O AWS Serverless Application Model (AWS SAM) é um kit de ferramentas que ajuda a simplificar o processo de criação e execução de aplicações com tecnologia sem servidor na AWS. Você define os recursos para a aplicação em um modelo YAML ou JSON e usa a interface da linha de comando do AWS SAM (CLI do AWS SAM) para criar, empacotar e implantar aplicações. Quando você cria uma função do Lambda com base em um modelo do AWS SAM, o AWS SAM cria automaticamente um pacote de implantação .zip ou uma imagem de contêiner com o código da função e quaisquer dependências que você especificar. Para saber mais sobre como usar o AWS SAM para criar e implantar funções do Lambda, consulte [Conceitos básicos do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-getting-started.html) no *Guia do desenvolvedor do AWS Serverless Application Model*. Você também pode usar o AWS SAM para criar uma função do Lambda usando um arquivo .zip existente. Para criar uma função do Lambda usando o AWS SAM, salve o arquivo .zip em um bucket do Amazon S3 ou em uma pasta local na máquina de compilação. Para obter instruções sobre como carregar um arquivo para um bucket do Amazon S3 usando a AWS CLI, consulte [Mover objetos](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) no *Guia do usuário da AWS CLI*. No modelo do AWS SAM, o recurso `AWS::Serverless::Function` especifica a função do Lambda. Nesse recurso, defina as seguintes propriedades para criar uma função usando um arquivo .zip: + `PackageType`: definir como `Zip` + `CodeUri`: definir como o URI do Amazon S3 do código da função, o caminho para a pasta local ou o objeto [FunctionCode](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-property-function-functioncode.html) + `Runtime`: definir como o runtime escolhido Com o AWS SAM, se o arquivo .zip for maior que 50 MB, você não precisará carregá-lo primeiro em um bucket do Amazon S3. O AWS SAM poderá carregar pacotes .zip com o tamanho máximo permitido de 250 MB (descompactados) de um local da máquina de compilação local. Para saber mais sobre a implantação de funções usando o arquivo .zip no AWS SAM, consulte [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) no *Guia do desenvolvedor do AWS SAM*. ### Criar e atualizar funções com arquivos .zip usando o CloudFormation Você pode usar o CloudFormation para criar uma função do Lambda usando um arquivo .zip. Para criar uma função do Lambda de um arquivo.zip, primeiro carregue o arquivo em um bucket do Amazon S3. Para obter instruções sobre como carregar um arquivo para um bucket do Amazon S3 usando a AWS CLI, consulte [Mover objetos](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-objects-move) no *Guia do usuário da AWS CLI. * No modelo do CloudFormation, o recurso `AWS::Lambda::Function` especifica a função do Lambda. Nesse recurso, defina as seguintes propriedades para criar uma função usando um arquivo .zip: + `PackageType`: definir como `Zip` + `Code`: inserir o nome do bucket do Amazon S3 e o nome do arquivo .zip nos campos `S3Bucket` e `S3Key` + `Runtime`: definir como o runtime escolhido O arquivo .zip que o CloudFormation gera não pode exceder 4 MB. Para saber mais sobre a implantação de funções usando o arquivo .zip no CloudFormation, consulte [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) no *Guia do desenvolvedor do CloudFormation*. # Implantar funções do Lambda em Node.js com imagens de contêiner Existem três maneiras de criar uma imagem de contêiner para uma função do Lambda em Node.js: + [Usar uma imagem base da AWS para Node.js](#nodejs-image-instructions) As [imagens base da AWS](images-create.md#runtimes-images-lp) são pré-carregadas com um  runtime de linguagem, um cliente de interface de runtime para gerenciar a interação entre o Lambda e o código da sua função e um emulador de interface de runtime para testes locais. + [Usar uma imagem base somente para sistema operacional da AWS](images-create.md#runtimes-images-provided) [As imagens base somente para sistema operacional da AWS](https://gallery.ecr.aws/lambda/provided) contêm uma distribuição do Amazon Linux e o [emulador de interface de runtime](https://github.com/aws/aws-lambda-runtime-interface-emulator/). Essas imagens são comumente usadas para criar imagens de contêiner para linguagens compiladas, como [Go](go-image.md#go-image-provided) e [Rust](lambda-rust.md) e para uma linguagem ou versão de linguagem para a qual o Lambda não fornece uma imagem base, como Node.js 19. Você também pode usar imagens base somente para sistema operacional para implementar um [runtime personalizado](runtimes-custom.md). Para tornar a imagem compatível com o Lambda, você deve incluir [o cliente de interface de runtime para Node.js](#nodejs-image-clients) na imagem. + [Usar uma imagem base que não é da AWS](#nodejs-image-clients) Você também pode usar uma imagem base alternativa de outro registro de contêiner, como Alpine Linux ou Debian. Você também pode usar uma imagem personalizada criada por sua organização. Para tornar a imagem compatível com o Lambda, você deve incluir [o cliente de interface de runtime para Node.js](#nodejs-image-clients) na imagem. **dica** Para reduzir o tempo necessário para que as funções do contêiner do Lambda se tornem ativas, consulte [Use multi-stage builds](https://docs.docker.com/build/building/multi-stage/) na documentação do Docker. Para criar imagens de contêiner eficientes, siga as [Melhores práticas para gravar Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/). Esta página explica como criar, testar e implantar imagens de contêiner para o Lambda. **Topics** + [ ## Imagens base da AWS para Node.js ](#nodejs-image-base) + [ ## Usar uma imagem base da AWS para Node.js ](#nodejs-image-instructions) + [ ## Usar uma imagem base alternativa com o cliente da interface de runtime ](#nodejs-image-clients) ## Imagens base da AWS para Node.js A AWS oferece as seguintes imagens base para Node.js: | Tags | Runtime | Sistema operacional | Dockerfile | Desaprovação | | --- | --- | --- | --- | --- | | 24 | Node.js 24 | Amazon Linux 2023 | [Dockerfile para Node.js 24 no GitHub](https://github.com/aws/aws-lambda-base-images/blob/nodejs24.x/Dockerfile.nodejs24.x) | 30 de abril de 2028 | | 22 | Node.js 22 | Amazon Linux 2023 | [Dockerfile para Node.js 22 no GitHub](https://github.com/aws/aws-lambda-base-images/blob/nodejs22.x/Dockerfile.nodejs22.x) | 30 de abril de 2027 | | 20 | Node.js 20 | Amazon Linux 2023 | [Dockerfile para Node.js 20 no GitHub](https://github.com/aws/aws-lambda-base-images/blob/nodejs20.x/Dockerfile.nodejs20.x) | 30 de abril de 2026 | Repositório do Amazon ECR: [gallery.ecr.aws/lambda/nodejs](https://gallery.ecr.aws/lambda/nodejs) As imagens base do Node.js 20 e posteriores são baseadas na [imagem de contêiner mínimo do Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/minimal-container.html). Imagens base anteriores usam o Amazon Linux 2. O AL2023 oferece várias vantagens em relação ao Amazon Linux 2, incluindo uma área de implantação menor e versões atualizadas de bibliotecas, como `glibc`. As imagens baseadas no AL2023 usam o `microdnf` (com link simbólico `dnf`) como o gerenciador de pacotes, em vez do `yum`, que é o gerenciador de pacotes padrão no Amazon Linux 2. O `microdnf` é uma implementação autônoma do `dnf`. Para obter uma lista dos pacotes incluídos nas imagens baseadas no AL2023, consulte as colunas **Contêiner mínimo** em [Comparar pacotes instalados em imagens de contêiner do Amazon Linux 2023](https://docs.aws.amazon.com/linux/al2023/ug/al2023-container-image-types.html). Para obter mais informações sobre as diferenças entre o AL2023 e o Amazon Linux 2, consulte [Introdução ao runtime do Amazon Linux 2023 para AWS Lambda](https://aws.amazon.com/blogs/compute/introducing-the-amazon-linux-2023-runtime-for-aws-lambda/) no blog AWS Compute. **nota** Para executar imagens baseadas no AL2023 localmente, inclusive com o AWS Serverless Application Model (AWS SAM), você deve usar o Docker versão 20.10.10 ou posterior. ## Usar uma imagem base da AWS para Node.js ### Pré-requisitos Para executar as etapas desta seção, você deve ter o seguinte: + [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + [Docker](https://docs.docker.com/get-docker) (versão mínima 25.0.0) + O plug-in [buildx](https://github.com/docker/buildx/blob/master/README.md) do Docker. + Node.js ### Criação de uma imagem a partir de uma imagem base **Para criar uma imagem de contêiner a partir de uma imagem base da AWS para Node.js** 1. Crie um diretório para o projeto e depois mude para esse diretório. ``` mkdir example cd example ``` 1. Crie um novo projeto Node.js com o `npm`. Para aceitar as opções padrão fornecidas na experiência interativa, pressione `Enter`. ``` npm init ``` 1. Crie um novo arquivo chamado `index.js`. É possível adicionar o exemplo de código de função a seguir ao arquivo para testes ou usar o seu próprio código. **Example Manipulador CommonJS** ``` exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from Lambda!'), }; return response; }; ``` 1. Se a função depender de outras bibliotecas que não o AWS SDK para JavaScript, use o [npm](https://www.npmjs.com/) para adicioná-las ao seu pacote. 1. Crie um novo Dockerfile com a seguinte configuração: + Defina a propriedade `FROM` como o [URI da imagem base](https://gallery.ecr.aws/lambda/nodejs). + Use o comando COPY para copiar o código da função e as dependências do runtime para `{LAMBDA_TASK_ROOT}`, uma [variável de ambiente definida pelo Lambda](configuration-envvars.md#configuration-envvars-runtime). + Defina o argumento `CMD` como o manipulador de funções do Lambda. Observe que o Dockerfile de exemplo não inclui uma [instrução USER](https://docs.docker.com/reference/dockerfile/#user). Quando você implanta uma imagem de contêiner no Lambda, o Lambda define automaticamente um usuário padrão do Linux com permissões de privilégio mínimo. Isso é diferente do comportamento padrão do Docker, que adota o usuário `root` como padrão quando nenhuma instrução `USER` é fornecida. **Example Dockerfile** ``` FROM public.ecr.aws/lambda/nodejs:22 # Copy function code COPY index.js ${LAMBDA_TASK_ROOT} # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "index.handler" ] ``` 1. Crie a imagem do Docker com o comando [docker build](https://docs.docker.com/engine/reference/commandline/build/). O exemplo a seguir nomeia a imagem como `docker-image` e atribui a ela a [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) `test`. Para tornar sua imagem compatível com o Lambda, é necessário usar a opção `--provenance=false`. ``` docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test . ``` **nota** O comando especifica a opção `--platform linux/amd64` para garantir que seu contêiner seja compatível com o ambiente de execução do Lambda, independentemente da arquitetura da sua máquina de compilação. Se você pretende criar uma função do Lambda usando a arquitetura do conjunto de instruções ARM64, certifique-se de alterar o comando para usar a opção `--platform linux/arm64` em vez disso. ### (Opcional) Teste a imagem localmente 1. Inicie a imagem do Docker com o comando **docker run**. Neste exemplo, `docker-image` é o nome da imagem e `test` é a tag. ``` docker run --platform linux/amd64 -p 9000:8080 docker-image:test ``` Esse comando executa a imagem como um contêiner e cria um endpoint local em `localhost:9000/2015-03-31/functions/function/invocations`. **nota** Se você criou a imagem do Docker para a arquitetura do conjunto de instruções ARM64, certifique-se de usar a opção `--platform linux/arm64`, em vez de `--platform linux/amd64`. 1. Em uma nova janela de terminal, publique um evento no endpoint local. ------ #### [ Linux/macOS ] No Linux e no MacOS, execute o seguinte comando `curl`: ``` curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}' ``` Esse comando invoca a função com um evento vazio e retorna uma resposta. Caso esteja usando seu próprio código de função em vez do código de função de exemplo, você talvez queira invocar a função com uma carga útil JSON. Exemplo: ``` curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}' ``` ------ #### [ PowerShell ] No PowerShell, execute o seguinte comando `Invoke-WebRequest`: ``` Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json" ``` Esse comando invoca a função com um evento vazio e retorna uma resposta. Caso esteja usando seu próprio código de função em vez do código de função de exemplo, você talvez queira invocar a função com uma carga útil JSON. Exemplo: ``` Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json" ``` ------ 1. Obtenha o ID do contêiner. ``` docker ps ``` 1. Use o comando [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) para parar o contêiner. Nesse comando, substitua `3766c4ab331c` pelo ID do contêiner da etapa anterior. ``` docker kill 3766c4ab331c ``` ### Implantação da imagem **Para enviar a imagem ao Amazon ECR e criar a função do Lambda** 1. Execute o comando [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html) para autenticar a CLI do Docker no seu registro do Amazon ECR. + Defina o valor `--region` para a Região da AWS onde você deseja criar o repositório do Amazon ECR. + Substituir `111122223333` por seu ID da Conta da AWS. ``` aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com ``` 1. Crie um repositório no Amazon ECR usando o comando [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html). ``` aws ecr create-repository --repository-name hello-world --region us-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE ``` **nota** O repositório do Amazon ECR deve estar na mesma Região da AWS que a função do Lambda. Se tiver êxito, você verá uma resposta como esta: ``` { "repository": { "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } } ``` 1. Copie o `repositoryUri` da saída na etapa anterior. 1. Execute o comando [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) para aplicar uma tag na sua imagem local em seu repositório do Amazon ECR como a versão mais recente. Neste comando: + `docker-image:test` é o nome e a [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) da sua imagem do Docker. Esse é o nome e a tag da imagem que você especificou no comando `docker build`. + Substitua `` pelo `repositoryUri` que você copiou. Certifique-se de incluir `:latest` no final do URI. ``` docker tag docker-image:test :latest ``` Exemplo: ``` docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest ``` 1. Execute o comando [docker push](https://docs.docker.com/engine/reference/commandline/push/) para implantar a imagem local no repositório do Amazon ECR. Certifique-se de incluir `:latest` no final do URI do repositório. ``` docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest ``` 1. [Crie um perfil de execução](lambda-intro-execution-role.md#permissions-executionrole-api) para a função, caso ainda não tenha um. Você precisará do nome do recurso da Amazon (ARN) do perfil na próxima etapa. 1. Criar a função do Lambda. Em `ImageUri`, especifique o URI do repositório anterior. Certifique-se de incluir `:latest` no final do URI. ``` aws lambda create-function \ --function-name hello-world \ --package-type Image \ --code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \ --role arn:aws:iam::111122223333:role/lambda-ex ``` **nota** É possível criar uma função usando uma imagem em uma conta da AWS diferente desde que a imagem esteja na mesma região da função do Lambda. Para obter mais informações, consulte [Permissões entre contas do Amazon ECR](images-create.md#configuration-images-xaccount-permissions). 1. Invoque a função. ``` aws lambda invoke --function-name hello-world response.json ``` Você obterá uma resposta parecida com esta: ``` { "ExecutedVersion": "$LATEST", "StatusCode": 200 } ``` 1. Para ver a saída da função, verifique o arquivo `response.json`. Para atualizar o código da função, você deve criar a imagem novamente, fazer upload da nova imagem no repositório do Amazon ECR e, em seguida, usar o comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) para implantar a imagem na função do Lambda. O Lambda resolve a tag de imagem em um resumo de imagem específico. Isso significa que, se você apontar a tag de imagem que foi usada para implantar a função em uma nova imagem no Amazon ECR, o Lambda não atualizará automaticamente a função para usar a nova imagem. Para implantar a nova imagem na mesma função do Lambda, você deverá usar o comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html), mesmo que a tag da imagem no Amazon ECR permaneça a mesma. No exemplo a seguir, a opção `--publish` cria uma nova versão da função usando a imagem de contêiner atualizada. ``` aws lambda update-function-code \ --function-name hello-world \ --image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \ --publish ``` ## Usar uma imagem base alternativa com o cliente da interface de runtime Se você usar uma [imagem base somente para sistema operacional](images-create.md#runtimes-images-provided) ou uma imagem base alternativa, deverá incluir o cliente de interface de runtime na imagem. O cliente de interface de runtime estende [API de runtime](runtimes-api.md), que gerencia a interação entre o Lambda e o código da sua função. Instale o [cliente de interface de runtime em Node.js](https://www.npmjs.com/package/aws-lambda-ric) usando o gerenciador de pacotes npm: ``` npm install aws-lambda-ric ``` Você também pode fazer download do [cliente de interface de runtime Node.js](https://github.com/aws/aws-lambda-nodejs-runtime-interface-client) no GitHub. O exemplo a seguir demonstra como criar uma imagem de contêiner para Node.js usando uma imagem base que não é da AWS. O exemplo de Dockerfile usa a imagem base da `bookworm`. O Dockerfile inclui o cliente de interface de runtime. ### Pré-requisitos Para executar as etapas desta seção, você deve ter o seguinte: + [AWS CLI versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + [Docker](https://docs.docker.com/get-docker) (versão mínima 25.0.0) + O plug-in [buildx](https://github.com/docker/buildx/blob/master/README.md) do Docker. + Node.js ### Criar uma imagem de uma imagem base alternativa **Para criar uma imagem de contêiner de uma imagem base que não é da AWS** 1. Crie um diretório para o projeto e depois mude para esse diretório. ``` mkdir example cd example ``` 1. Crie um novo projeto Node.js com o `npm`. Para aceitar as opções padrão fornecidas na experiência interativa, pressione `Enter`. ``` npm init ``` 1. Crie um novo arquivo chamado `index.js`. É possível adicionar o exemplo de código de função a seguir ao arquivo para testes ou usar o seu próprio código. **Example Manipulador CommonJS** ``` exports.handler = async (event) => { const response = { statusCode: 200, body: JSON.stringify('Hello from Lambda!'), }; return response; }; ``` 1. Crie um novo Dockerfile. O Dockerfile a seguir usa uma imagem base de `bookworm` em vez de uma [imagem base da AWS](images-create.md#runtimes-images-lp). O Dockerfile inclui o [cliente de interface de runtime](https://www.npmjs.com/package/aws-lambda-ric), o que torna a imagem compatível com o Lambda. O Dockerfile usa uma [compilação em vários estágios](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#use-multi-stage-builds). O primeiro estágio cria uma imagem de compilação, que é um ambiente Node.js padrão em que as dependências da função são instaladas. O segundo estágio cria uma imagem mais fina que inclui o código da função e suas dependências. Isso reduz o tamanho final da imagem. + Defina a propriedade `FROM` como o identificador da imagem base. + Use o comando `COPY` para copiar o código da função e as dependências do runtime. + Defina o `ENTRYPOINT` como o módulo em que você deseja que o contêiner do Docker seja executado quando for iniciado. Nesse caso, o módulo é o cliente de interface de runtime. + Defina o argumento `CMD` como o manipulador de funções do Lambda. Observe que o Dockerfile de exemplo não inclui uma [instrução USER](https://docs.docker.com/reference/dockerfile/#user). Quando você implanta uma imagem de contêiner no Lambda, o Lambda define automaticamente um usuário padrão do Linux com permissões de privilégio mínimo. Isso é diferente do comportamento padrão do Docker, que adota o usuário `root` como padrão quando nenhuma instrução `USER` é fornecida. **Example Dockerfile** ``` # Define custom function directory ARG FUNCTION_DIR="/function" FROM node:20-bookworm as build-image # Include global arg in this stage of the build ARG FUNCTION_DIR # Install build dependencies RUN apt-get update && \ apt-get install -y \ g++ \ make \ cmake \ unzip \ libcurl4-openssl-dev # Copy function code RUN mkdir -p ${FUNCTION_DIR} COPY . ${FUNCTION_DIR} WORKDIR ${FUNCTION_DIR} # Install Node.js dependencies RUN npm install # Install the runtime interface client RUN npm install aws-lambda-ric # Grab a fresh slim copy of the image to reduce the final size FROM node:20-bookworm-slim # Required for Node runtimes which use npm@8.6.0+ because # by default npm writes logs under /home/.npm and Lambda fs is read-only ENV NPM_CONFIG_CACHE=/tmp/.npm # Include global arg in this stage of the build ARG FUNCTION_DIR # Set working directory to function root directory WORKDIR ${FUNCTION_DIR} # Copy in the built dependencies COPY --from=build-image ${FUNCTION_DIR} ${FUNCTION_DIR} # Set runtime interface client as default command for the container runtime ENTRYPOINT ["/usr/local/bin/npx", "aws-lambda-ric"] # Pass the name of the function handler as an argument to the runtime CMD ["index.handler"] ``` 1. Crie a imagem do Docker com o comando [docker build](https://docs.docker.com/engine/reference/commandline/build/). O exemplo a seguir nomeia a imagem como `docker-image` e atribui a ela a [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) `test`. Para tornar sua imagem compatível com o Lambda, é necessário usar a opção `--provenance=false`. ``` docker buildx build --platform linux/amd64 --provenance=false -t docker-image:test . ``` **nota** O comando especifica a opção `--platform linux/amd64` para garantir que seu contêiner seja compatível com o ambiente de execução do Lambda, independentemente da arquitetura da sua máquina de compilação. Se você pretende criar uma função do Lambda usando a arquitetura do conjunto de instruções ARM64, certifique-se de alterar o comando para usar a opção `--platform linux/arm64` em vez disso. ### (Opcional) Teste a imagem localmente Use o [emulador de interface de runtime](https://github.com/aws/aws-lambda-runtime-interface-emulator/) para testar a imagem localmente. É possível [compilar o emulador em sua imagem](https://github.com/aws/aws-lambda-runtime-interface-emulator/?tab=readme-ov-file#build-rie-into-your-base-image) ou usar o procedimento a seguir instalá-lo na sua máquina local. **Para instalar o emulador de interface de runtime na sua máquina local** 1. No diretório do projeto, execute o comando a seguir para baixar o emulador de interface de runtime (arquitetura x86-64) do GitHub e instalá-lo na sua máquina local. ------ #### [ Linux/macOS ] ``` mkdir -p ~/.aws-lambda-rie && \ curl -Lo ~/.aws-lambda-rie/aws-lambda-rie https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie && \ chmod +x ~/.aws-lambda-rie/aws-lambda-rie ``` Para instalar o emulador arm64, substitua o URL do repositório do GitHub no comando anterior pelo seguinte: ``` https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64 ``` ------ #### [ PowerShell ] ``` $dirPath = "$HOME\.aws-lambda-rie" if (-not (Test-Path $dirPath)) { New-Item -Path $dirPath -ItemType Directory } $downloadLink = "https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie" $destinationPath = "$HOME\.aws-lambda-rie\aws-lambda-rie" Invoke-WebRequest -Uri $downloadLink -OutFile $destinationPath ``` Para instalar o emulador de arm64, substitua `$downloadLink` pelo seguinte: ``` https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/aws-lambda-rie-arm64 ``` ------ 1. Inicie a imagem do Docker com o comando **docker run**. Observe o seguinte: + `docker-image` é o nome da imagem e `test` é a tag. + `/usr/local/bin/npx aws-lambda-ric index.handler` é o `ENTRYPOINT` seguido pelo `CMD` do Dockerfile. ------ #### [ Linux/macOS ] ``` docker run --platform linux/amd64 -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \ --entrypoint /aws-lambda/aws-lambda-rie \ docker-image:test \ /usr/local/bin/npx aws-lambda-ric index.handler ``` ------ #### [ PowerShell ] ``` docker run --platform linux/amd64 -d -v "$HOME\.aws-lambda-rie:/aws-lambda" -p 9000:8080 ` --entrypoint /aws-lambda/aws-lambda-rie ` docker-image:test ` /usr/local/bin/npx aws-lambda-ric index.handler ``` ------ Esse comando executa a imagem como um contêiner e cria um endpoint local em `localhost:9000/2015-03-31/functions/function/invocations`. **nota** Se você criou a imagem do Docker para a arquitetura do conjunto de instruções ARM64, certifique-se de usar a opção `--platform linux/arm64`, em vez de `--platform linux/amd64`. 1. Publique um evento no endpoint local. ------ #### [ Linux/macOS ] No Linux e no MacOS, execute o seguinte comando `curl`: ``` curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}' ``` Esse comando invoca a função com um evento vazio e retorna uma resposta. Caso esteja usando seu próprio código de função em vez do código de função de exemplo, você talvez queira invocar a função com uma carga útil JSON. Exemplo: ``` curl "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"payload":"hello world!"}' ``` ------ #### [ PowerShell ] No PowerShell, execute o seguinte comando `Invoke-WebRequest`: ``` Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{}' -ContentType "application/json" ``` Esse comando invoca a função com um evento vazio e retorna uma resposta. Caso esteja usando seu próprio código de função em vez do código de função de exemplo, você talvez queira invocar a função com uma carga útil JSON. Exemplo: ``` Invoke-WebRequest -Uri "http://localhost:9000/2015-03-31/functions/function/invocations" -Method Post -Body '{"payload":"hello world!"}' -ContentType "application/json" ``` ------ 1. Obtenha o ID do contêiner. ``` docker ps ``` 1. Use o comando [docker kill](https://docs.docker.com/engine/reference/commandline/kill/) para parar o contêiner. Nesse comando, substitua `3766c4ab331c` pelo ID do contêiner da etapa anterior. ``` docker kill 3766c4ab331c ``` ### Implantação da imagem **Para enviar a imagem ao Amazon ECR e criar a função do Lambda** 1. Execute o comando [get-login-password](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/get-login-password.html) para autenticar a CLI do Docker no seu registro do Amazon ECR. + Defina o valor `--region` para a Região da AWS onde você deseja criar o repositório do Amazon ECR. + Substituir `111122223333` por seu ID da Conta da AWS. ``` aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 111122223333.dkr.ecr.us-east-1.amazonaws.com ``` 1. Crie um repositório no Amazon ECR usando o comando [create-repository](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecr/create-repository.html). ``` aws ecr create-repository --repository-name hello-world --region us-east-1 --image-scanning-configuration scanOnPush=true --image-tag-mutability MUTABLE ``` **nota** O repositório do Amazon ECR deve estar na mesma Região da AWS que a função do Lambda. Se tiver êxito, você verá uma resposta como esta: ``` { "repository": { "repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/hello-world", "registryId": "111122223333", "repositoryName": "hello-world", "repositoryUri": "111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world", "createdAt": "2023-03-09T10:39:01+00:00", "imageTagMutability": "MUTABLE", "imageScanningConfiguration": { "scanOnPush": true }, "encryptionConfiguration": { "encryptionType": "AES256" } } } ``` 1. Copie o `repositoryUri` da saída na etapa anterior. 1. Execute o comando [docker tag](https://docs.docker.com/engine/reference/commandline/tag/) para aplicar uma tag na sua imagem local em seu repositório do Amazon ECR como a versão mais recente. Neste comando: + `docker-image:test` é o nome e a [tag](https://docs.docker.com/engine/reference/commandline/build/#tag) da sua imagem do Docker. Esse é o nome e a tag da imagem que você especificou no comando `docker build`. + Substitua `` pelo `repositoryUri` que você copiou. Certifique-se de incluir `:latest` no final do URI. ``` docker tag docker-image:test :latest ``` Exemplo: ``` docker tag docker-image:test 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest ``` 1. Execute o comando [docker push](https://docs.docker.com/engine/reference/commandline/push/) para implantar a imagem local no repositório do Amazon ECR. Certifique-se de incluir `:latest` no final do URI do repositório. ``` docker push 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest ``` 1. [Crie um perfil de execução](lambda-intro-execution-role.md#permissions-executionrole-api) para a função, caso ainda não tenha um. Você precisará do nome do recurso da Amazon (ARN) do perfil na próxima etapa. 1. Criar a função do Lambda. Em `ImageUri`, especifique o URI do repositório anterior. Certifique-se de incluir `:latest` no final do URI. ``` aws lambda create-function \ --function-name hello-world \ --package-type Image \ --code ImageUri=111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \ --role arn:aws:iam::111122223333:role/lambda-ex ``` **nota** É possível criar uma função usando uma imagem em uma conta da AWS diferente desde que a imagem esteja na mesma região da função do Lambda. Para obter mais informações, consulte [Permissões entre contas do Amazon ECR](images-create.md#configuration-images-xaccount-permissions). 1. Invoque a função. ``` aws lambda invoke --function-name hello-world response.json ``` Você obterá uma resposta parecida com esta: ``` { "ExecutedVersion": "$LATEST", "StatusCode": 200 } ``` 1. Para ver a saída da função, verifique o arquivo `response.json`. Para atualizar o código da função, você deve criar a imagem novamente, fazer upload da nova imagem no repositório do Amazon ECR e, em seguida, usar o comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html) para implantar a imagem na função do Lambda. O Lambda resolve a tag de imagem em um resumo de imagem específico. Isso significa que, se você apontar a tag de imagem que foi usada para implantar a função em uma nova imagem no Amazon ECR, o Lambda não atualizará automaticamente a função para usar a nova imagem. Para implantar a nova imagem na mesma função do Lambda, você deverá usar o comando [update-function-code](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-code.html), mesmo que a tag da imagem no Amazon ECR permaneça a mesma. No exemplo a seguir, a opção `--publish` cria uma nova versão da função usando a imagem de contêiner atualizada. ``` aws lambda update-function-code \ --function-name hello-world \ --image-uri 111122223333.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest \ --publish ``` # Trabalho com camadas para funções do Lambda com Node.js Use [camadas do Lambda](chapter-layers.md) para empacotar o código e as dependências que você quiser reutilizar em várias funções. As camadas geralmente contêm dependências de biblioteca, um [runtime personalizado](runtimes-custom.md) ou arquivos de configuração. A criação de uma camada envolve três etapas gerais: 1. Empacotar o conteúdo da sua camada. Isso significa criar um arquivo .zip contendo as dependências que você deseja usar em suas funções. 1. Criar a camada no Lambda. 1. Adicionar a camada às suas funções. **Topics** + [ ## Empacotar o conteúdo da sua camada ](#nodejs-layers-package) + [ ## Criar a camada no Lambda ](#publishing-layer) + [ ## Adicionar a camada à função ](#nodejs-layer-adding) + [ ## Aplicação de amostra ](#nodejs-layer-sample-app) ## Empacotar o conteúdo da sua camada Para criar uma camada, reúna os pacotes em um arquivo .zip que atenda aos seguintes requisitos: + Crie a camada usando a mesma versão do Node.js que você planeja usar para a função do Lambda. Por exemplo, se você compilar a camada usando o Node.js 24, use o runtime do Node.js 24 para a função. + O arquivo .zip da camada deve usar uma destas estruturas de diretório: + `nodejs/node_modules` + `nodejs/nodeX/node_modules` (em que *X* é a versão do Node.js, como `node22`) Para obter mais informações, consulte [Caminhos da camada para cada runtime do Lambda](packaging-layers.md#packaging-layers-paths). + Os pacotes da camada devem ser compatíveis com o Linux. As funções do Lambda são executadas no Amazon Linux. Você pode criar camadas que contenham bibliotecas Node.js de terceiros instaladas com `npm` (como `axios` ou `lodash`) ou seus próprios módulos JavaScript. ### Dependências de terceiros **Para criar uma camada usando pacotes npm** 1. Crie a estrutura de diretório necessária e instale pacotes nela diretamente: ``` mkdir -p nodejs npm install --prefix nodejs lodash axios ``` Esse comando instala pacotes diretamente no diretório `nodejs/node_modules`, que é a estrutura exigida pelo Lambda. **nota** Para pacotes com dependências nativas ou componentes binários (como [sharp](https://www.npmjs.com/package/sharp) ou [bcrypt](https://www.npmjs.com/package/bcrypt)), certifique-se de que sejam compatíveis com o ambiente Linux do Lambda e com a [arquitetura](foundation-arch.md) da função. Talvez seja necessário usar o sinalizador `--platform`: ``` npm install --prefix nodejs --platform=linux --arch=x64 sharp ``` No caso de dependências nativas mais complexas, talvez seja necessário compilá-las em um ambiente Linux que corresponda ao runtime do Lambda. É possível usar o Docker para essa finalidade. 1. Crie um arquivo .zip do conteúdo da camada: ------ #### [ Linux/macOS ] ``` zip -r layer.zip nodejs/ ``` ------ #### [ PowerShell ] ``` Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip ``` ------ A estrutura de diretórios do arquivo zip deve ser assim: ``` nodejs/ ├── package.json ├── package-lock.json └── node_modules/ ├── lodash/ ├── axios/ └── (dependencies of the other packages) ``` **nota** Garanta que o arquivo .zip inclua o diretório `nodejs` no nível raiz com `node_modules` dentro dele. Essa estrutura garante que o Lambda consiga localizar e importar seus pacotes. Os arquivos `package.json` e `package-lock.json` no diretório `nodejs/` são usados pelo npm para gerenciamento de dependências, mas não são exigidos pelo Lambda para a funcionalidade da camada. Cada pacote instalado já contém seu próprio arquivo `package.json` que define como o Lambda importa o pacote. ### Módulos JavaScript personalizados **Para criar uma camada usando seu próprio código** 1. Crie a estrutura de diretório necessária para sua camada: ``` mkdir -p nodejs/node_modules/validator cd nodejs/node_modules/validator ``` 1. Crie um arquivo `package.json` para seu módulo personalizado a fim de definir como ele deve ser importado: **Example nodejs/node\$1modules/validator/package.json** ``` { "name": "validator", "version": "1.0.0", "type": "module", "main": "index.mjs" } ``` 1. Crie o arquivo do módulo JavaScript: **Example nodejs/node\$1modules/validator/index.mjs** ``` export function validateOrder(orderData) { // Validates an order and returns formatted data const requiredFields = ['productId', 'quantity']; // Check required fields const missingFields = requiredFields.filter(field => !(field in orderData)); if (missingFields.length > 0) { throw new Error(`Missing required fields: ${missingFields.join(', ')}`); } // Validate quantity const quantity = orderData.quantity; if (!Number.isInteger(quantity) || quantity < 1) { throw new Error('Quantity must be a positive integer'); } // Format and return the validated data return { productId: String(orderData.productId), quantity: quantity, shippingPriority: orderData.priority || 'standard' }; } export function formatResponse(statusCode, body) { // Formats the API response return { statusCode: statusCode, body: JSON.stringify(body) }; } ``` 1. Crie um arquivo .zip do conteúdo da camada: ------ #### [ Linux/macOS ] ``` zip -r layer.zip nodejs/ ``` ------ #### [ PowerShell ] ``` Compress-Archive -Path .\nodejs -DestinationPath .\layer.zip ``` ------ A estrutura de diretórios do arquivo zip deve ser assim: ``` nodejs/ └── node_modules/ └── validator/ ├── package.json └── index.mjs ``` 1. Na função, importe e use os módulos. Exemplo: ``` import { validateOrder, formatResponse } from 'validator'; export const handler = async (event) => { try { // Parse the order data from the event body const orderData = JSON.parse(event.body || '{}'); // Validate and format the order const validatedOrder = validateOrder(orderData); return formatResponse(200, { message: 'Order validated successfully', order: validatedOrder }); } catch (error) { if (error instanceof Error && error.message.includes('Missing required fields')) { return formatResponse(400, { error: error.message }); } return formatResponse(500, { error: 'Internal server error' }); } }; ``` Você pode usar os seguinte [evento de teste](testing-functions.md#invoke-with-event)para invocar a função: ``` { "body": "{\"productId\": \"ABC123\", \"quantity\": 2, \"priority\": \"express\"}" } ``` Resposta esperada: ``` { "statusCode": 200, "body": "{\"message\":\"Order validated successfully\",\"order\":{\"productId\":\"ABC123\",\"quantity\":2,\"shippingPriority\":\"express\"}}" } ``` ## Criar a camada no Lambda Você pode publicar a camada usando a AWS CLI ou o console do Lambda. ------ #### [ AWS CLI ] Execute o comando da AWS CLI [publish-layer-version](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/publish-layer-version.html) para criar a camada do Lambda: ``` aws lambda publish-layer-version --layer-name my-layer --zip-file fileb://layer.zip --compatible-runtimes nodejs24.x ``` O parâmetro [runtimes compatíveis](https://docs.aws.amazon.com/lambda/latest/api/API_PublishLayerVersion.html#lambda-PublishLayerVersion-request-CompatibleRuntimes) é opcional. Quando especificado, o Lambda usa esse parâmetro para filtrar camadas no console do Lambda. ------ #### [ Console ] **Para criar uma camada (console)** 1. Abra a [página Layers](https://console.aws.amazon.com/lambda/home#/layers) (Camadas) do console do Lambda. 1. Escolha **Criar camada**. 1. Escolha **Carregar um arquivo .zip** e depois carregue o arquivo .zip que você criou anteriormente. 1. (Opcional) Para ver quais são os **runtimes compatíveis**, escolha o runtime do Node.js que corresponde à versão do Node.js que você usou para criar a camada. 1. Escolha **Criar**. ------ ## Adicionar a camada à função ------ #### [ AWS CLI ] Para anexar a camada à função, execute o comando da AWS CLI [update-function-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-function-configuration.html) . Para o parâmetro `--layers` use o ARN da camada. O ARN deve especificar a versão (por exemplo, `arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1`). Para obter mais informações, consulte [Camadas e versões da camada](chapter-layers.md#lambda-layer-versions). ``` aws lambda update-function-configuration --function-name my-function --cli-binary-format raw-in-base64-out --layers "arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1" ``` A opção **cli-binary-format** será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute `aws configure set cli-binary-format raw-in-base64-out`. Para obter mais informações, consulte [A AWS CLI comporta opções de linha de comando globais](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) no *Guia do usuário da AWS Command Line Interface versão 2*. ------ #### [ Console ] **Para adicionar uma camada a uma função** 1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda. 1. Escolha a função. 1. Role a tela para baixo até a seção **Camadas** e depois escolha **Adicionar uma camada**. 1. Em **Escolher uma camada**, selecione **Camadas personalizadas** e depois escolha a camada. **nota** Se você não adicionou um [runtime compatível](https://docs.aws.amazon.com/lambda/latest/api/API_PublishLayerVersion.html#lambda-PublishLayerVersion-request-CompatibleRuntimes) ao criar a camada, ela não estará listada aqui. Em vez disso, você pode especificar o ARN da camada. 1. Escolha **Adicionar**. ------ ## Aplicação de amostra Para obter mais exemplos de como usar camadas do Lambda, consulte a aplicação de amostra [layer-nodejs](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/layer-nodejs) no repositório AWS Lambda Developer Guide do GitHub. Essa aplicação inclui uma camada que contém a biblioteca [lodash](https://www.npmjs.com/package/lodash). Após criar a camada, você pode implantar e invocar as funções correspondentes para confirmar que ela funciona conforme o esperado. # Usar o objeto de contexto do Lambda para recuperar informações das funções em Node.js Quando o Lambda executa a função, ele transmite um objeto de contexto para o [handler](nodejs-handler.md). Esse objeto fornece métodos e propriedades que fornecem informações sobre a invocação, a função e o ambiente de execução. **Métodos de contexto** + `getRemainingTimeInMillis()`: retorna o número de milissegundos restantes antes do tempo limite da execução. **Propriedades de contexto** + `functionName`: o nome da função do Lambda. + `functionVersion`: a [versão](configuration-versions.md) da função. + `invokedFunctionArn`: o nome do recurso da Amazon (ARN) usado para invocar a função. Indica se o invocador especificou um alias ou número de versão. + `memoryLimitInMB`: a quantidade de memória alocada para a função. + `awsRequestId`: o identificador da solicitação de invocação. + `logGroupName`: o grupo de logs da função. + `logStreamName`: a transmissão de log para a instância da função. + `identity`: (aplicativos móveis) informações sobre a identidade do Amazon Cognito que autorizou a solicitação. + `cognitoIdentityId`: a identidade autenticada do Amazon Cognito. + `cognitoIdentityPoolId`: o grupo de identidades do Amazon Cognito que autorizou a invocação. + `clientContext`: (aplicativos móveis) contexto do cliente fornecido ao Lambda pela aplicação cliente. + `client.installation_id` + `client.app_title` + `client.app_version_name` + `client.app_version_code` + `client.app_package_name` + `env.platform_version` + `env.platform` + `env.make` + `env.model` + `env.locale` + `custom`: os valores personalizados que são definidos pela aplicação cliente. + `callbackWaitsForEmptyEventLoop`: por padrão (`true`), ao usar um manipulador de função baseado em retorno de chamada, o Lambda espera que o loop de eventos fique vazio após a execução do retorno de chamada antes de encerrar a invocação da função. Definido como `false` para enviar a resposta e encerrar a chamada imediatamente após a execução do retorno de chamada, em vez de aguardar até que o loop de eventos esteja vazio. Os eventos pendentes continuarão a ser executados durante a próxima invocação. Observe que o Lambda oferece suporte a manipuladores de funções baseados em retorno de chamada somente para runtimes do Node.js 22 e anteriores. O exemplo a seguir registra informações de contexto da função e retorna a localização dos logs. **Example Arquivo index.js** ``` exports.handler = async function(event, context) { console.log('Remaining time: ', context.getRemainingTimeInMillis()) console.log('Function name: ', context.functionName) return context.logStreamName } ``` # Registrar em log e monitorar funções do Lambda em Node.js O AWS Lambda monitora automaticamente as funções do Lambda em seu nome e envia logs para o Amazon CloudWatch. Sua função do Lambda vem com um grupo de logs do CloudWatch Logs e uma transmissão de logs para cada instância de sua função. O ambiente do runtime do Lambda envia detalhes sobre cada invocação à transmissão de logs e transmite os logs e outras saídas do código de sua função. Para obter mais informações, consulte [Enviar logs de função do Lambda para o CloudWatch Logs](monitoring-cloudwatchlogs.md). Esta página descreve como produzir saída em log usando o código de função do Lambda e como acessar os logs usando a AWS Command Line Interface, o console do Lambda ou o console do CloudWatch. **Topics** + [ ## Criar uma função que retorna logs ](#node-logging-output) + [ ## Usar controles avançados de registro em log do Lambda com Node.js ](#node-js-logging-advanced) + [ ## Visualizar logs no console do Lambda ](#nodejs-logging-console) + [ ## Visualização de logs no console do CloudWatch ](#nodejs-logging-cwconsole) + [ ## Visualizar logs usando a AWS Command Line Interface (AWS CLI) ](#nodejs-logging-cli) + [ ## Excluir logs ](#nodejs-logging-delete) ## Criar uma função que retorna logs Para gerar os logs do código de função, você pode usar métodos no [objeto do console](https://developer.mozilla.org/en-US/docs/Web/API/Console) ou qualquer biblioteca de logs que grave no `stdout` ou `stderr`. O exemplo a seguir registra em log os valores das variáveis de ambiente e o objeto do evento. **nota** Recomendamos que você use técnicas como validação de entrada e codificação de saída ao registrar entradas. Se você registrar os dados de entrada diretamente, um invasor poderá usar seu código para dificultar a detecção de adulterações, falsificar entradas de logs ou ignorar os monitores de registro. Para obter mais informações, consulte [Improper Output Neutralization for Logs](https://cwe.mitre.org/data/definitions/117.html) na *Common Weakness Enumeration*. **Example Arquivo index.js: registro em log** ``` exports.handler = async function(event, context) { console.log("ENVIRONMENT VARIABLES\n" + JSON.stringify(process.env, null, 2)) console.info("EVENT\n" + JSON.stringify(event, null, 2)) console.warn("Event not processed.") return context.logStreamName } ``` **Example formato do log** ``` START RequestId: c793869b-ee49-115b-a5b6-4fd21e8dedac Version: $LATEST 2019-06-07T19:11:20.562Z c793869b-ee49-115b-a5b6-4fd21e8dedac INFO ENVIRONMENT VARIABLES { "AWS_LAMBDA_FUNCTION_VERSION": "$LATEST", "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/my-function", "AWS_LAMBDA_LOG_STREAM_NAME": "2019/06/07/[$LATEST]e6f4a0c4241adcd70c262d34c0bbc85c", "AWS_EXECUTION_ENV": "AWS_Lambda_nodejs12.x", "AWS_LAMBDA_FUNCTION_NAME": "my-function", "PATH": "/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin", "NODE_PATH": "/opt/nodejs/node10/node_modules:/opt/nodejs/node_modules:/var/runtime/node_modules", ... } 2019-06-07T19:11:20.563Z c793869b-ee49-115b-a5b6-4fd21e8dedac INFO EVENT { "key": "value" } 2019-06-07T19:11:20.564Z c793869b-ee49-115b-a5b6-4fd21e8dedac WARN Event not processed. END RequestId: c793869b-ee49-115b-a5b6-4fd21e8dedac REPORT RequestId: c793869b-ee49-115b-a5b6-4fd21e8dedac Duration: 128.83 ms Billed Duration: 296 ms Memory Size: 128 MB Max Memory Used: 74 MB Init Duration: 166.62 ms XRAY TraceId: 1-5d9d007f-0a8c7fd02xmpl480aed55ef0 SegmentId: 3d752xmpl1bbe37e Sampled: true ``` O runtime do Node.js registra as linhas `START`, `END` e `REPORT` para cada invocação. Ele adiciona um carimbo de data e hora, o ID da solicitação e o nível de log em cada entrada registrada pela função. A linha do relatório fornece os detalhes a seguir. **RELATAR campos de dados de linha** + **RequestId**: o ID de solicitação exclusivo para a invocação. + **Duração**: a quantidade de tempo que o método de manipulador da função gastou processando o evento. + **Duração faturada**: a quantia de tempo faturada para a invocação. + **Tamanho da memória**: a quantidade de memória alocada para a função. + **Memória máxima utilizada**: a quantidade de memória utilizada pela função. Quando as invocações compartilham um ambiente de execução, o Lambda relata a memória máxima usada em todas as invocações. Esse comportamento pode resultar em um valor relatado maior do que o esperado. + **Duração inicial**: para a primeira solicitação atendida, a quantidade de tempo que o runtime levou para carregar a função e executar o código fora do método do handler. + **XRAY TraceId**: para solicitações rastreadas, o [ID de rastreamento do AWS X-Ray](services-xray.md). + **SegmentId**: para solicitações rastreadas, o ID do segmento do X-Ray. + **Amostragem**: para solicitações rastreadas, o resultado da amostragem. É possível visualizar logs no console do Lambda, no console do CloudWatch Logs ou na linha de comando. ## Usar controles avançados de registro em log do Lambda com Node.js Para dar mais controle sobre como os logs das funções são capturados, processados e consumidos, você pode configurar as seguintes opções de log para runtimes compatíveis do Node.js: + **Formato do log**: selecione entre texto simples e formato JSON estruturado para os logs da sua função. + **Nível de log**: para logs no formato JSON, escolha o nível de detalhe dos logs enviados pelo Lambda para o Amazon CloudWatch, como ERROR, DEBUG ou INFO. + **Grupo de logs**: escolha o grupo de logs do CloudWatch para o qual sua função envia logs. Para obter mais informações sobre essas opções de registro em log e instruções sobre como configurar a função para usá-las, consulte [Configurar controles avançados de registro em log para funções do Lambda](monitoring-logs.md#monitoring-cloudwatchlogs-advanced). Para usar as opções de formato de log e nível de log com as funções do Lambda para Node.js, consulte as orientações nas seções a seguir. ### Usar logs JSON estruturados com Node.js Se você selecionar JSON para o formato de log da função, o Lambda enviará a saída de logs usando os métodos do console `console.trace`, `console.debug`, `console.log`, `console.info`, `console.error` e `console.warn` para o CloudWatch como JSON estruturado. Cada objeto de log JSON contém pelo menos quatro pares de valores-chave com as seguintes chaves: + `"timestamp"`: o horário em que a mensagem de log foi gerada. + `"level"`: o nível de log atribuído à mensagem. + `"message"`: o conteúdo da mensagem de log. + `"requestId"`: o ID de solicitação exclusivo para invocar a função. Dependendo do método de registro em log que a função usa, esse objeto JSON também pode conter pares de chaves adicionais. Por exemplo, se a função usa métodos do `console` para registrar em log objetos de erro usando vários argumentos, o objeto JSON conterá pares adicionais de valores de chave com as chaves `errorMessage`, `errorType` e `stackTrace`. Se o código já usa outra biblioteca de logs, como o Powertools para AWS Lambda, para produzir logs em JSON estruturados, você não precisa fazer nenhuma alteração. O Lambda não codifica duas vezes nenhum log que já esteja codificado em JSON. Então, os logs de aplicações da função continuarão sendo capturados como antes. Para obter mais informações sobre como usar o pacote Powertools for AWS Lambda para criar logs em JSON estruturados no runtime do Node.js, consulte [Registrar em log e monitorar funções do Lambda em TypeScript](typescript-logging.md). #### Exemplos de saídas de log formatadas em JSON Os exemplos a seguir mostram como várias saídas de log geradas usando os métodos do `console` com argumentos únicos e múltiplos são capturadas no CloudWatch Logs quando você define o formato de log da função como JSON. O primeiro exemplo usa o método do `console.error` para gerar uma string simples. **Example Código de registro em log do Node.js** ``` export const handler = async (event) => { console.error("This is a warning message"); ... } ``` **Example Registro em log JSON** ``` { "timestamp":"2025-11-01T00:21:51.358Z", "level":"ERROR", "message":"This is a warning message", "requestId":"93f25699-2cbf-4976-8f94-336a0aa98c6f" } ``` Também é possível gerar mensagens de log estruturadas mais complexas usando argumentos únicos ou múltiplos com os métodos do `console`. No próximo exemplo, você usará `console.log` para gerar dois pares de valores de chave usando um único argumento. Observe que o campo `"message"` no objeto JSON que o Lambda envia para o CloudWatch Logs não é convertido em strings. **Example Código de registro em log do Node.js** ``` export const handler = async (event) => { console.log({data: 12.3, flag: false}); ... } ``` **Example Registro em log JSON** ``` { "timestamp": "2025-12-08T23:21:04.664Z", "level": "INFO", "requestId": "405a4537-9226-4216-ac59-64381ec8654a", "message": { "data": 12.3, "flag": false } } ``` No próximo exemplo, você usará novamente o método do `console.log` para criar uma saída de log. Dessa vez, o método usa dois argumentos, um mapa contendo dois pares de valores de chave e uma string identificadora. Observe que, nesse caso, como você forneceu dois argumentos, o Lambda converte o campo `"message"` em strings. **Example Código de registro em log do Node.js** ``` export const handler = async (event) => { console.log('Some object - ', {data: 12.3, flag: false}); ... } ``` **Example Registro em log JSON** ``` { "timestamp": "2025-12-08T23:21:04.664Z", "level": "INFO", "requestId": "405a4537-9226-4216-ac59-64381ec8654a", "message": "Some object - { data: 12.3, flag: false }" } ``` O Lambda atribui saídas geradas usando `console.log` no nível de log INFO. O exemplo final mostra como objetos de erro podem ser enviados para o CloudWatch Logs usando os métodos do `console`. Observe que, quando são registrados objetos de erro usando vários argumentos, o Lambda adiciona os campos `errorMessage`, `errorType` e `stackTrace` à saída do log. **Example Código de registro em log do Node.js** ``` export const handler = async (event) => { let e1 = new ReferenceError("some reference error"); let e2 = new SyntaxError("some syntax error"); console.log(e1); console.log("errors logged - ", e1, e2); }; ``` **Example Registro em log JSON** ``` { "timestamp": "2025-12-08T23:21:04.632Z", "level": "INFO", "requestId": "405a4537-9226-4216-ac59-64381ec8654a", "message": { "errorType": "ReferenceError", "errorMessage": "some reference error", "stackTrace": [ "ReferenceError: some reference error", " at Runtime.handler (file:///var/task/index.mjs:3:12)", " at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1173:29)" ] } } { "timestamp": "2025-12-08T23:21:04.646Z", "level": "INFO", "requestId": "405a4537-9226-4216-ac59-64381ec8654a", "message": "errors logged - ReferenceError: some reference error\n at Runtime.handler (file:///var/task/index.mjs:3:12)\n at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1173:29) SyntaxError: some syntax error\n at Runtime.handler (file:///var/task/index.mjs:4:12)\n at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1173:29)", "errorType": "ReferenceError", "errorMessage": "some reference error", "stackTrace": [ "ReferenceError: some reference error", " at Runtime.handler (file:///var/task/index.mjs:3:12)", " at Runtime.handleOnceNonStreaming (file:///var/runtime/index.mjs:1173:29)" ] } ``` Ao registrar em log vários tipos de erro, os campos adicionais `errorMessage`, `errorType` e `stackTrace` são extraídos do primeiro tipo de erro fornecido ao método do `console`. ### Usar bibliotecas cliente com logs de formato de métricas incorporadas (EMF) em JSON estruturado A AWS fornece bibliotecas cliente de código aberto para o Node.js que podem ser usadas para criar logs de [formato de métricas incorporadas ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format_Libraries.html) (EMF). Se você já tiver funções que usam essas bibliotecas e alterar o formato de log da função para JSON, é possível que o CloudWatch não reconheça mais as métricas emitidas pelo código. Se o seu código atualmente emite logs em EMF diretamente usando `console.log` ou o Powertools para AWS Lambda (TypeScript), o CloudWatch também não poderá analisá-los se você alterar o formato de log da função para JSON. **Importante** Para garantir que os logs em EMF das funções continuem sendo analisados adequadamente pelo CloudWatch, atualize as bibliotecas de [EMF](https://www.npmjs.com/package/aws-embedded-metrics) e do [Powertools para AWS Lambda](https://github.com/aws-powertools/powertools-lambda-typescript) para as versões mais recentes. Ao mudar para logs em formato JSON, também recomendamos que você realize testes a fim de garantir a compatibilidade com as métricas incorporadas da função. Se o seu código emitir logs em EMF diretamente usando `console.log`, altere o código para gerar essas métricas diretamente em `stdout`, conforme mostrado no código de exemplo a seguir. **Example código que emite métricas incorporadas para `stdout`** ``` process.stdout.write(JSON.stringify( { "_aws": { "Timestamp": Date.now(), "CloudWatchMetrics": [{ "Namespace": "lambda-function-metrics", "Dimensions": [["functionVersion"]], "Metrics": [{ "Name": "time", "Unit": "Milliseconds", "StorageResolution": 60 }] }] }, "functionVersion": "$LATEST", "time": 100, "requestId": context.awsRequestId } ) + "\n") ``` ### Usar a filtragem em nível de log com Node.js Para o AWS Lambda filtrar os logs de aplicação de acordo com o nível de log, a função precisa usar logs em formato JSON. Isso pode ser feito de duas maneiras: + Crie saídas de log usando os métodos padrão do console e configure a função para usar logs em formato JSON. Dessa forma, o AWS Lambda filtra suas saídas de logs usando o par de valores-chave “nível” no objeto JSON descrito em [Usar logs JSON estruturados com Node.js](#nodejs-logging-advanced-JSON). Para saber como configurar o formato de log da função, consulte [Configurar controles avançados de registro em log para funções do Lambda](monitoring-logs.md#monitoring-cloudwatchlogs-advanced). + Use outro método ou biblioteca de logs para criar logs JSON estruturados no código, de modo que incluam um par de valores-chave de “nível” para definir o nível da saída de log. Por exemplo, você pode usar o Powertools para AWS Lambda para gerar saídas de log JSON estruturado do seu código. Consulte [Registrar em log e monitorar funções do Lambda em TypeScript](typescript-logging.md) para saber mais sobre como usar o Powertools com o runtime do Node.js. Para que o Lambda filtre os logs da função, você também precisa incluir um par de valores-chave `"timestamp"` na saída do log JSON. A hora deve ser especificada em um formato [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) válido de carimbo de data/hora. Se você não fornecer um carimbo de data/hora válido, o Lambda atribuirá ao log o nível INFO e adicionará um carimbo de data/hora. Ao configurar a função para usar a filtragem em nível de log, você seleciona uma das seguintes opções para o nível de logs enviados pelo AWS Lambda para o CloudWatch Logs: | Nível de log | Uso padrão | | --- | --- | | TRACE (mais detalhes) | As informações mais detalhadas usadas para rastrear o caminho da execução do código | | DEBUG | Informações detalhadas para depuração do sistema | | INFORMAÇÕES | Mensagens que registram a operação normal da função | | WARN | Mensagens sobre possíveis erros que podem levar a um comportamento inesperado se não forem corrigidos | | ERRO | Mensagens sobre problemas que impedem que o código funcione conforme o esperado | | FATAL (menos detalhes) | Mensagens sobre erros graves que fazem a aplicação parar de funcionar | O Lambda envia logs do nível selecionado, e dos níveis inferiores, para o CloudWatch. Por exemplo, se você configurar um nível de log de WARN, o Lambda enviará logs correspondentes aos níveis WARN, ERROR e FATAL. ## Visualizar logs no console do Lambda É possível usar o console do Lambda para exibir a saída do log depois de invocar uma função do Lambda. Se seu código puder ser testado no editor de **Código** incorporado, você encontrará logs nos **resultados de execução**. Ao usar o recurso de teste do console para invocar uma função, você encontrará **Saída de log** na seção **Detalhes**. ## Visualização de logs no console do CloudWatch É possível usar o console do Amazon CloudWatch para exibir logs de todas as invocações da função do Lambda. **Para visualizar logs no console do CloudWatch** 1. No console do Amazon CloudWatch, abra a [página Log groups](https://console.aws.amazon.com/cloudwatch/home?#logs:) (Grupos de log). 1. Escolha o grupo de logs de sua função (**/aws/lambda/*nome-de-sua-função***). 1. Escolha um stream de logs. Cada fluxo de log corresponde a uma [instância da sua função](lambda-runtime-environment.md). Um fluxo de logs é exibido quando você atualiza sua função do Lambda e quando mais instâncias são criadas para lidar com invocações simultâneas. Para localizar logs de uma invocação específica, recomendamos intrumentar sua função com AWS X-Ray. O X-Ray registra detalhes sobre a solicitação e o stream de logs no rastreamento. ## Visualizar logs usando a AWS Command Line Interface (AWS CLI) O AWS CLI é uma ferramenta de código aberto que permite interagir com os serviços do AWS usando comandos no shell da linha de comando. Para concluir as etapas desta seção, você deve ter a [versão 2 da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). É possível usar a [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) para recuperar logs de uma invocação usando a opção de comando `--log-type`. A resposta contém um campo `LogResult` com até 4 KB de logs codificados em base64 obtidos da invocação. **Example recuperar um ID de log** O exemplo a seguir mostra como recuperar um *ID de log* do campo `LogResult` para uma função chamada `my-function`. ``` aws lambda invoke --function-name my-function out --log-type Tail ``` A seguinte saída deverá ser mostrada: ``` { "StatusCode": 200, "LogResult": "U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...", "ExecutedVersion": "$LATEST" } ``` **Example decodificar os logs** No mesmo prompt de comando, use o utilitário `base64` para decodificar os logs. O exemplo a seguir mostra como recuperar logs codificados em base64 de `my-function`. ``` aws lambda invoke --function-name my-function out --log-type Tail \ --query 'LogResult' --output text --cli-binary-format raw-in-base64-out | base64 --decode ``` A opção **cli-binary-format** será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute `aws configure set cli-binary-format raw-in-base64-out`. Para obter mais informações, consulte [A AWS CLI comporta opções de linha de comando globais](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) no *Guia do usuário da AWS Command Line Interface versão 2*. A seguinte saída deverá ser mostrada: ``` START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST "AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib", END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Duration: 79.67 ms Billed Duration: 80 ms Memory Size: 128 MB Max Memory Used: 73 MB ``` O utilitário `base64` está disponível no Linux, macOS e [Ubuntu no Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Os usuários do macOS precisam usar `base64 -D`. **Example get-logs.sh script** No mesmo prompt de comando, use o script a seguir para fazer download dos últimos cinco eventos de log. O script usa `sed` para remover as aspas do arquivo de saída e fica inativo por 15 segundos para que os logs tenham tempo de ficar disponíveis. A saída inclui a resposta do Lambda, e a saída do comando `get-log-events`. Copie o conteúdo do exemplo de código a seguir e salve no diretório de seu projeto do Lambda como `get-logs.sh`. A opção **cli-binary-format** será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute `aws configure set cli-binary-format raw-in-base64-out`. Para obter mais informações, consulte [A AWS CLI comporta opções de linha de comando globais](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-options.html#cli-configure-options-list) no *Guia do usuário da AWS Command Line Interface versão 2*. ``` #!/bin/bash aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --payload '{"key": "value"}' out sed -i'' -e 's/"//g' out sleep 15 aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name stream1 --limit 5 ``` **Example macOS e Linux (somente)** No mesmo prompt de comando, os usuários do macOS e do Linux podem precisar executar o comando a seguir para garantir que o script seja executável. ``` chmod -R 755 get-logs.sh ``` **Example recuperar os últimos cinco eventos de log** No mesmo prompt de comando, execute o script a seguir para obter os últimos cinco eventos de log. ``` ./get-logs.sh ``` A seguinte saída deverá ser mostrada: ``` { "StatusCode": 200, "ExecutedVersion": "$LATEST" } { "events": [ { "timestamp": 1559763003171, "message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version: $LATEST\n", "ingestionTime": 1559763003309 }, { "timestamp": 1559763003173, "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tENVIRONMENT VARIABLES\r{\r \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...", "ingestionTime": 1559763018353 }, { "timestamp": 1559763003173, "message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf\tINFO\tEVENT\r{\r \"key\": \"value\"\r}\n", "ingestionTime": 1559763018353 }, { "timestamp": 1559763003218, "message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n", "ingestionTime": 1559763018353 }, { "timestamp": 1559763003218, "message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration: 26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n", "ingestionTime": 1559763018353 } ], "nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795", "nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080" } ``` ## Excluir logs Os grupos de logs não são excluídos automaticamente excluídos quando você exclui uma função. Para evitar armazenar logs indefinidamente, exclua o grupo de logs ou[Configurar um período de retenção](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html#SettingLogRetention)após o qual os logs são excluídos automaticamente. # Instrumentação do código Node.js no AWS Lambda O Lambda se integra ao AWS X-Ray para ajudar você a rastrear, depurar e otimizar aplicações do Lambda. É possível usar o X-Ray para rastrear uma solicitação enquanto ela atravessa recursos na aplicação, o que pode incluir funções Lambda e outros produtos da AWS. Para enviar dados de rastreamento ao X-Ray, você pode usar uma das duas bibliotecas SDK: + [AWS Distro for OpenTelemetry (ADOT)](https://aws.amazon.com/otel): uma distribuição segura, pronta para produção e com suporte na AWS do SDK OpenTelemetry (OTel). + [AWS X-Ray SDK for Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html) – um SDK para geração e envio de dados de rastreamento ao X-Ray. Cada um dos SDKs oferece maneiras de enviar dados de telemetria ao serviço do X-Ray. Em seguida, é possível usar o X-Ray para visualizar, filtrar e obter insights sobre as métricas de performance da aplicação para identificar problemas e oportunidades de otimização. **Importante** Os SDKs do X-Ray e do Powertools para AWS Lambda fazem parte de uma solução de instrumentação totalmente integrada oferecida pela AWS. As camadas do Lambda para ADOT fazem parte de um padrão em todo o setor para instrumentação de rastreamento que coleta mais dados em geral, mas pode não ser adequado para todos os casos de uso. É possível implementar o rastreamento de ponta a ponta no X-Ray usando ambas as soluções. Para saber mais sobre como escolher entre elas, consulte [Como escolher entre os SDKs do AWS Distro para OpenTelemetry e do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-instrumenting-your-app.html#xray-instrumenting-choosing). **Topics** + [ ## Usar o ADOT para instrumentar funções do Node.js ](#nodejs-adot) + [ ## Usar o SDK do X-Ray para instrumentar suas funções Node.js ](#nodejs-xray-sdk) + [ ## Ativar o rastreamento com o console do Lambda ](#nodejs-tracing-console) + [ ## Ativar o rastreamento com a API do Lambda ](#nodejs-tracing-api) + [ ## Ativar o rastreamento com o CloudFormation ](#nodejs-tracing-cloudformation) + [ ## Interpretar um rastreamento do X-Ray ](#nodejs-tracing-interpretation) + [ ## Armazenar dependências de runtime em uma camada (SDK do X-Ray) ](#nodejs-tracing-layers) ## Usar o ADOT para instrumentar funções do Node.js O ADOT fornece [camadas](chapter-layers.md) do Lambda totalmente gerenciadas que empacotam tudo o que você precisa para coletar dados de telemetria usando o SDK do OTel. Ao consumir essa camada, é possível instrumentar suas funções Lambda sem precisar modificar nenhum código de função. Você também pode configurar sua camada para fazer a inicialização personalizada do OTel. Para obter mais informações, consulte [Custom configuration for the ADOT Collector on Lambda](https://aws-otel.github.io/docs/getting-started/lambda#custom-configuration-for-the-adot-collector-on-lambda) (Configuração personalizada para o ADOT Collector no Lambda) na documentação do ADOT. Para runtimes Node.js, você pode adicionar a **camada do Lambda gerenciada pela AWS para ADOT Javascript** a fim de instrumentar suas funções automaticamente. Para obter instruções detalhadas sobre como adicionar essa camada, consulte [Suporte do AWS Distro for OpenTelemetry Lambda para JavaScript](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js), na documentação do ADOT. ## Usar o SDK do X-Ray para instrumentar suas funções Node.js Para registrar detalhes sobre as chamadas feitas pela sua função do Lambda para outros recursos na sua aplicação, você também pode usar o AWS X-Ray SDK for Node.js. Para obter o SDK, adicione o pacote `aws-xray-sdk-core` às dependências do aplicativo. **Example [blank-nodejs/package.json](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/package.json)** ``` { "name": "blank-nodejs", "version": "1.0.0", "private": true, "devDependencies": { "jest": "29.7.0" }, "dependencies": { "@aws-sdk/client-lambda": "3.345.0", "aws-xray-sdk-core": "3.5.3" }, "scripts": { "test": "jest" } } ``` Para instrumentar clientes do AWS SDK no [AWS SDK para JavaScript v3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html), envolva a instância do cliente com o método `captureAWSv3Client`. **Example [blank-nodejs/function/index.js](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/function/index.js): rastrear um cliente do AWS SDK** ``` const AWSXRay = require('aws-xray-sdk-core'); const { LambdaClient, GetAccountSettingsCommand } = require('@aws-sdk/client-lambda'); // Create client outside of handler to reuse const lambda = AWSXRay.captureAWSv3Client(new LambdaClient()); // Handler exports.handler = async function(event, context) { event.Records.forEach(record => { ... ``` O runtime do Lambda define algumas variáveis de ambiente para configurar o X-Ray SDK. Por exemplo, o Lambda define `AWS_XRAY_CONTEXT_MISSING` como `LOG_ERROR` para evitar lançar erros de runtime no X-Ray SDK. Para definir uma estratégia de contexto ausente personalizada, substitua a variável de ambiente na configuração da função para que ela não tenha valores e, depois, defina a estratégia de contexto ausente de forma programática. **Example Exemplo de código de inicialização** ``` const AWSXRay = require('aws-xray-sdk-core'); // Configure the context missing strategy to do nothing AWSXRay.setContextMissingStrategy(() => {}); ``` Para obter mais informações, consulte [Trabalhar com variáveis de ambiente no Lambda](configuration-envvars.md). Depois de adicionar as dependências corretas e fazer as devidas mudanças de código, ative o rastreamento na configuração da sua função usando o console do Lambda ou a API. ## Ativar o rastreamento com o console do Lambda Para alternar o rastreamento ativo na sua função do Lambda usando o console, siga as etapas abaixo: **Para ativar o rastreamento ativo** 1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda. 1. Escolha uma função. 1. Escolha **Configuration** (Configuração) e depois **Monitoring and operations tools** (Ferramentas de monitoramento e operações). 1. Em **Ferramentas de monitoramento adicionais**, selecione **Editar**. 1. Em **CloudWatch Application Signals e AWS X-Ray**, escolha **Habilitar** para **Rastreamentos do serviço Lambda**. 1. Escolha **Salvar**. ## Ativar o rastreamento com a API do Lambda Configure o rastreamento na sua função do Lambda com a AWS CLI ou o AWS SDK, usando as seguintes operações de API: + [UpdateFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionConfiguration.html) + [GetFunctionConfiguration](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionConfiguration.html) + [CreateFunction](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunction.html) O exemplo de comando da AWS CLI a seguir habilita o rastreamento ativo em uma função chamada **my-function**. ``` aws lambda update-function-configuration --function-name my-function \ --tracing-config Mode=Active ``` O modo de rastreamento faz parte da configuração específica da versão quando você publica uma versão da função. Não é possível alterar o modo de rastreamento em uma versão publicada. ## Ativar o rastreamento com o CloudFormation Para ativar o rastreamento ativo em um recurso `AWS::Lambda::Function` em um modelo do CloudFormation, use a propriedade `TracingConfig`. **Example [function-inline.yml](https://github.com/awsdocs/aws-lambda-developer-guide/blob/master/templates/function-inline.yml): configuração de rastreamento** ``` Resources: function: Type: [AWS::Lambda::Function](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-lambda-function.html) Properties: TracingConfig: Mode: Active ... ``` Para um recurso do AWS Serverless Application Model (AWS SAM) `AWS::Serverless::Function`, use a propriedade `Tracing`. **Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml): configuração de rastreamento** ``` Resources: function: Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) Properties: Tracing: Active ... ``` ## Interpretar um rastreamento do X-Ray Sua função precisa de permissão para carregar dados de rastreamento no X-Ray. Quando você ativa o rastreamento ativo no console do Lambda, o Lambda adiciona as permissões necessárias à [função de execução](lambda-intro-execution-role.md) da função. Caso contrário, adicione a política [AWSXRayDaemonWriteAccess](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess) à função de execução. Após configurar o rastreamento ativo, você pode observar solicitações específicas por meio da aplicação. O [grafo de serviço do X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts-servicegraph) exibe informações sobre sua aplicação e todos os componentes. O exemplo a seguir mostra uma aplicação com duas funções. A função principal processa eventos e, às vezes, retorna erros. A segunda função de cima para baixo processa erros que aparecem no primeiro grupo de logs e usa o AWS SDK para chamar o X-Ray, o Amazon Simple Storage Service (Amazon S3) e o Amazon CloudWatch Logs. ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sample-errorprocessor-servicemap.png) O X-Ray não rastreia todas as solicitações para sua aplicação. O X-Ray aplica um algoritmo de amostragem para garantir que o rastreamento seja eficiente, enquanto ainda fornece uma amostra representativa das solicitações. A taxa de amostragem é uma solicitação por segundo e 5% de solicitações adicionais. Você não pode configurar a taxa de amostragem do X-Ray para suas funções. No X-Ray, um *rastreamento* registra informações sobre uma solicitação que é processada por um ou mais *serviços*. O Lambda registra dois segmentos por rastreamento, o que cria dois nós no gráfico de serviços. A imagem a seguir destaca esses dois nós: ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/xray-servicemap-function.png) O primeiro nó à esquerda representa o serviço do Lambda, que recebe a solicitação de invocação. O segundo nó representa a sua função do Lambda específica. O exemplo a seguir mostra um rastreamento com esses dois segmentos. Ambos têm o nome **my-function**, mas um tem a origem `AWS::Lambda` e o outro, a origem `AWS::Lambda::Function`. Se o segmento `AWS::Lambda` mostrar um erro, o serviço Lambda teve um problema. Se o segmento `AWS::Lambda::Function` mostrar um erro, sua função teve um problema. ![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/V2_sandbox_images/my-function-2-v1.png) Este exemplo expande o segmento `AWS::Lambda::Function` para mostrar seus três subsegmentos. **nota** A AWS atualmente está implementando alterações no serviço Lambda. Devido a essas alterações, você pode ver pequenas diferenças entre a estrutura e o conteúdo das mensagens de log do sistema e os segmentos de rastreamento emitidos por diferentes funções do Lambda na sua Conta da AWS. O exemplo de rastreamento mostrado aqui ilustra o segmento de função no estilo antigo. As diferenças entre os segmentos no estilo antigo e no estilo novo são descritas nos próximos parágrafos. Essas alterações serão implementadas durante as próximas semanas, e todas as funções em todas as Regiões da AWS, exceto nas regiões China e GovCloud, passarão a usar o novo formato de mensagens de log e segmentos de rastreamento. O segmento de função no estilo antigo contém os seguintes subsegmentos: + **Inicialização**: representa o tempo gasto carregando a função e executando o [código de inicialização](foundation-progmodel.md). Esse subsegmento aparece somente para o primeiro evento que cada instância da função processa. + **Invocação**: representa o tempo gasto na execução do código do manipulador. + **Sobrecarga**: representa o tempo gasto pelo runtime do Lambda preparando-se para lidar com o próximo evento. O segmento de função no estilo novo não contém um subsegmento `Invocation`. Em vez disso, os subsegmentos dos clientes são anexados diretamente ao segmento da função. Para obter mais informações sobre a estrutura dos segmentos de função no estilo antigo e no estilo novo, consulte [Noções básicas sobre rastreamentos do X-Ray](services-xray.md#services-xray-traces). Você também pode instrumentar clientes HTTP, registrar consultas SQL e criar subsegmentos personalizados com anotações e metadados. Para obter mais informações, consulte [AWS X-Ray SDK for Node.js](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html) no *Guia do desenvolvedor do AWS X-Ray*. **Preços** Você pode usar o rastreamento do X-Ray gratuitamente todos os meses até determinado limite como parte do nível gratuito da AWS. Além do limite, o X-Ray cobra por armazenamento e recuperação de rastreamento. Para obter mais informações, consulte [Preços do AWS X-Ray](https://aws.amazon.com/xray/pricing/). ## Armazenar dependências de runtime em uma camada (SDK do X-Ray) Se você usar o X-Ray SDK para instrumentar os clientes do AWS SDK com seu código de função, seu pacote de implantação poderá se tornar bastante grande. Para evitar o upload de dependências de runtime todas as vezes que você atualizar seu código de função, empacote o SDK do X-Ray em uma [camada do Lambda](chapter-layers.md). O exemplo a seguir mostra um recurso `AWS::Serverless::LayerVersion` que armazena o AWS X-Ray SDK for Node.js. **Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs/template.yml): camada de dependências** ``` Resources: function: Type: [AWS::Serverless::Function](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html) Properties: CodeUri: function/. Tracing: Active Layers: - !Ref libs ... libs: Type: [AWS::Serverless::LayerVersion](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-layerversion.html) Properties: LayerName: blank-nodejs-lib Description: Dependencies for the blank sample app. ContentUri: lib/. CompatibleRuntimes: - nodejs24.x ``` Com essa configuração, você atualizará a camada de biblioteca somente se alterar as dependências de runtime. Já que o pacote de implantação de função inclui apenas o seu código, isso pode ajudar a reduzir o tempo de upload. A criação de uma camada de dependências requer alterações de compilação para gerar o arquivo da camada antes da implantação. Para obter um exemplo funcional, consulte o aplicativo de exemplo [blank-nodejs](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-nodejs) .