Tutorial: usar o Lambda com o Amazon SQS - AWS Lambda

Tutorial: usar o Lambda com o Amazon SQS

Neste tutorial, você criará uma função do Lambda que consome mensagens de uma fila do Amazon Simple Queue Service (Amazon SQS). A função do Lambda é executada sempre que uma nova mensagem é adicionada à fila. A função grava as mensagens em um fluxo do Amazon CloudWatch Logs. O diagrama a seguir mostrará os recursos da AWS que você usará para concluir o tutorial.

Diagrama mostrando a mensagem do Amazon SQS, a função do Lambda e o fluxo do CloudWatch Logs

Para concluir este tutorial, execute as seguintes tarefas:

  1. Crie uma função do Lambda que grave mensagens no CloudWatch Logs.

  2. Criar uma fila do Amazon SQS.

  3. Crie um mapeamento da origem do evento do Lambda. O mapeamento da origem do evento realiza a leitura da fila do Amazon SQS e invoca a função do Lambda quando uma nova mensagem é adicionada.

  4. Teste a configuração ao adicionar mensagens à sua fila e ao monitorar os resultados no CloudWatch Logs.

Pré-requisitos

Se você ainda não tem Conta da AWS, siga as etapas a seguir para criar um.

Para se cadastrar em uma Conta da AWS
  1. Abra https://portal.aws.amazon.com/billing/signup.

  2. Siga as instruções online.

    Parte do procedimento de inscrição envolve receber uma chamada telefônica e inserir um código de verificação no teclado do telefone.

    Quando você se cadastra em uma Conta da AWS, um Usuário raiz da conta da AWS é criado. O usuário raiz tem acesso a todos os Serviços da AWS e atributos na conta. Como prática recomendada de segurança, atribua o acesso administrativo a um usuário e use somente o usuário-raiz para executar tarefas que exigem acesso de usuário-raiz.

A AWS envia um e-mail de confirmação depois que o processo de cadastramento é concluído. A qualquer momento, é possível visualizar as atividades da conta atual e gerenciar sua conta acessando https://aws.amazon.com/ e selecionando Minha conta.

Depois de se cadastrar em uma Conta da AWS, proteja seu Usuário raiz da conta da AWS, habilite o AWS IAM Identity Center e crie um usuário administrativo para não usar o usuário raiz em tarefas cotidianas.

Proteger seu Usuário raiz da conta da AWS
  1. Faça login no AWS Management Console como o proprietário da conta ao escolher a opção Usuário raiz e inserir o endereço de e-mail da Conta da AWS. Na próxima página, insira sua senha.

    Para obter ajuda ao fazer login usando o usuário raiz, consulte Fazer login como usuário raiz no Guia do usuário do Início de Sessão da AWS.

  2. Habilite a autenticação multifator (MFA) para o usuário raiz.

    Para obter instruções, consulte Habilitar um dispositivo MFA virtual para o usuário raiz de sua conta da Conta da AWS (console) no Guia do usuário do IAM.

Criar um usuário com acesso administrativo
  1. Habilitar o IAM Identity Center.

    Para obter instruções, consulte Habilitar AWS IAM Identity Center no Guia do usuário do AWS IAM Identity Center.

  2. No Centro de Identidade do IAM, conceda o acesso administrativo para um usuário.

    Para obter um tutorial sobre como usar o Diretório do Centro de Identidade do IAM como fonte de identidade, consulte Configurar o acesso dos usuários com o Diretório do Centro de Identidade do IAM padrão no Guia do usuário do AWS IAM Identity Center.

Iniciar sessão como o usuário com acesso administrativo
  • Para fazer login com seu usuário do Centro de Identidade do IAM, use o URL de login que foi enviado ao seu endereço de e-mail quando você criou o usuário do Centro do Usuário do IAM.

    Para obter ajuda com o login utilizando um usuário do Centro de Identidade do IAM, consulte Fazer login no portal de acesso da AWS, no Guia do usuário do Início de Sessão da AWS.

Atribuir acesso a usuários adicionais
  1. No Centro de Identidade do IAM, crie um conjunto de permissões que siga as práticas recomendadas de aplicação de permissões com privilégio mínimo.

    Para obter instruções, consulte Create a permission set no Guia do usuário do AWS IAM Identity Center.

  2. Atribua usuários a um grupo e, em seguida, atribua o acesso de autenticação única ao grupo.

    Para obter instruções, consulte Add groups no Guia do usuário do AWS IAM Identity Center.

Se você ainda não instalou a AWS Command Line Interface, siga as etapas em Instalar ou atualizar a versão mais recente da AWS CLI para instalá-la.

O tutorial requer um terminal de linha de comando ou um shell para executar os comandos. No Linux e no macOS, use o gerenciador de pacotes e de shell de sua preferência.

nota

No Windows, alguns comandos da CLI do Bash que você costuma usar com o Lambda (como zip) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, instale o Subsistema do Windows para Linux.

Criar a função de execução

Etapa 1: criar o perfil de execução

Um perfil de execução é um perfil do AWS Identity and Access Management (IAM) que concede a uma função do Lambda permissão para acessar serviços e recursos da AWS. Para permitir que a função realize a leitura de itens do Amazon SQS, anexe a política de permissões AWSLambdaSQSQueueExecutionRole.

Criar um perfil de execução e anexar uma política de permissões do Amazon SQS
  1. Abra a página Roles (Funções) no console do IAM.

  2. Selecione Criar função.

  3. Em Tipo de entidade confiável, escolha Serviços da AWS.

  4. Em Caso de uso, escolha Lambda.

  5. Escolha Próximo.

  6. Na caixa de pesquisa Políticas de permissões, insira AWSLambdaSQSQueueExecutionRole.

  7. Selecione a política AWSLambdaSQSQueueExecutionRole e, em seguida, escolha Próximo.

  8. Em Detalhes do perfil, para Nome do perfil, insira lambda-sqs-role e, em seguida, escolha Criar perfil.

Após a criação da função, anote o nome de recurso da Amazon (ARN) do seu perfil de execução. Você precisará dele em etapas posteriores.

Criar a função

Etapa 2: criar a função do Lambda

Crie uma função do Lambda queprocessesuas mensagens do Amazon SQS. O código da função registra o corpo da mensagem do Amazon SQS no CloudWatch Logs.

Este tutorial usa o runtime do Node.js 18.x, mas também fornecemos exemplos de arquivos em outras linguagens de runtime. Você pode selecionar a guia na caixa a seguir para ver o código do runtime do seu interesse. O código JavaScript que você usará nesta etapa é o primeiro exemplo mostrado na guia JavaScript.

.NET
AWS SDK for .NET
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando .NET.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 using Amazon.Lambda.Core; using Amazon.Lambda.SQSEvents; // Assembly attribute to enable the Lambda function's JSON input to be converted into a .NET class. [assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))] namespace SqsIntegrationSampleCode { public async Task FunctionHandler(SQSEvent evnt, ILambdaContext context) { foreach (var message in evnt.Records) { await ProcessMessageAsync(message, context); } context.Logger.LogInformation("done"); } private async Task ProcessMessageAsync(SQSEvent.SQSMessage message, ILambdaContext context) { try { context.Logger.LogInformation($"Processed message {message.Body}"); // TODO: Do interesting work based on the new message await Task.CompletedTask; } catch (Exception e) { //You can use Dead Letter Queue to handle failures. By configuring a Lambda DLQ. context.Logger.LogError($"An error occurred"); throw; } } }
Go
SDK para Go V2
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando Go.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 package integration_sqs_to_lambda import ( "fmt" "github.com/aws/aws-lambda-go/events" "github.com/aws/aws-lambda-go/lambda" ) func handler(event events.SQSEvent) error { for _, record := range event.Records { err := processMessage(record) if err != nil { return err } } fmt.Println("done") return nil } func processMessage(record events.SQSMessage) error { fmt.Printf("Processed message %s\n", record.Body) // TODO: Do interesting work based on the new message return nil } func main() { lambda.Start(handler) }
Java
SDK para Java 2.x
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando Java.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; import com.amazonaws.services.lambda.runtime.events.SQSEvent; import com.amazonaws.services.lambda.runtime.events.SQSEvent.SQSMessage; public class Function implements RequestHandler<SQSEvent, Void> { @Override public Void handleRequest(SQSEvent sqsEvent, Context context) { for (SQSMessage msg : sqsEvent.getRecords()) { processMessage(msg, context); } context.getLogger().log("done"); return null; } private void processMessage(SQSMessage msg, Context context) { try { context.getLogger().log("Processed message " + msg.getBody()); // TODO: Do interesting work based on the new message } catch (Exception e) { context.getLogger().log("An error occurred"); throw e; } } }
JavaScript
SDK para JavaScript (v3)
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando JavaScript.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 exports.handler = async (event, context) => { for (const message of event.Records) { await processMessageAsync(message); } console.info("done"); }; async function processMessageAsync(message) { try { console.log(`Processed message ${message.body}`); // TODO: Do interesting work based on the new message await Promise.resolve(1); //Placeholder for actual async work } catch (err) { console.error("An error occurred"); throw err; } }

Consumir um evento do SQS com o Lambda usando TypeScript.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 import { SQSEvent, Context, SQSHandler, SQSRecord } from "aws-lambda"; export const functionHandler: SQSHandler = async ( event: SQSEvent, context: Context ): Promise<void> => { for (const message of event.Records) { await processMessageAsync(message); } console.info("done"); }; async function processMessageAsync(message: SQSRecord): Promise<any> { try { console.log(`Processed message ${message.body}`); // TODO: Do interesting work based on the new message await Promise.resolve(1); //Placeholder for actual async work } catch (err) { console.error("An error occurred"); throw err; } }
PHP
SDK para PHP
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando PHP.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 <?php # using bref/bref and bref/logger for simplicity use Bref\Context\Context; use Bref\Event\InvalidLambdaEvent; use Bref\Event\Sqs\SqsEvent; use Bref\Event\Sqs\SqsHandler; use Bref\Logger\StderrLogger; require __DIR__ . '/vendor/autoload.php'; class Handler extends SqsHandler { private StderrLogger $logger; public function __construct(StderrLogger $logger) { $this->logger = $logger; } /** * @throws InvalidLambdaEvent */ public function handleSqs(SqsEvent $event, Context $context): void { foreach ($event->getRecords() as $record) { $body = $record->getBody(); // TODO: Do interesting work based on the new message } } } $logger = new StderrLogger(); return new Handler($logger);
Python
SDK para Python (Boto3).
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando Python.

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 def lambda_handler(event, context): for message in event['Records']: process_message(message) print("done") def process_message(message): try: print(f"Processed message {message['body']}") # TODO: Do interesting work based on the new message except Exception as err: print("An error occurred") raise err
Ruby
SDK para Ruby
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consumir um evento do SQS com o Lambda usando Ruby.

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 def lambda_handler(event:, context:) event['Records'].each do |message| process_message(message) end puts "done" end def process_message(message) begin puts "Processed message #{message['body']}" # TODO: Do interesting work based on the new message rescue StandardError => err puts "An error occurred" raise err end end
Rust
SDK para Rust
nota

Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos Exemplos sem servidor.

Consuma um evento do SQS com o Lambda usando Rust.

// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. // SPDX-License-Identifier: Apache-2.0 use aws_lambda_events::event::sqs::SqsEvent; use lambda_runtime::{run, service_fn, Error, LambdaEvent}; async fn function_handler(event: LambdaEvent<SqsEvent>) -> Result<(), Error> { event.payload.records.iter().for_each(|record| { // process the record tracing::info!("Message body: {}", record.body.as_deref().unwrap_or_default()) }); Ok(()) } #[tokio::main] async fn main() -> Result<(), Error> { tracing_subscriber::fmt() .with_max_level(tracing::Level::INFO) // disable printing the name of the module in every log line. .with_target(false) // disabling time is handy because CloudWatch will add the ingestion time. .without_time() .init(); run(service_fn(function_handler)).await }
Criar uma função do Lambda em Node.js
  1. Crie um diretório para o projeto e depois mude para esse diretório.

    mkdir sqs-tutorial cd sqs-tutorial
  2. Copie o código JavaScript de amostra em um novo arquivo denominado index.js.

  3. Crie um pacote de implantação usando o comando zip a seguir.

    zip function.zip index.js
  4. Crie uma função do Lambda usando o comando create-function da AWS CLI. Para o parâmetro role, insira o ARN da função de execução criada anteriormente.

    nota

    A função do Lambda e a fila do Amazon SQS devem estar na mesma Região da AWS.

    aws lambda create-function --function-name ProcessSQSRecord \ --zip-file fileb://function.zip --handler index.handler --runtime nodejs18.x \ --role arn:aws:iam::111122223333:role/lambda-sqs-role

Testar a função

Etapa 3: testar a função do Lambda

Invoque sua função do Lambda manualmente usando o comando da invoke AWS CLI e um evento do Amazon SQS de amostra.

Invocar a função do Lambda com um evento de amostra
  1. Salve o JSON a seguir como um arquivo denominado input.json. Esse JSON simula um evento que o Amazon SQS pode enviar para a função do Lambda, no qual "body" contém a mensagem real da fila. Neste exemplo, a mensagem é "test".

    exemplo Evento do Amazon SQS

    Este é um evento de teste, portanto, você não precisa alterar a mensagem ou o número da conta.

    { "Records": [ { "messageId": "059f36b4-87a3-44ab-83d2-661975830a7d", "receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...", "body": "test", "attributes": { "ApproximateReceiveCount": "1", "SentTimestamp": "1545082649183", "SenderId": "AIDAIENQZJOLO23YVJ4VO", "ApproximateFirstReceiveTimestamp": "1545082649185" }, "messageAttributes": {}, "md5OfBody": "098f6bcd4621d373cade4e832627b4f6", "eventSource": "aws:sqs", "eventSourceARN": "arn:aws:sqs:us-east-1:111122223333:my-queue", "awsRegion": "us-east-1" } ] }
  2. Execute o comando invoke da AWS CLI apresentado a seguir. Esse comando retorna os logs do CloudWatch na resposta. Para obter mais informações sobre recuperação de logs, consulte Acesso aos logs com a AWS CLI.

    aws lambda invoke --function-name ProcessSQSRecord --payload file://input.json 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 no Guia do usuário da AWS Command Line Interface versão 2.

  3. Encontre o log INFO na resposta. É aqui que a função do Lambda registra em log o corpo da mensagem. Você deve ver logs semelhantes a este:

    2023-09-11T22:45:04.271Z 348529ce-2211-4222-9099-59d07d837b60 INFO Processed message test 2023-09-11T22:45:04.288Z 348529ce-2211-4222-9099-59d07d837b60 INFO done

Criar uma fila do Amazon SQS

Etapa 4: criar uma fila do Amazon SQS

Crie uma fila do Amazon SQS que a função do Lambda possa usar como uma fonte de eventos. A função do Lambda e a fila do Amazon SQS devem estar na mesma Região da AWS.

Para criar uma fila
  1. Abra o console do Amazon SQS.

  2. Selecione Criar fila.

  3. Insira um nome para a fila. Deixe todas as outras opções nas configurações padrão.

  4. Selecione Criar fila.

Depois de criar a fila, anote seu ARN. Você precisará dele na próxima etapa, quando for associar a fila à função do Lambda.

Configurar a origem de evento

Etapa 5: configurar o mapeamento da origem do evento

Conecte a fila do Amazon SQS à função do Lambda ao criar um mapeamento da origem do evento. O mapeamento da origem do evento realiza a leitura da fila do Amazon SQS e invoca a função do Lambda quando uma nova mensagem é adicionada.

Para criar um mapeamento entre a fila do Amazon SQS e a função do Lambda, use o comando create-event-source-mapping da AWS CLI. Exemplo:

aws lambda create-event-source-mapping --function-name ProcessSQSRecord --batch-size 10 \ --event-source-arn arn:aws:sqs:us-east-1:111122223333:my-queue

Para obter uma lista dos mapeamentos da origem dos eventos, use o comando list-event-source-mappings. Exemplo:

aws lambda list-event-source-mappings --function-name ProcessSQSRecord

Envie uma mensagem de teste

Etapa 6: enviar uma mensagem de teste
Enviar uma mensagem do Amazon SQS para a função do Lambda
  1. Abra o console do Amazon SQS.

  2. Escolha a fila que você criou anteriormente.

  3. Escolha Send and receive messages (Enviar e receber mensagens).

  4. Em Corpo da mensagem, insira uma mensagem de teste, como “esta é uma mensagem de teste”.

  5. Escolha Send Message (Enviar mensagem).

O Lambda pesquisa a fila para atualizações. Quando há uma nova mensagem, o Lambda invoca a sua função com esses novos dados de evento da fila. Caso o manipulador de função retorne sem exceções, o Lambda considera a mensagem processada com êxito e começa a realizar a leitura de novas mensagens na fila. Após o processamento com sucesso, uma mensagem,o Lambda a exclui automaticamente da fila. Se o manipulador gera uma exceção, o Lambda considera que o batch de mensagens não foi processado com êxito e o Lambda invoca novamente a função com o mesmo batch de mensagens.

Verificar os logs do CloudWatch

Etapa 6: enviar uma mensagem de teste
Confirmar que a função processou a mensagem
  1. Abra a página Funções do console do Lambda.

  2. Escolha a função ProcessSQSRecord.

  3. Escolha Monitor.

  4. Escolha Visualizar logs do CloudWatch.

  5. No console do CloudWatch, escolha o Fluxo de logs para a função.

  6. Encontre o log INFO. É aqui que a função do Lambda registra em log o corpo da mensagem. Você deve visualizar a mensagem que enviou da fila do Amazon SQS. Exemplo:

    2023-09-11T22:49:12.730Z b0c41e9c-0556-5a8b-af83-43e59efeec71 INFO Processed message this is a test message.

Limpe os recursos

Agora você pode excluir os recursos criados para este tutorial, a menos que queira mantê-los. Excluindo os recursos da AWS que você não está mais usando, você evita cobranças desnecessárias em sua Conta da AWS.

Para excluir a função de execução
  1. Abra a página Roles (Funções) no console do IAM.

  2. Selecione a função de execução que você criou.

  3. Escolha Excluir.

  4. Insira o nome do perfil no campo de entrada de texto e escolha Delete (Excluir).

Como excluir a função do Lambda
  1. Abra a página Functions (Funções) no console do Lambda.

  2. Selecione a função que você criou.

  3. Escolha Ações, Excluir.

  4. Digite delete no campo de entrada de texto e escolha Delete (Excluir).

Para excluir a fila do Amazon SQS
  1. Faça login no AWS Management Console e abra o console do Amazon SQS em https://console.aws.amazon.com/sqs/.

  2. Selecione a fila que você criou.

  3. Escolha Excluir.

  4. Digite confirm no campo de entrada de texto.

  5. Escolha Excluir.