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.
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 7zipzip
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
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
Tópicos
- Dependências de runtime em Node.js
- Criar um pacote de implantação .zip sem dependências
- Criar um pacote de implantação .zip com dependências
- Criar uma camada Node.js para suas dependências
- Caminho de pesquisa de dependências e bibliotecas incluídas no runtime
- Criação e atualização de funções do Lambda em Node.js usando arquivos .zip
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 for JavaScript. O runtime do Lambda para nodejs16.x
inclui a versão 2.x do SDK. As versões de runtime nodejs18.x
e posteriores incluem a versão 3 do SDK. Para usar a versão 2 do SDK com as versões de runtime nodejs18.x
e posteriores, adicione o SDK ao arquivo .zip. do pacote de implantação. Se o runtime escolhido incluir a versão do SDK que você está usando, não será necessário incluir a biblioteca do SDK no arquivo .zip. Para descobrir qual versão do SDK está incluída no runtime que você está usando, consulte Versões do SDK incluídas no runtime.
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.
No modelo de responsabilidade compartilhada da AWS, 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 e Criação e atualização de funções do Lambda em Node.js usando arquivos .zip 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.
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. 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.
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
-
Navegue até o diretório do projeto que contém seu arquivo de código-fonte
index.js
ouindex.mjs
. Neste exemplo, o diretório se chamamy_function
.cd my_function
-
Instale as bibliotecas necessárias para a função no diretório
node_modules
usando o comandonpm 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. -
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.
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 a variável PATH
colete o conteúdo da camada, o arquivo .zip da camada deve ter suas dependências nos seguintes caminhos de pasta:
-
nodejs/node_modules
-
nodejs/node16/node_modules (NODE_PATH)
-
nodejs/node18/node_modules (NODE_PATH)
-
nodejs/node20/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 e Adicionar camadas às funções 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 for 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 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 seu pacote de implantação .zip, você poderá usá-lo para criar uma nova 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 AWS 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 executável as permissões corretas, execute o comando a seguir.
chmod 755 <filepath>
Para alterar as permissões de arquivo no Windows, consulte Set, View, Change, or Remove Permissions on an Object
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 AWS Management Console, consulte Conceitos básicos do Amazon S3. Para carregar arquivos usando a AWS CLI, consulte Mover objetos no Guia do usuário da AWS CLI.
nota
Você não pode alterar o tipo de pacote de implantação (.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)
-
Abra a página Funções
do console do Lambda e escolha Criar função. -
Escolha Author from scratch (Criar do zero).
-
Em Basic information (Informações básicas), faça o seguinte:
-
Em Nome da função, insira o nome da função.
-
Em Runtime, selecione o runtime que você deseja usar.
-
(Opcional) Em Arquitetura, escolha a arquitetura do conjunto de instruções para a função. O valor da arquitetura padrão é X86_64. 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.
-
-
(Opcional) Em Permissões, expanda Alterar função de execução padrão. Crie uma função de execução ou use uma existente.
-
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)
-
Na página Funções
do console Lambda, escolha a função para a qual você deseja carregar o arquivo .zip. -
Selecione a guia Código.
-
No painel do Código-fonte, escolha Carregar de.
-
Escolha o arquivo .zip.
-
Para carregar o arquivo .zip, faça o seguinte:
-
Selecione Carregar e, em seguida, selecione o arquivo .zip no seletor de arquivos.
-
Escolha Open (Abrir).
-
Escolha Salvar.
-
Para carregar um arquivo .zip de um bucket do Amazon S3 (console)
-
Na página Funções
do console do Lambda, escolha a função para a qual você deseja carregar um novo arquivo .zip. -
Selecione a guia Código.
-
No painel do Código-fonte, escolha Carregar de.
-
Escolha Local do Amazon S3.
-
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 deve ser menor que 3 MB.
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
-
Abra a página Funções
do console do Lambda e selecione a função. -
Selecione a guia Código.
-
No painel Código-fonte, selecione o arquivo de código-fonte e edite-o no editor de código integrado.
-
Quando terminar de editar o código, escolha Implantar para salvar as alterações e atualizar a função.
Criar e atualizar funções com arquivos .zip usando a AWS CLI
Você pode usar a AWS CLI para criar uma função ou atualizar uma existente usando um arquivo .zip. Use os comandos create-function e update-function-code 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 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 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 nodejs20.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 nodejs20.x --handler index.handler \ --role arn:aws:iam::111122223333:role/service-role/my-lambda-role \ --code S3Bucket=DOC-EXAMPLE-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 DOC-EXAMPLE-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:
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 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 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 comoZip
-
CodeUri
: definir como o URI do Amazon S3 do código da função, o caminho para a pasta local ou o objeto FunctionCode -
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 no Guia do desenvolvedor do AWS SAM.
Criar e atualizar funções com arquivos .zip usando o AWS CloudFormation
Você pode usar o AWS 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 no Guia do usuário da AWS CLI.
No modelo do AWS 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 comoZip
-
Code
: inserir o nome do bucket do Amazon S3 e o nome do arquivo .zip nos camposS3Bucket
eS3Key
-
Runtime
: definir como o runtime escolhido
O arquivo .zip que o AWS CloudFormation gera não pode exceder 4 MB. Para saber mais sobre a implantação de funções usando o arquivo .zip no AWS CloudFormation, consulte AWS::Lambda::Function no Guia do desenvolvedor do AWS CloudFormation.