# Construir funções do Lambda com Ruby Você pode executar o código Ruby no AWS Lambda. O Lambda fornece [runtimes](lambda-runtimes.md) para Ruby que executam seu código para processar eventos. Seu código é executado em um ambiente que inclui o AWS SDK para Ruby, 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 Ruby, consulte [Versões do SDK incluídas no runtime](#ruby-sdk-included). O Lambda oferece suporte aos seguintes runtimes do Ruby: | Nome | Identificador | Sistema operacional | Data da substituição | Bloquear a criação de funções | Bloquear a atualização de funções | | --- | --- | --- | --- | --- | --- | | Ruby 3.4 | `ruby3.4` | Amazon Linux 2023 | 31 de março de 2028 | 30 de abril de 2028 | 31 de maio de 2028 | | Ruby 3.3 | `ruby3.3` | Amazon Linux 2023 | 31 de março de 2027 | 30 de abril de 2027 | 31 de maio de 2027 | | Ruby 3.2 | `ruby3.2` | Amazon Linux 2 | 31 de março de 2026 | 31 de agosto de 2026 | 30 de setembro de 2026 | **Para criar uma função do Ruby** 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 o **Ruby 3.4**. 1. Escolha a opção **Criar função**. O console cria uma função do Lambda com um único arquivo de origem chamado `lambda_function.rb`. É 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 `lambda_function.rb` exporta uma função chamada `lambda_handler` que utiliza um objeto de evento e um objeto de contexto. Esta é a [função de manipulador](ruby-handler.md) que o Lambda chama quando a função é invocada. O runtime da função do Ruby obtém eventos de invocação do Lambda e os transmite ao handler. Na configuração da função, o valor do manipulador é `lambda_function.lambda_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](ruby-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](ruby-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](ruby-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 ](#ruby-sdk-included) + [ ## Como habilitar Yet Another Ruby JIT (YJIT) ](#ruby-yjit) + [ # Definir o manipulador de função do Lambda em Ruby ](ruby-handler.md) + [ # Implantar funções do Lambda em Ruby com arquivos .zip ](ruby-package.md) + [ # Implantar funções do Lambda em Ruby com imagens de contêiner ](ruby-image.md) + [ # Como trabalhar com camadas em Ruby para funções do Lambda ](ruby-layers.md) + [ # Usar o objeto de contexto do Lambda para recuperar informações das funções em Ruby ](ruby-context.md) + [ # Registrar em log e monitorar funções do Lambda em Ruby ](ruby-logging.md) + [ # Instrumentar o código Ruby no AWS Lambda ](ruby-tracing.md) ## Versões do SDK incluídas no runtime A versão do AWS SDK incluída no runtime do Ruby depende da versão do runtime e da Região da AWS. O AWS SDK para Ruby foi projetado para ser modular e é separado pelo AWS service (Serviço da AWS). Para encontrar o número da versão de um determinado gem de serviço incluído no runtime que você está usando, crie uma função do Lambda com o código no formato a seguir. Substitua `aws-sdk-s3` e `Aws::S3` pelo nome dos gems de serviço que o código usa. ``` require 'aws-sdk-s3' def lambda_handler(event:, context:) puts "Service gem version: #{Aws::S3::GEM_VERSION}" puts "Core version: #{Aws::CORE_GEM_VERSION}" end ``` ## Como habilitar Yet Another Ruby JIT (YJIT) Os runtimes do Ruby oferecem suporte ao [YJIT](https://docs.ruby-lang.org/en/master/jit/yjit_md.html), um compilador JIT para Ruby leve e minimalista. O YJIT fornece performance significativamente maior, mas também usa mais memória do que o interpretador Ruby. O YJIT é recomendado para workloads Ruby on Rails. Por padrão, o YJIT não está habilitado. Para habilitar o YJIT para uma função Ruby, defina a variável de ambiente `RUBY_YJIT_ENABLE` como `1`. Para confirmar que o YJIT está habilitado, imprima o resultado do método `RubyVM::YJIT.enabled?`. **Example : confirmação de que o YJIT está habilitado** ``` puts(RubyVM::YJIT.enabled?()) # => true ``` # Definir o manipulador de função do Lambda em Ruby 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. **Topics** + [ ## Conceitos básicos do handler em Ruby ](#ruby-handler-basics) + [ ## Práticas recomendadas de código para as funções do Lambda em Ruby ](#ruby-best-practices) ## Conceitos básicos do handler em Ruby No exemplo a seguir, o arquivo `function.rb` define um método de handler chamado `handler`. A função do handler usa dois objetos como entrada e retorna um documento JSON. **Example function.rb** ``` require 'json' def handler(event:, context:) { event: JSON.generate(event), context: JSON.generate(context.inspect) } end ``` Em sua configuração de função, a configuração `handler` informa o Lambda onde encontrar o manipulador. Para o exemplo anterior, o valor correto para essa configuração é **function.handler**. Ele inclui dois nomes separados por um ponto: o nome do arquivo e o nome do método do handler. Você também pode definir o método de handler em uma classe. O exemplo a seguir define um método de handler chamado `process` em uma classe denominada `Handler` em um módulo chamado `LambdaFunctions`. **Example source.rb** ``` module LambdaFunctions class Handler def self.process(event:,context:) "Hello!" end end end ``` Nesse caso, a configuração do handler é **source.LambdaFunctions::Handler.process**. Os dois objetos que o handler aceita são os eventos de invocação e contexto. O evento é um objeto Ruby que contém a carga que é fornecida pelo chamador. Se a carga útil for um documento JSON, o objeto de evento é um hash do Ruby. Caso contrário, é uma string. O [objeto de contexto](ruby-context.md) tem métodos e propriedades que fornecem informações sobre a invocação, a função e o ambiente de execução. O manipulador da função é executado sempre que sua função do Lambda é invocada. O código estático fora do handler é executado uma vez por instância da função. Se o handler usar recursos como clientes SDK e conexões de banco de dados, você poderá criá-los fora do método de handler para reutilizá-los para várias invocações. Cada instância de sua função pode processar vários eventos de invocação, mas ela processa apenas um evento por vez. O número de instâncias que processam um evento em um momento é a *simultaneidade* da sua função. Para obter mais informações sobre o ambiente de execução do Lambda, consulte [Noções básicas sobre o ciclo de vida do ambiente de execução do Lambda](lambda-runtime-environment.md). ## Práticas recomendadas de código para as funções do Lambda em Ruby Adote as diretrizes da lista a seguir para usar as práticas recomendadas de codificação ao compilar suas 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. Por exemplo, em Ruby, isso poderia ser assim: ``` def lambda_handler(event:, context:) foo = event['foo'] bar = event['bar'] result = my_lambda_function(foo:, bar:) end def my_lambda_function(foo:, bar:) // MyLambdaFunction logic here end ``` + **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 o runtime do Ruby, o AWS SDK está incluído. 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. Para funções criadas em Ruby, evite carregar toda a biblioteca de AWS SDKs como parte do pacote de implantação. Em vez disso, use seletivamente gems que coletem os componentes necessários do SDK (por exemplo, gems do SDK do DynamoDB ou do Amazon S3). **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 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 Ruby com arquivos .zip O código de sua função do AWS Lambda compreende um arquivo .rb contendo o código do manipulador da função, em conjunto com quaisquer dependências adicionais (gems) das quais o código depende. 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 o Ruby, consulte [Implantar funções do Lambda em Ruby com imagens de contêiner](https://docs.aws.amazon.com/lambda/latest/dg/ruby-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. Os comandos de exemplo nas seções a seguir usam o utilitário [Bundler](https://bundler.io/) para adicionar dependências ao pacote de implantação. Para instalar o Bundler, execute o comando a seguir. ``` gem install bundler ``` **Topics** + [ ## Dependências em Ruby ](#ruby-package-runtime-dependencies) + [ ## Criar um pacote de implantação .zip sem dependências ](#ruby-package-codeonly) + [ ## Criar um pacote de implantação .zip com dependências ](#ruby-package-dependencies) + [ ## Criar uma camada Ruby para suas dependências ](#ruby-package-dependencies-layers) + [ ## Criar pacotes de implantação .zip com bibliotecas nativas ](#ruby-package-native) + [ ## Criação e atualização de funções do Lambda em Ruby usando arquivos .zip ](#ruby-package-create-functions) ## Dependências em Ruby Para as funções do Lambda que usam o runtime do Ruby, uma dependência pode ser qualquer gem do Ruby. Ao implantar a função usando um arquivo .zip, você pode adicionar essas dependências ao arquivo .zip com o código da função ou usar uma camada do Lambda. Uma camada é um arquivo .zip que pode conter código adicional e outro conteúdo. Para saber mais sobre como usar as camadas do Lambda, consulte [Gerenciar dependências do Lambda com camadas](chapter-layers.md). O runtime do Ruby inclui o AWS SDK para Ruby. Caso a função use o SDK, você não precisa empacotá-lo com o código. No entanto, para manter o controle total das dependências ou para usar uma versão específica do SDK, você pode adicioná-lo ao pacote de implantação da função. É possível incluir o SDK em seu arquivo .zip ou adicioná-lo usando uma camada do Lambda. As dependências em seu arquivo .zip ou em camadas do Lambda têm precedência sobre as versões inclusas no runtime. Para descobrir qual versão do SDK para Ruby está incluída em sua versão de runtime, consulte [Versões do SDK incluídas no runtime](lambda-ruby.md#ruby-sdk-included). 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](#ruby-package-dependencies) e [Criação e atualização de funções do Lambda em Ruby usando arquivos .zip](#ruby-package-create-functions) 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, o arquivo .zip conterá somente o arquivo .rb com o código do manipulador da função. Use seu utilitário zip preferencial para criar um arquivo .zip com o arquivo .rb na raiz. Se o arquivo .rb não estiver na raiz do arquivo .zip, o Lambda não poderá executar seu 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 Ruby usando arquivos .zip](#ruby-package-create-functions). ## Criar um pacote de implantação .zip com dependências Caso o código de função dependa de gems do Ruby adicionais, você pode 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 nesta 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 Ruby para suas dependências](#ruby-package-dependencies-layers). Suponha que o código de função esteja salvo em um arquivo denominado `lambda_function.rb` no diretório do seu projeto. Os exemplos de comandos da CLI a seguir criam um arquivo .zip denominado `my_deployment_package.zip` que contém o código da função e suas dependências. **Para criar o pacote de implantação** 1. No diretório do seu projeto, crie um `Gemfile` para especificar as dependências. ``` bundle init ``` 1. Usando o editor de texto preferencial, edite o `Gemfile` para especificar as dependências da função. Por exemplo, para usar a gem TZInfo, edite o `Gemfile` para que se assemelhe ao apresentado a seguir. ``` source "https://rubygems.org" gem "tzinfo" ``` 1. Execute o comando a seguir para instalar as gems especificadas no `Gemfile` no diretório do seu projeto. Este comando define `vendor/bundle` como o caminho padrão para instalações de gem. ``` bundle config set --local path 'vendor/bundle' && bundle install ``` Você deve ver saída semelhante ao seguinte: ``` Fetching gem metadata from https://rubygems.org/........... Resolving dependencies... Using bundler 2.4.13 Fetching tzinfo 2.0.6 Installing tzinfo 2.0.6 ... ``` **nota** Para instalar gems de forma global novamente em outro momento, execute o comando a seguir. ``` bundle config set --local system 'true' ``` 1. Crie um arquivo .zip compactado contendo o arquivo `lambda_function.rb` com o código do manipulador da função e as dependências instaladas na etapa anterior. ``` zip -r my_deployment_package.zip lambda_function.rb vendor ``` Você deve ver saída semelhante ao seguinte: ``` adding: lambda_function.rb (deflated 37%) adding: vendor/ (stored 0%) adding: vendor/bundle/ (stored 0%) adding: vendor/bundle/ruby/ (stored 0%) adding: vendor/bundle/ruby/3.2.0/ (stored 0%) adding: vendor/bundle/ruby/3.2.0/build_info/ (stored 0%) adding: vendor/bundle/ruby/3.2.0/cache/ (stored 0%) adding: vendor/bundle/ruby/3.2.0/cache/aws-eventstream-1.0.1.gem (deflated 36%) ... ``` ## Criar uma camada Ruby para suas dependências Para saber mais como empacotar dependências do Ruby em uma camada do Lambda, consulte [Como trabalhar com camadas em Ruby para funções do Lambda](ruby-layers.md). ## Criar pacotes de implantação .zip com bibliotecas nativas Muitas gems conhecidas do Ruby, como `nokogiri`, `nio4r` e `mysql`, contêm extensões nativas gravadas em C. Ao adicionar bibliotecas contendo código C ao pacote de implantação, é necessário compilar o pacote corretamente para garantir que seja compatível com o ambiente de execução do Lambda. Para aplicações de produção, recomendamos desenvolver e implantar o código usando o AWS Serverless Application Model (AWS SAM). No AWS SAM, use a opção `sam build --use-container` para desenvolver a função dentro de um contêiner do Docker semelhante ao Lambda. Para saber mais sobre como usar o AWS SAM para implantar o código de função, consulte [Building applications](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build.html) no *Guia do desenvolvedor do AWS SAM*. Para criar um pacote de implantação .zip contendo gems com extensões nativas sem usar o AWS SAM, como alternativa, você pode usar um contêiner para empacotar suas dependências em um ambiente igual ao ambiente de runtime do Ruby no Lambda. Para concluir essas etapas, você deve ter o Docker instalado em sua máquina de compilação. Para saber mais sobre a instalação do Docker, consulte [Install Docker Engine](https://docs.docker.com/engine/install/). **Criar um pacote de implantação .zip em um contêiner do Docker** 1. Crie uma pasta em sua máquina de compilação local para salvar o contêiner. Dentro dessa pasta, crie um arquivo chamado `dockerfile` e cole o código a seguir nele. ``` FROM public.ecr.aws/sam/build-ruby3.2:latest-x86_64 RUN gem update bundler CMD "/bin/bash" ``` 1. Dentro da pasta em que você criou o `dockerfile`, execute o comando a seguir para criar o contêiner do Docker. ``` docker build -t awsruby32 . ``` 1. Navegue até o diretório do projeto que contém o arquivo `.rb` com o código do manipulador da função e o `Gemfile` especificando as dependências da função. De dentro desse diretório, execute o comando a seguir para iniciar o contêiner do Ruby no Lambda. ------ #### [ Linux/MacOS ] ``` docker run --rm -it -v $PWD:/var/task -w /var/task awsruby32 ``` **nota** No MacOS, você pode visualizar um aviso informando que a plataforma da imagem solicitada não corresponde à plataforma de host detectada. Ignore esse aviso. ------ #### [ Windows PowerShell ] ``` docker run --rm -it -v ${pwd}:var/task -w /var/task awsruby32 ``` ------ Quando o contêiner for iniciado, você deverá ver um prompt de bash. ``` bash-4.2# ``` 1. Configure o utilitário empacotado para instalar as gems especificadas no `Gemfile` em um diretório local de `vendor/bundle` e instale as dependências. ``` bash-4.2# bundle config set --local path 'vendor/bundle' && bundle install ``` 1. Crie o pacote de implantação .zip com o código de função e as dependências. Neste exemplo, o arquivo que contém o código do manipulador da função é denominado `lambda_function.rb`. ``` bash-4.2# zip -r my_deployment_package.zip lambda_function.rb vendor ``` 1. Saia do contêiner e retorne ao diretório local do projeto. ``` bash-4.2# exit ``` Agora é possível usar o pacote de implantação de arquivo .zip para criar ou atualizar sua função do Lambda. Consulte [Criação e atualização de funções do Lambda em Ruby usando arquivos .zip](#ruby-package-create-functions) ## Criação e atualização de funções do Lambda em Ruby 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 ruby3.2 --handler lambda_function.lambda_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 ruby3.2 --handler lambda_function.lambda_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 Ruby com imagens de contêiner Existem três maneiras de criar uma imagem de contêiner para uma função do Lambda em Ruby: + [Usar uma imagem base da AWS para Ruby](#ruby-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. Também é possível 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 do Ruby](#ruby-image-clients) na imagem. + [Usar uma imagem base que não é da AWS](#ruby-image-clients) Também é possível usar uma imagem base alternativa de outro registro de contêiner, como Alpine Linux ou Debian. Também é possível 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 do Ruby](#ruby-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 Ruby ](#ruby-image-base) + [ ## Usar uma imagem base da AWS para Ruby ](#ruby-image-instructions) + [ ## Usar uma imagem base alternativa com o cliente da interface de runtime ](#ruby-image-clients) ## Imagens base da AWS para Ruby A AWS oferece as seguintes imagens base para Ruby: | Tags | Runtime | Sistema operacional | Dockerfile | Desaprovação | | --- | --- | --- | --- | --- | | 3.4 | Ruby 3.4 | Amazon Linux 2023 | [Dockerfile para Ruby 3.4 no GitHub](https://github.com/aws/aws-lambda-base-images/blob/ruby3.4/Dockerfile.ruby3.4) | 31 de março de 2028 | | 3.3 | Ruby 3.3 | Amazon Linux 2023 | [Dockerfile para Ruby 3.3 no GitHub](https://github.com/aws/aws-lambda-base-images/blob/ruby3.3/Dockerfile.ruby3.3) | 31 de março de 2027 | | 3.2 | Ruby 3.2 | Amazon Linux 2 | [Dockerfile para Ruby 3.2 no GitHub](https://github.com/aws/aws-lambda-base-images/blob/ruby3.2/Dockerfile.ruby3.2) | 31 de março de 2026 | Repositório do Amazon ECR: [gallery.ecr.aws/lambda/ruby](https://gallery.ecr.aws/lambda/ruby) ## Usar uma imagem base da AWS para Ruby ### 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. + Ruby ### Criação de uma imagem a partir de uma imagem base **Para criar uma imagem de contêiner para Ruby** 1. Crie um diretório para o projeto e depois mude para esse diretório. ``` mkdir example cd example ``` 1. Crie um novo arquivo chamado `Gemfile`. É aqui que você lista os pacotes do RubyGems necessários da sua aplicação. O AWS SDK para Ruby está disponível no RubyGems. Você deve escolher gems de serviço da AWS específicos para instalar. Por exemplo, para usar o [gem do Ruby para Lambda](https://rubygems.org/gems/aws-sdk-lambda/), seu Gemfile deve ser: ``` source 'https://rubygems.org' gem 'aws-sdk-lambda' ``` Como alternativa, o gem [aws-sdk](https://rubygems.org/gems/aws-sdk/) contém todos os gems de serviço da AWS disponíveis. Esse gem é muito grande. Recomendamos que ele só seja usado se você depender de muitos serviços da AWS. 1. Instale as dependências especificadas no Gemfile usando [instalação de pacote](https://bundler.io/v2.4/man/bundle-install.1.html). ``` bundle install ``` 1. Crie um novo arquivo chamado `lambda_function.rb`. É 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 Função Ruby** ``` module LambdaFunction class Handler def self.process(event:,context:) "Hello from Lambda!" end end end ``` 1. Crie um novo Dockerfile. É mostrado a seguir um exemplo de Dockerfile que usa uma [imagem base da AWS](images-create.md#runtimes-images-lp). Esse Dockerfile usa a seguinte configuração: + Defina a propriedade `FROM` como o URI da imagem base. + 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/ruby:3.4 # Copy Gemfile and Gemfile.lock COPY Gemfile Gemfile.lock ${LAMBDA_TASK_ROOT}/ # Install Bundler and the specified gems RUN gem install bundler:2.4.20 && \ bundle config set --local path 'vendor/bundle' && \ bundle install # Copy function code COPY lambda_function.rb ${LAMBDA_TASK_ROOT}/ # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "lambda_function.LambdaFunction::Handler.process" ] ``` 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 para Ruby](https://rubygems.org/gems/aws_lambda_ric) usando o gerenciador de pacotes RubyGems.org: ``` gem install aws_lambda_ric ``` Também é possível fazer download do [cliente de interface de runtime do Ruby](https://github.com/aws/aws-lambda-ruby-runtime-interface-client) no GitHub. O exemplo a seguir demonstra como criar uma imagem de contêiner para Ruby usando uma imagem base que não é da AWS. O exemplo de Dockerfile usa uma imagem base oficial do Ruby. 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. + Ruby ### Criar uma imagem de uma imagem base alternativa **Para criar uma imagem de contêiner usando uma imagem base alternativa do Ruby** 1. Crie um diretório para o projeto e depois mude para esse diretório. ``` mkdir example cd example ``` 1. Crie um novo arquivo chamado `Gemfile`. É aqui que você lista os pacotes do RubyGems necessários da sua aplicação. O AWS SDK para Ruby está disponível no RubyGems. Você deve escolher gems de serviço da AWS específicos para instalar. Por exemplo, para usar o [gem do Ruby para Lambda](https://rubygems.org/gems/aws-sdk-lambda/), seu Gemfile deve ser: ``` source 'https://rubygems.org' gem 'aws-sdk-lambda' ``` Como alternativa, o gem [aws-sdk](https://rubygems.org/gems/aws-sdk/) contém todos os gems de serviço da AWS disponíveis. Esse gem é muito grande. Recomendamos que ele só seja usado se você depender de muitos serviços da AWS. 1. Instale as dependências especificadas no Gemfile usando [instalação de pacote](https://bundler.io/v2.4/man/bundle-install.1.html). ``` bundle install ``` 1. Crie um novo arquivo chamado `lambda_function.rb`. É 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 Função Ruby** ``` module LambdaFunction class Handler def self.process(event:,context:) "Hello from Lambda!" end end end ``` 1. Crie um novo Dockerfile. O Dockerfile a seguir usa uma imagem base do Ruby em vez de uma [imagem base da AWS](images-create.md#runtimes-images-lp). O Dockerfile inclui o [cliente de interface de runtime do Ruby](https://github.com/aws/aws-lambda-ruby-runtime-interface-client), o que torna a imagem compatível com o Lambda. Como alternativa, você pode adicionar o cliente da interface de runtime ao Gemfile da aplicação. + Defina a propriedade `FROM` como a imagem básica do Ruby. + Crie um diretório para o código da função e uma variável de ambiente que aponte para esse diretório. Neste exemplo, o diretório é `/var/task`, que espelha o ambiente de execução do Lambda. No entanto, você pode escolher qualquer diretório para o código da função, pois o Dockerfile não usa uma imagem básica da AWS. + 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** ``` FROM ruby:2.7 # Install the runtime interface client for Ruby RUN gem install aws_lambda_ric # Add the runtime interface client to the PATH ENV PATH="/usr/local/bundle/bin:${PATH}" # Create a directory for the Lambda function ENV LAMBDA_TASK_ROOT=/var/task RUN mkdir -p ${LAMBDA_TASK_ROOT} WORKDIR ${LAMBDA_TASK_ROOT} # Copy Gemfile and Gemfile.lock COPY Gemfile Gemfile.lock ${LAMBDA_TASK_ROOT}/ # Install Bundler and the specified gems RUN gem install bundler:2.4.20 && \ bundle config set --local path 'vendor/bundle' && \ bundle install # Copy function code COPY lambda_function.rb ${LAMBDA_TASK_ROOT}/ # Set runtime interface client as default command for the container runtime ENTRYPOINT [ "aws_lambda_ric" ] # Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile) CMD [ "lambda_function.LambdaFunction::Handler.process" ] ``` 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. + `aws_lambda_ric lambda_function.LambdaFunction::Handler.process` é 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 \ aws_lambda_ric lambda_function.LambdaFunction::Handler.process ``` ------ #### [ 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 ` aws_lambda_ric lambda_function.LambdaFunction::Handler.process ``` ------ 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 ``` # Como trabalhar com camadas em Ruby para funções do Lambda 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 ](#ruby-layers-package) + [ ## Criar a camada no Lambda ](#publishing-layer) + [ ## Como usar gems de camadas em uma função ](#ruby-layers-bundler-limitations) + [ ## Adicionar a camada à função ](#ruby-layer-adding) + [ ## Aplicação de amostra ](#ruby-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 Ruby que você planeja usar para a função do Lambda. Por exemplo, se você criar a camada para o Ruby 3.4, use o runtime do Ruby 3.4 para a função. + O arquivo .zip da camada deve usar uma destas estruturas de diretório: + `ruby/gems/x.x.x` (onde *x.x.x* é sua versão do Ruby, por exemplo `3.4.0`) + `ruby/lib` 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 gems em Ruby de terceiros ou seus próprios módulos e classes em Ruby. Muitos gems em Ruby populares contêm extensões nativas (código C) que devem ser compiladas para o ambiente Lambda Linux. ### Gems em Ruby Pure Os gems em Ruby puras contêm somente código Ruby e não precisam de compilação. Essas geas são mais simples de empacotar e trabalhar em diferentes plataformas. **Para criar uma camada usando os gems em Ruby Pure** 1. Crie um `Gemfile` para especificar os gems em Ruby Pure que você deseja incluir na sua camada: **Example Gemfile** ``` source 'https://rubygems.org' gem 'tzinfo' ``` 1. Instale os gems no diretório `vendor/bundle` usando o Bundler: ``` bundle config set --local path vendor/bundle bundle install ``` 1. Copie os gems instalados para a estrutura de diretórios exigida pelo Lambda`ruby/gems/3.4.0`): ``` mkdir -p ruby/gems/3.4.0 cp -r vendor/bundle/ruby/3.4.0*/* ruby/gems/3.4.0/ ``` 1. Crie um arquivo .zip do conteúdo da camada: ------ #### [ Linux/macOS ] ``` zip -r layer.zip ruby/ ``` ------ #### [ PowerShell ] ``` Compress-Archive -Path .\ruby -DestinationPath .\layer.zip ``` ------ A estrutura de diretórios do arquivo zip deve ser assim: ``` ruby/ └── gems/ └── 3.4.0/ ├── gems/ │ ├── concurrent-ruby-1.3.5/ │ └── tzinfo-2.0.6/ ├── specifications/ ├── cache/ ├── build_info/ └── (other bundler directories) ``` **nota** Você deve exigir cada gem individualmente em seu código de função. Você pode usar `bundler/setup` ou `Bundler.require`. Para obter mais informações, consulte [Como usar gems de camadas em uma função](#ruby-layers-bundler-limitations). ### Gems com extensões nativas Muitos gems em Ruby populares contêm extensões nativas (código C) que devem ser compiladas para a plataforma de destino. Gemas populares com extensões nativas incluem [nokogiri](https://rubygems.org/gems/nokogiri/), [pg](https://rubygems.org/gems/pg/), [mysql2](https://rubygems.org/gems/mysql2/), [sqlite3](https://rubygems.org/gems/sqlite3/) e [ffi](https://rubygems.org/gems/ffi/). Esses gems devem ser criados em um ambiente Linux compatível com o runtime do Lambda. **Para criar uma camada usando gems com extensões nativas** 1. Crie um `Gemfile`. **Example Gemfile** ``` source 'https://rubygems.org' gem 'nokogiri' gem 'httparty' ``` 1. Use o Docker para criar os gems em um ambiente Linux compatível com o Lambda. Especifique uma [imagem base da AWS](ruby-image.md#ruby-image-base) em seu Dockerfile: **Example Dockerfile para Ruby 3.4** ``` FROM public.ecr.aws/lambda/ruby:3.4 # Copy Gemfile COPY Gemfile ./ # Install system dependencies for native extensions RUN dnf update -y && \ dnf install -y gcc gcc-c++ make # Configure bundler and install gems RUN bundle config set --local path vendor/bundle && \ bundle install # Create the layer structure RUN mkdir -p ruby/gems/3.4.0 && \ cp -r vendor/bundle/ruby/3.4.0*/* ruby/gems/3.4.0/ # Create the layer zip file RUN zip -r layer.zip ruby/ ``` 1. Crie a imagem e extraia a camada: ``` docker build -t ruby-layer-builder . docker run --rm -v $(pwd):/output --entrypoint cp ruby-layer-builder layer.zip /output/ ``` Isso cria os gems no ambiente Linux correto e copia o arquivo `layer.zip` para o diretório local. A estrutura de diretórios do arquivo zip deve ser assim: ``` ruby/ └── gems/ └── 3.4.0/ ├── gems/ │ ├── bigdecimal-3.2.2/ │ ├── csv-3.3.5/ │ ├── httparty-0.23.1/ │ ├── mini_mime-1.1.5/ │ ├── multi_xml-0.7.2/ │ ├── nokogiri-1.18.8-x86_64-linux-gnu/ │ └── racc-1.8.1/ ├── build_info/ ├── cache/ ├── specifications/ └── (other bundler directories) ``` **nota** Você deve exigir cada gem individualmente em seu código de função. Você pode usar `bundler/setup` ou `Bundler.require`. Para obter mais informações, consulte [Como usar gems de camadas em uma função](#ruby-layers-bundler-limitations). ### Módulos em Ruby 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 ruby/lib ``` 1. Crie seus módulos de Ruby no diretório `ruby/lib`. O exemplo de módulo a seguir valida os pedidos confirmando que eles contêm as informações necessárias. **Example ruby/lib/order\$1validator.rb** ``` require 'json' module OrderValidator class ValidationError < StandardError; end def self.validate_order(order_data) # Validates an order and returns formatted data required_fields = %w[product_id quantity] # Check required fields missing_fields = required_fields.reject { |field| order_data.key?(field) } unless missing_fields.empty? raise ValidationError, "Missing required fields: #{missing_fields.join(', ')}" end # Validate quantity quantity = order_data['quantity'] unless quantity.is_a?(Integer) && quantity > 0 raise ValidationError, 'Quantity must be a positive integer' end # Format and return the validated data { 'product_id' => order_data['product_id'].to_s, 'quantity' => quantity, 'shipping_priority' => order_data.fetch('priority', 'standard') } end def self.format_response(status_code, body) # Formats the API response { statusCode: status_code, body: JSON.generate(body) } end end ``` 1. Crie um arquivo .zip do conteúdo da camada: ------ #### [ Linux/macOS ] ``` zip -r layer.zip ruby/ ``` ------ #### [ PowerShell ] ``` Compress-Archive -Path .\ruby -DestinationPath .\layer.zip ``` ------ A estrutura de diretórios do arquivo zip deve ser assim: ``` ruby/ └── lib/ └── order_validator.rb ``` 1. Na função, exija e use os módulos. Você deve exigir cada gem individualmente em seu código de função. Você pode usar `bundler/setup` ou `Bundler.require`. Para obter mais informações, consulte [Como usar gems de camadas em uma função](#ruby-layers-bundler-limitations). Exemplo: ``` require 'json' require 'order_validator' def lambda_handler(event:, context:) begin # Parse the order data from the event body order_data = JSON.parse(event['body'] || '{}') # Validate and format the order validated_order = OrderValidator.validate_order(order_data) OrderValidator.format_response(200, { message: 'Order validated successfully', order: validated_order }) rescue OrderValidator::ValidationError => e OrderValidator.format_response(400, { error: e.message }) rescue => e OrderValidator.format_response(500, { error: 'Internal server error' }) end end ``` Você pode usar os seguinte [evento de teste](testing-functions.md#invoke-with-event)para invocar a função: ``` { "body": "{\"product_id\": \"ABC123\", \"quantity\": 2, \"priority\": \"express\"}" } ``` Resposta esperada: ``` { "statusCode": 200, "body": "{\"message\":\"Order validated successfully\",\"order\":{\"product_id\":\"ABC123\",\"quantity\":2,\"shipping_priority\":\"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 ruby3.4 ``` 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 Ruby que corresponde à versão do Ruby que você usou para criar a camada. 1. Escolha **Criar**. ------ ## Como usar gems de camadas em uma função Em seu código de função, você deve exigir explicitamente cada gem que você deseja usar. Comandos do bundler, como `bundler/setup` e `Bundler.require` não são compatíveis. Veja como usar corretamente os gems de uma camada em uma função do Lambda: ``` # Correct: Use explicit requires for each gem require 'nokogiri' require 'httparty' def lambda_handler(event:, context:) # Use the gems directly doc = Nokogiri::HTML(event['html']) response = HTTParty.get(event['url']) # ... rest of your function end # Incorrect: These Bundler commands will not work # require 'bundler/setup' # Bundler.require ``` ## 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-ruby](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/layer-ruby) no repositório AWS Lambda Developer Guide do GitHub. Essa aplicação inclui uma camada que contém a biblioteca [zinfo](https://rubygems.org/gems/tzinfo). 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 Ruby Quando o Lambda executa a função, ele transmite um objeto de contexto para o [handler](ruby-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** + `get_remaining_time_in_millis`: retorna o número de milissegundos restantes antes do tempo limite da execução. **Propriedades de contexto** + `function_name`: o nome da função do Lambda. + `function_version`: a [versão](configuration-versions.md) da função. + `invoked_function_arn`: 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. + `memory_limit_in_mb`: a quantidade de memória alocada para a função. + `aws_request_id`: o identificador da solicitação de invocação. + `log_group_name`: o grupo de logs da função. + `log_stream_name`: a transmissão de log para a instância da função. + `deadline_ms`: a data em que a função expira em milissegundos de tempo do Unix. + `identity`: (aplicativos móveis) informações sobre a identidade do Amazon Cognito que autorizou a solicitação. + `client_context`: (aplicativos móveis) contexto do cliente fornecido ao Lambda pela aplicação cliente. # Registrar em log e monitorar funções do Lambda em Ruby 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 ](#ruby-logging-output) + [ ## Visualizar logs no console do Lambda ](#ruby-logging-console) + [ ## Visualização de logs no console do CloudWatch ](#ruby-logging-cwconsole) + [ ## Visualizar logs usando a AWS Command Line Interface (AWS CLI) ](#ruby-logging-cli) + [ ## Excluir logs ](#ruby-logging-delete) + [ ## Trabalhar com a biblioteca de registro em log do Ruby ](#ruby-logging-lib) ## Criar uma função que retorna logs Para gerar os logs do seu código de função, você pode usar instruções `puts` ou qualquer biblioteca de logs que grave no `stdout` ou no `stderr`. O exemplo a seguir registra em log os valores das variáveis de ambiente e o objeto do evento. **Example lambda\$1function.rb** ``` # lambda_function.rb def handler(event:, context:) puts "## ENVIRONMENT VARIABLES" puts ENV.to_a puts "## EVENT" puts event.to_a end ``` **Example formato do log** ``` START RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Version: $LATEST ## ENVIRONMENT VARIABLES environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]3893xmpl7fac4485b47bb75b671a283c', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...}) ## EVENT {'key': 'value'} END RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 REPORT RequestId: 8f507cfc-xmpl-4697-b07a-ac58fc914c95 Duration: 15.74 ms Billed Duration: 147 ms Memory Size: 128 MB Max Memory Used: 56 MB Init Duration: 130.49 ms XRAY TraceId: 1-5e34a614-10bdxmplf1fb44f07bc535a1 SegmentId: 07f5xmpl2d1f6f85 Sampled: true ``` O runtime do Ruby registra em log as linhas `START`, `END` e `REPORT` para cada invocaçã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. Para obter logs mais detalhados, use a [Trabalhar com a biblioteca de registro em log do Ruby](#ruby-logging-lib). ## 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. ## Trabalhar com a biblioteca de registro em log do Ruby A [biblioteca do logger](https://ruby-doc.org/stdlib-2.7.0/libdoc/logger/rdoc/index.html) do Ruby retorna logs simplificados que são facilmente lidos. Use o utilitário logger para gerar informações detalhadas, mensagens e códigos de erro relacionados à sua função. ``` # lambda_function.rb require 'logger' def handler(event:, context:) logger = Logger.new($stdout) logger.info('## ENVIRONMENT VARIABLES') logger.info(ENV.to_a) logger.info('## EVENT') logger.info(event) event.to_a end ``` A saída de `logger` inclui o nível do log, o timestamp e o ID da solicitação. ``` START RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 Version: $LATEST [INFO] 2020-01-31T22:12:58.534Z 1c8df7d3-xmpl-46da-9778-518e6eca8125 ## ENVIRONMENT VARIABLES [INFO] 2020-01-31T22:12:58.534Z 1c8df7d3-xmpl-46da-9778-518e6eca8125 environ({'AWS_LAMBDA_LOG_GROUP_NAME': '/aws/lambda/my-function', 'AWS_LAMBDA_LOG_STREAM_NAME': '2020/01/31/[$LATEST]1bbe51xmplb34a2788dbaa7433b0aa4d', 'AWS_LAMBDA_FUNCTION_NAME': 'my-function', ...}) [INFO] 2020-01-31T22:12:58.535Z 1c8df7d3-xmpl-46da-9778-518e6eca8125 ## EVENT [INFO] 2020-01-31T22:12:58.535Z 1c8df7d3-xmpl-46da-9778-518e6eca8125 {'key': 'value'} END RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 REPORT RequestId: 1c8df7d3-xmpl-46da-9778-518e6eca8125 Duration: 2.75 ms Billed Duration: 117 ms Memory Size: 128 MB Max Memory Used: 56 MB Init Duration: 113.51 ms XRAY TraceId: 1-5e34a66a-474xmpl7c2534a87870b4370 SegmentId: 073cxmpl3e442861 Sampled: true ``` # Instrumentar o código Ruby no AWS Lambda O Lambda se integra ao AWS X-Ray para permitir que você rastreie, depure e otimize aplicativos do Lambda. É possível usar o X-Ray para rastrear uma solicitação à medida que ela atravessa recursos na aplicação, da API de frontend ao armazenamento e aos banco de dados no backend. Ao simplesmente adicionar a biblioteca do X-Ray SDK à configuração de compilação, é possível registrar erros e latência para qualquer chamada que a função faça para um serviço da AWS. 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) 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**. **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/). 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. 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). É possível instrumentar o código do manipulador para gravar metadados e rastrear chamadas downstream. Para registrar detalhes sobre chamadas feitas pelo manipulador para outros recursos e serviços, use o X-Ray SDK for Ruby. Para obter o SDK, adicione o pacote `aws-xray-sdk` às dependências do aplicativo. **Example [blank-ruby/function/Gemfile](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-ruby/function/Gemfile)** ``` # Gemfile source 'https://rubygems.org' gem 'aws-xray-sdk', '0.11.4' gem 'aws-sdk-lambda', '1.39.0' gem 'test-unit', '3.3.5' ``` Para instrumentar clientes do AWS SDK, solicite o módulo `aws-xray-sdk/lambda` depois de criar um cliente no código de inicialização. **Example [blank-ruby/function/lambda\$1function.rb](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-ruby/function/lambda_function.rb): rastrear um cliente do AWS SDK** ``` # lambda_function.rb require 'logger' require 'json' require 'aws-sdk-lambda' $client = Aws::Lambda::Client.new() $client.get_account_settings() require 'aws-xray-sdk/lambda' def lambda_handler(event:, context:) logger = Logger.new($stdout) ... ``` 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 [The X-Ray SDK for Ruby](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-ruby.html) no Guia do desenvolvedor do AWS X-Ray. **Topics** + [ ## Habilitar o rastreamento ativo com a API do Lambda ](#ruby-tracing-api) + [ ## Habilitar o rastreamento ativo com o CloudFormation ](#ruby-tracing-cloudformation) + [ ## Armazenar dependências de runtime em uma camada ](#ruby-tracing-layers) ## Habilitar o rastreamento ativo com a API do Lambda Para gerenciar a configuração de rastreamento com a AWS CLI ou com o AWS SDK, use 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. ## Habilitar o rastreamento ativo 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 ... ``` ## Armazenar dependências de runtime em uma camada 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 X-Ray SDK for Ruby. **Example [template.yml](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-ruby/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-ruby-lib Description: Dependencies for the blank-ruby sample app. ContentUri: lib/. CompatibleRuntimes: - ruby2.5 ``` 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-ruby](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/blank-ruby).