# Usar o Lambda com o Amazon SQS
**nota**
Se você deseja enviar dados para um destino que não seja uma função do Lambda ou enriquecer os dados antes de enviá-los, consulte [Amazon EventBridge Pipes](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-pipes.html) (Pipes do Amazon EventBridge).
É possível usar uma função do Lambda para processar mensagens em uma fila do Amazon Simple Queue Service (Amazon SQS). O Lambda oferece suporte a [filas padrão](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/standard-queues.html) e [filas FIFO (primeiro a entrar, primeiro a sair)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html) para [mapeamentos de origem de eventos](invocation-eventsourcemapping.md). Também é possível usar o modo provisionado para alocar recursos de sondagem dedicados para seus mapeamentos da origem do evento do Amazon SQS. A função do Lambda e a fila do Amazon SQS devem estar na mesma Região da AWS, embora possam estar em [diferentes Contas da AWS](with-sqs-cross-account-example.md).
Ao processar mensagens do Amazon SQS, é necessário implementar uma lógica de resposta parcial em lote para evitar que as mensagens processadas com êxito sejam repetidas quando algumas mensagens em um lote falham. O [utilitário Processador em lote](https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/) do Powertools para AWS Lambda simplifica essa implementação ao lidar automaticamente com a lógica de resposta parcial em lote, reduzindo o tempo de desenvolvimento e melhorando a confiabilidade.
**Topics**
+ [Entender o comportamento de sondagens e lotes para mapeamentos de origem de eventos do Amazon SQS](#sqs-polling-behavior)
+ [Uso do modo provisionado com mapeamentos da origem do evento do Amazon SQS](#sqs-provisioned-mode)
+ [Configuração do modo provisionado para mapeamentos da origem do evento do Amazon SQS](#sqs-configuring-provisioned-mode)
+ [Exemplo de evento de mensagem de fila padrão](#example-standard-queue-message-event)
+ [Exemplo de evento de mensagem de fila FIFO](#sample-fifo-queues-message-event)
+ [Criar e configurar um mapeamento de origem de evento do Amazon SQS](services-sqs-configure.md)
+ [Configurar o comportamento de escalabilidade para mapeamentos de origem de eventos do SQS](services-sqs-scaling.md)
+ [Tratamento de erros para uma origem de eventos do SQS no Lambda](services-sqs-errorhandling.md)
+ [Parâmetros do Lambda para mapeamentos de origem de eventos do Amazon SQS](services-sqs-parameters.md)
+ [Usar a filtragem de eventos com uma origem de eventos do Amazon SQS](with-sqs-filtering.md)
+ [Tutorial: usar o Lambda com o Amazon SQS](with-sqs-example.md)
+ [Tutorial: Uso de uma fila do Amazon SQS entre contas como a origem de um evento](with-sqs-cross-account-example.md)
## Entender o comportamento de sondagens e lotes para mapeamentos de origem de eventos do Amazon SQS
[Com os mapeamentos de origem de eventos do Amazon SQS, o Lambda sonda a fila e invoca sua função de forma síncrona](invocation-sync.md) com um evento. Cada evento pode conter um lote de várias mensagens da fila. O Lambda recebe esses eventos um lote por vez e invoca sua função uma vez para cada lote. Quando sua função processa um lote com êxito, o Lambda exclui suas mensagens da fila.
Quando o Lambda recebe um lote, as mensagens permanecem na fila, mas permanecem ocultas durante o [tempo limite de visibilidade](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html) da fila. Se a função processar com êxito todas as mensagens no lote, o Lambda excluirá as mensagens da fila. Por padrão, se a sua função encontrar um erro durante o processamento de um lote, todas as mensagens naquele lote se tornarão visíveis na fila novamente após o tempo limite de visibilidade expirar. Por conta disso, o código da função deve ter a capacidade de processar a mesma mensagem várias vezes sem causar efeitos colaterais não intencionais.
**Atenção**
Os mapeamentos da origem do evento do Lambda processam cada evento ao menos uma vez, podendo haver o processamento duplicado de registros. Para evitar possíveis problemas relacionados a eventos duplicados, é altamente recomendável tornar o código da função idempotente. Para saber mais, consulte [Como tornar minha função do Lambda idempotente](https://repost.aws/knowledge-center/lambda-function-idempotent) no Centro de Conhecimentos da AWS.
Para evitar que o Lambda processe uma mensagem diversas vezes, é possível configurar o mapeamento de origem de eventos para incluir [falhas de itens de lote](services-sqs-errorhandling.md#services-sqs-batchfailurereporting) na resposta da função ou usar a API [DeleteMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_DeleteMessage.html) para remover mensagens da fila à medida que a função do Lambda as processa com êxito.
Para obter informações sobre os parâmetros de configuração aceitos pelo Lambda para mapeamentos de origem de eventos do SQS, consulte [Criar um mapeamento de origem de evento do SQS](services-sqs-configure.md#events-sqs-eventsource).
## Uso do modo provisionado com mapeamentos da origem do evento do Amazon SQS
Para workloads em que você precisa ajustar o throughput do mapeamento da origem de eventos, você pode usar o modo provisionado. No modo provisionado, você define limites mínimos e máximos para a quantidade de agentes de sondagem de eventos provisionados. Esses agentes de sondagem de eventos provisionados são dedicados ao mapeamento da origem do evento e podem lidar com picos inesperados de mensagens por meio do ajuste de escala automático responsivo. O mapeamento da origem do evento do Amazon SQS configurado com o modo provisionado é escalado 3 vezes mais rápido (até 1.000 invocações simultâneas por minuto) e suporta uma simultaneidade 16x maior (até 20.000 invocações simultâneas) do que o recurso padrão de mapeamento da origem do evento do Amazon SQS. Recomendamos que você use o modo provisionado para workloads orientadas a eventos do Amazon SQS que tenham requisitos rígidos de performance, como empresas de serviços financeiros que processem feeds de dados de mercado, plataformas de comércio eletrônico que forneçam recomendações personalizadas em tempo real e empresas de jogos que gerenciem interações com jogadores ao vivo. O uso do modo provisionado incorre em custos adicionais. Para obter detalhes sobre preços, consulte [Definição de preços do AWS Lambda](https://aws.amazon.com/lambda/pricing/).
Cada agente de sondagem de eventos no modo provisionado pode tratar até 1 MB/s de throughput, até 10 invocações simultâneas ou até 10 chamadas da API de sondagem do Amazon SQS por segundo. O intervalo de valores aceitos para o número mínimo de agentes de sondagem de eventos (MinimumPollers) é entre 2 e 200, com um padrão de 2. O intervalo de valores aceitos para o número máximo de agentes de sondagem de eventos (MaximumPollers) é entre 2 e 2.000, com um padrão de 200. MaximumPollers deve ser maior ou igual a MinimumPollers.
### Determinação dos agentes de sondagem de eventos necessários
Para estimar o número de agentes de sondagem de eventos necessários para garantir a performance ideal do processamento de mensagens ao usar o modo provisionado para o ESM do SQS, reúna as métricas a seguir para sua aplicação: pico de eventos de SQS por segundo que exijam processamento de baixa latência, tamanho médio da carga útil do evento de SQS, duração média da função do Lambda e tamanho do lote configurado.
Primeiro, é possível estimar o número de eventos de SQS por segundo (EPS) com suporte em um agente de sondagem de eventos para sua workload usando a fórmula a seguir:
```
EPS per event poller =
minimum(
ceiling(1024 / average event size in KB),
ceiling(10 / average function duration in seconds) * batch size,
min(100, 10 * batch size)
)
```
Em seguida, é possível calcular o número mínimo de sondagens necessárias usando a fórmula abaixo. Esse cálculo garante que você provisione capacidade suficiente para tratar seus requisitos de pico de tráfego.
```
Required event pollers = (Peak number of events per second in Queue) / EPS per event poller
```
Considere uma workload com um tamanho de lote padrão de 10, tamanho médio de evento de 3 KB, duração média da função de 100 ms e um requisito para tratar 1.000 eventos por segundo. Nesse cenário, cada agente de sondagem de eventos oferecerá suporte a aproximadamente 100 eventos por segundo (EPS). Portanto, é necessário definir o mínimo de sondagens como 10 para lidar adequadamente com seus requisitos de pico de tráfego. Se sua workload tiver as mesmas características, mas com duração média de função de 1 segundo, cada agente de sondagem oferecerá suporte apenas a 10 EPS, exigindo que você configure 100 agentes de sondagem no mínimo para tratar 1.000 eventos por segundo em baixa latência.
Recomendamos usar um tamanho de lote padrão de 10 ou mais para maximizar a eficiência dos agentes de sondagem de eventos no modo provisionado. Tamanhos de lote maiores permitem que cada agente de sondagem processe mais eventos por invocação, para melhorar a produtividade e a eficiência de custos. Ao planejar sua capacidade de agentes de sondagem de eventos, considere possíveis picos de tráfego e considere definir o valor de minimumPollers um pouco acima do mínimo calculado para fornecer um buffer. Além disso, monitore as características da workload ao longo do tempo, pois mudanças no tamanho da mensagem, na duração da função ou nos padrões de tráfego podem exigir ajustes na configuração de agentes de sondage de eventos para manter a performance e a eficiência de custos ideais. Para obter um planejamento preciso da capacidade, recomendamos testar sua workload específica para determinar o EPS real que cada agente de sondagem de eventos pode gerar.
## Configuração do modo provisionado para mapeamentos da origem do evento do Amazon SQS
É possível configurar o modo provisionado para o mapeamento da origem do evento do Amazon SQS usando o console ou a API do Lambda.
**Para configurar o modo provisionado para um mapeamento da origem do evento do Amazon MSK existente (console)**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Escolha a função com o mapeamento da origem do evento do Amazon SQS para o qual você deseja configurar o modo provisionado.
1. Escolha **Configuração** e, em seguida, escolha **Acionadores**.
1. Escolha o mapeamento da origem do evento do Amazon SQS para o qual você deseja configurar o modo provisionado e, em seguida, escolha **Editar**.
1. Em **Configuração de mapeamento da origem do evento**, escolha **Configurar modo provisionado**.
+ Para **Agentes de sondagem de eventos mínimos**, insira um valor entre 2 e 200. Se você não especificar um valor, o Lambda vai atribuir o valor padrão de 2.
+ Para **Agentes de sondagem de eventos máximos**, insira um valor entre 2 e 2.000. Esse valor deve ser maior ou igual ao seu valor para **Agentes de sondagem de eventos mínimos**. Se você não especificar um valor, o Lambda vai atribuir o valor padrão de 200.
1. Escolha **Salvar**.
É possível configurar o modo provisionado programaticamente usando o objeto `ProvisionedPollerConfig` na sua `EventSourceMappingConfiguration`. Por exemplo, o comando `UpdateEventSourceMapping` a seguir da CLI configura um valor de `MinimumPollers` como 5 e um valor de `MaximumPollers` como 100.
```
aws lambda update-event-source-mapping \
--uuid a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--provisioned-poller-config '{"MinimumPollers": 5, "MaximumPollers": 100}'
```
Depois de configurar o modo provisionado, você pode observar o uso de agentes de sondagem de eventos para sua workload monitorando a métrica `ProvisionedPollers`. Para obter mais informações, consulte as métricas do mapeamento da origem do evento.
Para desabilitar o modo provisionado e retornar ao modo padrão (sob demanda), é possível usar o comando `UpdateEventSourceMapping` a seguir da CLI:
```
aws lambda update-event-source-mapping \
--uuid a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 \
--provisioned-poller-config '{}'
```
**nota**
O modo provisionado não pode ser usado com a configuração de simultaneidade máxima. Ao usar o modo provisionado, você controla a simultaneidade máxima por meio do número máximo de agentes de sondagem de eventos.
Para obter mais informações sobre como configurar o modo provisionado, consulte [Criar e configurar um mapeamento de origem de evento do Amazon SQS](services-sqs-configure.md).
## Exemplo de evento de mensagem de fila padrão
**Example Evento de mensagem do Amazon SQS (fila padrão)**
```
{
"Records": [
{
"messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
"receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
"body": "Test message.",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1545082649183",
"SenderId": "AIDAIENQZJOLO23YVJ4VO",
"ApproximateFirstReceiveTimestamp": "1545082649185"
},
"messageAttributes": {
"myAttribute": {
"stringValue": "myValue",
"stringListValues": [],
"binaryListValues": [],
"dataType": "String"
}
},
"md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
"awsRegion": "us-east-2"
},
{
"messageId": "2e1424d4-f796-459a-8184-9c92662be6da",
"receiptHandle": "AQEBzWwaftRI0KuVm4tP+/7q1rGgNqicHq...",
"body": "Test message.",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1545082650636",
"SenderId": "AIDAIENQZJOLO23YVJ4VO",
"ApproximateFirstReceiveTimestamp": "1545082650649"
},
"messageAttributes": {},
"md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:my-queue",
"awsRegion": "us-east-2"
}
]
}
```
Por padrão, o Lambda pesquisará até 10 mensagens em sua fila de uma só vez e envia esse lote para sua função. Para evitar a invocação da função com poucos registros, você pode configurar a origem de eventos para armazenar os registros em buffer por até cinco minutos, configurando uma janela de lote. Antes de invocar a função, o Lambda continuará a sondar as mensagens da fila padrão até a janela de lote expirar, a [cota de tamanho da carga útil de invocação](gettingstarted-limits.md) ser atingida ou o tamanho de lote máximo configurado ser atingido.
Se você estiver usando uma janela em lote e sua fila do SQS contiver um volume de tráfego muito baixo, o Lambda poderá esperar até 20 segundos antes de invocar sua função. Isso será válido mesmo se você definir uma janela de lote inferior a 20 segundos.
**nota**
Em Java, talvez você observe erros de ponteiro nulo ao desserializar o JSON. Isso pode ser causado por como a caixa de “Records” e “EventSourceArn” é convertida pelo mapeador de objetos JSON.
## Exemplo de evento de mensagem de fila FIFO
Para as filas FIFO, os registros contêm atributos adicionais relacionados a desduplicação e sequenciamento.
**Example Evento de mensagem do Amazon SQS (fila FIFO)**
```
{
"Records": [
{
"messageId": "11d6ee51-4cc7-4302-9e22-7cd8afdaadf5",
"receiptHandle": "AQEBBX8nesZEXmkhsmZeyIE8iQAMig7qw...",
"body": "Test message.",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1573251510774",
"SequenceNumber": "18849496460467696128",
"MessageGroupId": "1",
"SenderId": "AIDAIO23YVJENQZJOL4VO",
"MessageDeduplicationId": "1",
"ApproximateFirstReceiveTimestamp": "1573251510774"
},
"messageAttributes": {},
"md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-east-2:123456789012:fifo.fifo",
"awsRegion": "us-east-2"
}
]
}
```
# Criar e configurar um mapeamento de origem de evento do Amazon SQS
Para processar mensagens do Amazon SQS com o Lambda, configure sua fila com as configurações apropriadas e, em seguida, crie um mapeamento de origem de evento do Lambda.
**Topics**
+ [Configurar uma fila para usar com o Lambda](#events-sqs-queueconfig)
+ [Configurar permissões do perfil de execução do Lambda](#events-sqs-permissions)
+ [Criar um mapeamento de origem de evento do SQS](#events-sqs-eventsource)
## Configurar uma fila para usar com o Lambda
Se você ainda não tiver uma fila do Amazon SQS, [crie uma](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-create-queue.html) para servir como uma origem de eventos para a sua função do Lambda. A função do Lambda e a fila do Amazon SQS devem estar na mesma Região da AWS, embora possam estar em [diferentes Contas da AWS](with-sqs-cross-account-example.md).
Para permitir que a função tenha tempo para processar cada lote de registros, defina o [tempo limite de visibilidade](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html) da fila de origem para, no mínimo, seis vezes o [tempo limite da configuração](configuration-timeout.md) na sua função. Esse tempo extra permite que o Lambda repita o processo se a execução da sua função for limitada durante o processamento de um lote anterior.
**nota**
O tempo limite da sua função deve ser menor ou igual ao tempo limite de visibilidade da fila. O Lambda valida esse requisito quando você cria ou atualiza um mapeamento da origem do evento e retornará um erro se o tempo limite da função exceder o tempo limite de visibilidade da fila.
Por padrão, se o Lambda se deparar com um erro em algum momento durante o processamento de um lote, todas as mensagens naquele lote retornarão para a fila. Após o [tempo limite de visibilidade](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html), as mensagens se tornam visíveis para o Lambda novamente. É possível configurar o mapeamento de origem de evento para usar [respostas parciais em lote](services-sqs-errorhandling.md#services-sqs-batchfailurereporting) para recolocar na fila somente as mensagens com falha. Além disso, se a sua função não conseguir processar uma mensagem várias vezes, o Amazon SQS poderá enviá-la para uma [fila de mensagens não entregues](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html). Recomendamos definir a `maxReceiveCount` na [política de redirecionamento](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html#policies-for-dead-letter-queues) da fila de origem para pelo menos 5. Isso dá ao Lambda algumas chances de tentar novamente antes de enviar mensagens com falha diretamente para a fila de mensagens não entregues.
## Configurar permissões do perfil de execução do Lambda
A política gerenciada pela AWS [AWSLambdaSQSQueueExecutionRole](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLambdaSQSQueueExecutionRole.html) inclui as permissões necessárias para o Lambda ler da sua fila do Amazon SQS. É possível [adicionar essa política gerenciada](lambda-intro-execution-role.md) ao perfil de execução da função.
Opcionalmente, se você estiver usando uma fila criptografada, também precisará adicionar a seguinte permissão à sua função de execução:
+ [kms:Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)
## Criar um mapeamento de origem de evento do SQS
Crie um mapeamento de fontes de eventos para orientar o Lambda a enviar itens da sua fila para uma função do Lambda. É possível criar vários mapeamentos da fonte do evento para processar itens de várias filas com uma única função. Quando o Lambda invoca a função de destino, o evento pode conter vários itens, até um *tamanho de lote* máximo configurável.
Para configurar sua função para ler do Amazon SQS, associe a política gerenciada pela AWS [AWSLambdaSQSQueueExecutionRole](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLambdaSQSQueueExecutionRole.html) ao seu perfil de execução. Em seguida, crie um mapeamento de origem de evento do **SQS** via console usando as etapas a seguir.
**Para adicionar permissões e criar um acionador**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Escolha o nome de uma função.
1. Escolha a guia **Configuration** (Configuração) e, depois, **Permissions** (Permissões).
1. Em **Nome do perfil**, escolha o link para seu perfil de execução. Esse link abre o perfil no console do IAM.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/execution-role.png)
1. Escolha **Adicionar permissões** e depois **Anexar políticas**.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/attach-policies.png)
1. No campo de pesquisa, digite `AWSLambdaSQSQueueExecutionRole`. Adicione esta política ao seu perfil de execução Essa é uma política gerenciada pela AWS que contém as permissões que sua função precisa para ler de uma fila do Amazon SQS. Para obter mais informações sobre essa política, consulte [AWSLambdaSQSQueueExecutionRole](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLambdaSQSQueueExecutionRole.html) na *Referência de políticas gerenciadas pela AWS*.
1. Volte para a sua função no console do Lambda Em **Visão geral da função**, escolha **Adicionar gatilho**.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/add-trigger.png)
1. Escolha um tipo de acionador.
1. Configure as opções necessárias e escolha **Add** (Adicionar).
O Lambda oferece suporte às seguintes opções de configuração para origens de eventos do Amazon SQS:
**Fila do SQS**
A fila do Amazon SQS de onde os registros serão lidos. A função do Lambda e a fila do Amazon SQS devem estar na mesma Região da AWS, embora possam estar em [diferentes Contas da AWS](with-sqs-cross-account-example.md).
**Habilitar acionador**
O status do mapeamento da origem do evento. **Enable trigger** (Habilitar acionador) está selecionado por padrão.
**Tamanho do lote**
O número máximo de registros a serem enviados para a função em cada lote. Em uma fila padrão, isso pode ser até 10.000 registros. Em uma fila FIFO, o máximo é 10. Para um tamanho de lote acima de dez, você também deve definir a janela do lote (`MaximumBatchingWindowInSeconds`) para, no mínimo, um segundo.
Configure o [tempo limite da função](https://serverlessland.com/content/service/lambda/guides/aws-lambda-operator-guide/configurations#timeouts) para permitir tempo suficiente para o processamento de um lote inteiro de itens. Se os itens levarem muito tempo para serem processados, escolha um tamanho de lote menor. Um tamanho de lote grande pode melhorar a eficiência das workloads muito rápidas ou com muita sobrecarga. Se você configurar a [simultaneidade reservada](configuration-concurrency.md) na sua função, defina pelo menos cinco execuções simultâneas para reduzir as chances de erros de controle de utilização quando o Lambda invocar a sua função.
O Lambda transmite todos os registros do lote para a função em uma única chamada, desde que o tamanho total dos eventos não exceda a [cota de tamanho da carga útil de invocação](gettingstarted-limits.md) para invocação síncrona (6 MB). O Lambda e o Amazon SQS geram metadados para cada registro. Esses metadados adicionais contam para o tamanho total da carga útil e podem fazer com que o total de registros enviados em um lote seja menor que o tamanho do lote configurado. Os campos de metadados enviados pelo Amazon SQS podem variar em termos de comprimento. Para saber mais sobre os campos de metadados do Amazon SQS, consulte a documentação da operação de API [ReceiveMessage](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_ReceiveMessage.html) na *Referência de APIs do Amazon Simple Queue Service*.
**Janela do lote**
O máximo de tempo para reunir registros antes de invocar a função, em segundos. Aplicável somente a filas padrão.
Se você estiver usando uma janela de lote maior que zero segundos, deverá considerar o aumento do tempo de processamento no [tempo limite de visibilidade](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html) da fila. Recomendamos definir o tempo limite de visibilidade da fila para seis vezes o [tempo limite da função](configuration-timeout.md), acrescido do valor de `MaximumBatchingWindowInSeconds`. Isso permite que sua função do Lambda tenha tempo para processar cada lote de eventos e tentar novamente em caso de erro de controle de utilização.
Quando as mensagens ficam disponíveis, o Lambda começa a processar as mensagens em lotes. O Lambda começa a processar cinco lotes por vez com cinco invocações simultâneas de sua função. Se ainda houver mensagens disponíveis, o Lambda adicionará até 300 invocações simultâneas da sua função por minuto, até alcançar um máximo de 1.250 invocações simultâneas. Ao usar o modo provisionado, cada agente de sondagem de eventos pode tratar até 1 MB/s de throughput, até 10 invocações simultâneas ou até 10 chamadas da API de sondagem do Amazon SQS por segundo. O Lambda escala o número de agentes de sondagem de eventos entre o mínimo e o máximo configurados, adicionando rapidamente até 1.000 invocações simultâneas por minuto para fornecer processamento de baixa latência de seus eventos do Amazon SQS. Você controla a escalabilidade e a simultaneidade por meio dessas configurações mínimas e máximas do agente de sondagem de eventos. Para saber mais sobre a escalabilidade e simultaneidade de funções, consulte [Como entender a escalabilidade da função do Lambda](lambda-concurrency.md).
Para processar mais mensagens, você pode otimizar sua função do Lambda para aumentar o throughput. Para obter mais informações, consulte [Entender como o AWS Lambda escala com as filas padrão do Amazon SQS](https://aws.amazon.com/blogs/compute/understanding-how-aws-lambda-scales-when-subscribed-to-amazon-sqs-queues/#:~:text=If there are more messages,messages from the SQS queue.).
**Critérios de filtro**
Adicione critérios de filtro para controlar quais eventos o Lambda enviará à função para processamento. Para obter mais informações, consulte [Controlar quais eventos o Lambda envia para a função](invocation-eventfiltering.md).
**Simultaneidade máxima**
O número máximo de funções simultâneas que a origem do evento pode invocar. Não pode ser usado com o modo provisionado habilitado. Para obter mais informações, consulte [Configuração de simultaneidade máxima para origens de eventos do Amazon SQS](services-sqs-scaling.md#events-sqs-max-concurrency).
**Modo provisionado**
Quando habilitado, aloca recursos de sondagem dedicados para o mapeamento da origem do evento. É possível configurar o número mínimo (2-200) e máximo (2-2000) de agentes de sondagem de eventos. Cada agente de sondagem de eventos pode tratar até 1 MB/s de throughput, até 10 invocações simultâneas ou até 10 chamadas da API de sondagem do Amazon SQS por segundo.
Observação: não é possível usar o modo provisionado e a simultaneidade máxima juntos. Quando o modo provisionado estiver habilitado, use a configuração máxima de agentes de sondagem para controlar a simultaneidade.
# Configurar o comportamento de escalabilidade para mapeamentos de origem de eventos do SQS
É possível controlar o comportamento de escalabilidade de seus mapeamentos da origem do evento do Amazon SQS por meio de configurações máximas de simultaneidade ou habilitando o modo provisionado. Estas são as opções mutuamente exclusivas.
Por padrão, o Lambda escala automaticamente os agentes de sondagem de eventos com base no volume de mensagens. Ao habilitar o modo provisionado, você aloca um número mínimo e máximo de recursos de sondagem dedicados que permanecem prontos para lidar com os padrões de tráfego esperados. Isso permite que você otimize a performance do mapeamento da origem do evento de duas maneiras:
+ Modo padrão (padrão): o Lambda gerencia automaticamente a escalabilidade, começando com um pequeno número de agentes de sondagem e aumentando ou diminuindo a escala com base na workload.
+ Modo provisionado: você configura recursos de sondagem dedicados com limites mínimos e máximos, permitindo um escalonamento 3 vezes mais rápido e uma capacidade de processamento até 16 vezes maior.
Para filas padrão, o Lambda usa [sondagem longa](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html#sqs-long-polling) para sondar uma fila até que ela se torne ativa. Quando as mensagens estão disponíveis, o Lambda começa a processar cinco lotes por vez com cinco invocações simultâneas da sua função. Se ainda houver mensagens disponíveis, o Lambda aumentará o número de processos de leitura de lotes em até 300 invocações simultâneas a mais por minuto. O número máximo de invocações que podem ser processadas simultaneamente por um mapeamento da origem do evento é 1.250. Quando não há muito tráfego, o Lambda reduz o processamento para cinco invocações simultâneas e pode otimizar para apenas duas invocações simultâneas para reduzir as chamadas do Amazon SQS e os custos correspondentes. Porém, essa otimização não está disponível quando você ativa a configuração máxima de simultaneidade.
Para filas FIFO, o Lambda envia mensagens para a função na ordem em que as recebe. Ao enviar uma mensagem para uma fila do FIFO, você especifica um[ID do grupo de mensagens](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/using-messagegroupid-property.html). O Amazon SQS garante que as mensagens no mesmo grupo sejam entregues ao Lambda em ordem. Quando o Lambda lê suas mensagens em lotes, cada lote poderá conter mensagens de mais de um grupo de mensagens, mas a ordem das mensagens será mantida. Se a função retornar um erro, ela fará todas as tentativas possíveis nas mensagens afetadas antes que o Lambda receba mensagens adicionais do mesmo grupo.
Ao usar o modo provisionado, cada agente de sondagem de eventos pode tratar até 1 MB/s de throughput, até 10 invocações simultâneas ou até 10 chamadas de API de sondagem do Amazon SQS por segundo. O Lambda escala o número de agentes de sondagem de eventos entre o mínimo e o máximo configurados, adicionando rapidamente até 1.000 simultaneidades por minuto para fornecer processamento consistente de baixa latência de seus eventos do Amazon SQS. O uso do modo provisionado incorre em custos adicionais. Para obter detalhes sobre preços, consulte [Definição de preços do AWS Lambda](https://aws.amazon.com/lambda/pricing/). Cada agente de sondagem de eventos usa uma [sondagem longa](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-short-and-long-polling.html) em sua fila do SQS com até 10 sondagens por segundo, o que incorre no custo das solicitações da API do SQS. Para obter mais detalhes, consulte [Definição de preços do Amazon SQS](https://aws.amazon.com/sqs/pricing/ ). Você controla a escalabilidade e a simultaneidade por meio dessas configurações mínimas e máximas do agente de sondagem de eventos, em vez de usar a configuração máxima de simultaneidade, pois essas opções não podem ser usadas juntas.
**nota**
Não é possível usar a configuração máxima de simultaneidade e o modo provisionado ao mesmo tempo. Quando o modo provisionado está habilitado, você controla a escalabilidade e a simultaneidade do mapeamento da origem do evento do Amazon SQS por meio do número mínimo e máximo de agentes de sondagem de eventos.
## Configuração de simultaneidade máxima para origens de eventos do Amazon SQS
É possível usar a configuração de simultaneidade máxima para controlar o comportamento de escalabilidade de suas fontes de eventos do SQS. Observe que a simultaneidade máxima não pode ser usada com o modo provisionado habilitado. A configuração de simultaneidade máxima limita o número de instâncias simultâneas da função que uma origem de evento do Amazon SQS pode invocar. A simultaneidade máxima é uma configuração em nível de origem do evento. Se você tiver diversas origens de eventos do Amazon SQS mapeadas para uma função, cada origem de evento poderá ter uma configuração de simultaneidade máxima separada. É possível usar a simultaneidade máxima para evitar que uma fila use toda a [simultaneidade reservada](configuration-concurrency.md) da função ou todo o restante da [cota de simultaneidade da conta](gettingstarted-limits.md). Não há custos para configurar a simultaneidade máxima em uma origem de evento do Amazon SQS.
Importante, a simultaneidade máxima e a simultaneidade reservada são duas configurações independentes. Não defina a simultaneidade máxima maior que a simultaneidade reservada da função. Se você configurar a simultaneidade máxima, certifique-se de que a simultaneidade reservada da função seja maior ou igual à simultaneidade máxima total para todas as origens de eventos do Amazon SQS na função. Caso contrário, o Lambda pode aplicar um controle de utilização para as suas mensagens.
Quando a cota de simultaneidade da sua conta é definida com o valor padrão de 1.000, um mapeamento de origem de eventos do Amazon SQS pode ser escalado para invocar instâncias de função até esse valor, a menos que você especifique uma simultaneidade máxima.
Se você receber um aumento na cota de simultaneidade padrão da sua conta, o Lambda talvez não consiga invocar instâncias de funções simultâneas até sua nova cota. Por padrão, o Lambda pode escalar para invocar até 1.250 instâncias de funções simultâneas para um mapeamento de origem de eventos do Amazon SQS. Se isso não for suficiente para seu caso de uso, entre em contato com o suporte da AWS para discutir um aumento na simultaneidade de mapeamento de origem de eventos do Amazon SQS da sua conta.
**nota**
Para filas FIFO, as invocações simultâneas são limitadas pelo número de [IDs de grupos de mensagens](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/using-messagegroupid-property.html) (`messageGroupId`) ou pela configuração máxima de simultaneidade, o que for menor. Por exemplo, se você tiver seis IDs de grupo de mensagens e a simultaneidade máxima estiver definida como dez, sua função poderá ter no máximo seis invocações simultâneas.
É possível configurar a simultaneidade máxima em mapeamentos da origem do evento novos e existentes do Amazon SQS.
**Configuração da simultaneidade máxima usando o console do Lambda**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Escolha o nome de uma função.
1. Em **Function overview** (Visão geral da função), escolha **SQS**. Isso abre a guia **Configuration** (Configuração).
1. Selecione o acionador do Amazon SQS e escolha **Edit** (Editar).
1. Em **Maximum concurrency** (Simultaneidade máxima), insira um número entre dois e mil. Para desativar a simultaneidade máxima, deixe a caixa em branco.
1. Escolha **Salvar**.
**Configuração da simultaneidade máxima usando a AWS Command Line Interface (AWS CLI)**
Use o comando [update-event-source-mapping](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/update-event-source-mapping.html) com a opção `--scaling-config`. Exemplo:
```
aws lambda update-event-source-mapping \
--uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--scaling-config '{"MaximumConcurrency":5}'
```
Para desativar a simultaneidade máxima, insira um valor vazio para `--scaling-config`:
```
aws lambda update-event-source-mapping \
--uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--scaling-config "{}"
```
**Configuração da simultaneidade máxima usando a API do Lambda**
Use a ação [CreateEventSourceMapping](https://docs.aws.amazon.com/lambda/latest/api/API_CreateEventSourceMapping.html) ou [UpdateEventSourceMapping](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateEventSourceMapping.html) com um objeto [ScalingConfig](https://docs.aws.amazon.com/lambda/latest/api/API_ScalingConfig.html).
# Tratamento de erros para uma origem de eventos do SQS no Lambda
Para lidar com erros relacionados a uma fonte de eventos do SQS, o Lambda usa automaticamente uma estratégia de repetição com uma estratégia de recuo. Você também pode personalizar o comportamento de tratamento de erros configurando o mapeamento de origem de eventos do SQS para retornar [respostas parciais em lote](#services-sqs-batchfailurereporting).
## Estratégia de recuo para invocações com falha
Quando uma invocação falha, o Lambda tenta repetir a invocação enquanto implementa uma estratégia de recuo. A estratégia de recuo difere ligeiramente caso o Lambda tenha encontrado a falha devido a um erro no código da função ou devido ao controle de utilização.
+ Se o **código da função** causou o erro, o Lambda interromperá o processamento e repetirá a invocação. Enquanto isso, o Lambda recua gradualmente, reduzindo a quantidade de simultaneidade alocada ao mapeamento da origem do evento do Amazon SQS. Depois que limite de tempo de visibilidade da sua fila se esgotar, a mensagem será mostrada novamente na fila.
+ Se a invocação apresentar falhas devido ao **controle de utilização**, o Lambda recua gradualmente as novas tentativas, reduzindo a quantidade de simultaneidade alocada para o mapeamento da origem do evento do Amazon SQS. O Lambda continuará a repetir a mensagem até que o carimbo de data/hora da mensagem exceda o tempo limite de visibilidade da fila, que corresponde ao momento em que o Lambda descartará a mensagem.
## Implementar respostas parciais em lote
Quando sua função do Lambda encontra um erro ao processar um lote, todas as mensagens nesse lote tornam-se novamente visíveis na fila por padrão, incluindo mensagens que o Lambda processou com sucesso. Como resultado, a função pode acabar processando a mesma mensagem diversas vezes.
Para não precisar reprocessar todas as mensagens processadas com êxito em um lote com falha, você pode configurar o mapeamento da origem do evento para tornar visíveis novamente apenas as mensagens com falha. Isso se chama resposta parcial em lote. Para ativar respostas parciais em lote, especifique `ReportBatchItemFailures` para a ação [FunctionResponseTypes](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateEventSourceMapping.html#lambda-UpdateEventSourceMapping-request-FunctionResponseTypes) ao configurar o mapeamento da origem do evento. Isso permite que a função retorne um sucesso parcial, podendo ajudar a reduzir o número de novas tentativas desnecessárias nos registros.
**nota**
O [utilitário de processador em lote](https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/) do Powertools para AWS Lambda lida com toda a lógica de respostas parciais em lote de maneira automática. Ele simplifica a implementação de padrões de processamento em lote, além de reduzir o código personalizado necessário para lidar corretamente com falhas de itens em lote. Esse utilitário está disponível para Python, Java, Typescript e .NET.
Quando `ReportBatchItemFailures` estiver ativado, o Lambda não [reduzirá a escala verticalmente da sondagem de mensagens](#services-sqs-backoff-strategy) quando as invocações de funções falharem. Se você espera que algumas mensagens falhem, e não quer que essas falhas afetem a taxa de processamento de mensagens, use `ReportBatchItemFailures`.
**nota**
Ao usar respostas parciais em lote, tenha em mente:
Se a sua função lançar uma exceção, o lote inteiro será considerado uma falha total.
Se você estiver usando esse recurso com uma fila FIFO, a função deverá interromper o processamento de mensagens após a primeira falha e retornar todas as mensagens com falha e não processadas no `batchItemFailures`. Isso ajuda a preservar a ordem das mensagens na sua fila.
**Para ativar o relatório parcial em lote**
1. Leia as [práticas recomendadas para implementar respostas parciais em lote](https://docs.aws.amazon.com/prescriptive-guidance/latest/lambda-event-filtering-partial-batch-responses-for-sqs/best-practices-partial-batch-responses.html).
1. Execute o comando a seguir para ativar `ReportBatchItemFailures` para a função. Para recuperar o UUID do mapeamento da origem do evento, execute o comando [list-event-source-mappings](https://docs.aws.amazon.com/cli/latest/reference/lambda/list-event-source-mappings.html) da AWS CLI.
```
aws lambda update-event-source-mapping \
--uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--function-response-types "ReportBatchItemFailures"
```
1. Atualize o código da função para capturar todas as exceções e retornar mensagens com falha em uma resposta `batchItemFailures` do JSON. A resposta `batchItemFailures` deve incluir uma lista de IDs de mensagens, como valores `itemIdentifier` do JSON.
Por exemplo, suponha que você tenha um lote de cinco mensagens, com os IDs de mensagem `id1`, `id2`, `id3`, `id4` e `id5`. Sua função processa `id1`,`id3` e `id5` com sucesso. Para tornar as mensagens `id2` e `id4` novamente visíveis na fila, a função deve retornar a seguinte resposta:
```
{
"batchItemFailures": [
{
"itemIdentifier": "id2"
},
{
"itemIdentifier": "id4"
}
]
}
```
Veja alguns exemplos de código de função que retornam a lista de IDs de mensagens com falha no lote:
------
#### [ .NET ]
**SDK para .NET**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote do SQS com o Lambda usando o .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 sqsSample;
public class Function
{
public async Task FunctionHandler(SQSEvent evnt, ILambdaContext context)
{
List batchItemFailures = new List();
foreach(var message in evnt.Records)
{
try
{
//process your message
await ProcessMessageAsync(message, context);
}
catch (System.Exception)
{
//Add failed message identifier to the batchItemFailures list
batchItemFailures.Add(new SQSBatchResponse.BatchItemFailure{ItemIdentifier=message.MessageId});
}
}
return new SQSBatchResponse(batchItemFailures);
}
private async Task ProcessMessageAsync(SQSEvent.SQSMessage message, ILambdaContext context)
{
if (String.IsNullOrEmpty(message.Body))
{
throw new Exception("No Body in SQS Message.");
}
context.Logger.LogInformation($"Processed message {message.Body}");
// TODO: Do interesting work based on the new message
await Task.CompletedTask;
}
}
```
------
#### [ Go ]
**SDK para Go V2**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote do SQS com o Lambda usando Go.
```
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package main
import (
"context"
"fmt"
"github.com/aws/aws-lambda-go/events"
"github.com/aws/aws-lambda-go/lambda"
)
func handler(ctx context.Context, sqsEvent events.SQSEvent) (map[string]interface{}, error) {
batchItemFailures := []map[string]interface{}{}
for _, message := range sqsEvent.Records {
if len(message.Body) > 0 {
// Your message processing condition here
fmt.Printf("Successfully processed message: %s\n", message.Body)
} else {
// Message processing failed
fmt.Printf("Failed to process message %s\n", message.MessageId)
batchItemFailures = append(batchItemFailures, map[string]interface{}{"itemIdentifier": message.MessageId})
}
}
sqsBatchResponse := map[string]interface{}{
"batchItemFailures": batchItemFailures,
}
return sqsBatchResponse, nil
}
func main() {
lambda.Start(handler)
}
```
------
#### [ Java ]
**SDK para Java 2.x**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote 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.SQSBatchResponse;
import java.util.ArrayList;
import java.util.List;
public class ProcessSQSMessageBatch implements RequestHandler {
@Override
public SQSBatchResponse handleRequest(SQSEvent sqsEvent, Context context) {
List batchItemFailures = new ArrayList();
for (SQSEvent.SQSMessage message : sqsEvent.getRecords()) {
try {
//process your message
} catch (Exception e) {
//Add failed message identifier to the batchItemFailures list
batchItemFailures.add(new SQSBatchResponse.BatchItemFailure(message.getMessageId()));
}
}
return new SQSBatchResponse(batchItemFailures);
}
}
```
------
#### [ JavaScript ]
**SDK para JavaScript (v3)**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote do SQS com o Lambda usando JavaScript.
```
// Node.js 20.x Lambda runtime, AWS SDK for Javascript V3
export const handler = async (event, context) => {
const batchItemFailures = [];
for (const record of event.Records) {
try {
await processMessageAsync(record, context);
} catch (error) {
batchItemFailures.push({ itemIdentifier: record.messageId });
}
}
return { batchItemFailures };
};
async function processMessageAsync(record, context) {
if (record.body && record.body.includes("error")) {
throw new Error("There is an error in the SQS Message.");
}
console.log(`Processed message: ${record.body}`);
}
```
Relatar falhas de item em lote 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, SQSBatchResponse, Context, SQSBatchItemFailure, SQSRecord } from 'aws-lambda';
export const handler = async (event: SQSEvent, context: Context): Promise => {
const batchItemFailures: SQSBatchItemFailure[] = [];
for (const record of event.Records) {
try {
await processMessageAsync(record);
} catch (error) {
batchItemFailures.push({ itemIdentifier: record.messageId });
}
}
return {batchItemFailures: batchItemFailures};
};
async function processMessageAsync(record: SQSRecord): Promise {
if (record.body && record.body.includes("error")) {
throw new Error('There is an error in the SQS Message.');
}
console.log(`Processed message ${record.body}`);
}
```
------
#### [ PHP ]
**SDK para PHP**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote do SQS com o Lambda usando PHP.
```
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
logger = $logger;
}
/**
* @throws JsonException
* @throws \Bref\Event\InvalidLambdaEvent
*/
public function handleSqs(SqsEvent $event, Context $context): void
{
$this->logger->info("Processing SQS records");
$records = $event->getRecords();
foreach ($records as $record) {
try {
// Assuming the SQS message is in JSON format
$message = json_decode($record->getBody(), true);
$this->logger->info(json_encode($message));
// TODO: Implement your custom processing logic here
} catch (Exception $e) {
$this->logger->error($e->getMessage());
// failed processing the record
$this->markAsFailed($record);
}
}
$totalRecords = count($records);
$this->logger->info("Successfully processed $totalRecords SQS records");
}
}
$logger = new StderrLogger();
return new Handler($logger);
```
------
#### [ Python ]
**SDK para Python (Boto3).**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote 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):
if event:
batch_item_failures = []
sqs_batch_response = {}
for record in event["Records"]:
try:
print(f"Processed message: {record['body']}")
except Exception as e:
batch_item_failures.append({"itemIdentifier": record['messageId']})
sqs_batch_response["batchItemFailures"] = batch_item_failures
return sqs_batch_response
```
------
#### [ Ruby ]
**SDK para Ruby**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda-with-batch-item-handling).
Relatar falhas de itens em lote do SQS com o Lambda usando Ruby.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
require 'json'
def lambda_handler(event:, context:)
if event
batch_item_failures = []
sqs_batch_response = {}
event["Records"].each do |record|
begin
# process message
rescue StandardError => e
batch_item_failures << {"itemIdentifier" => record['messageId']}
end
end
sqs_batch_response["batchItemFailures"] = batch_item_failures
return sqs_batch_response
end
end
```
------
#### [ Rust ]
**SDK para Rust**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/lambda-function-sqs-report-batch-item-failures).
Relatar falhas de itens em lote 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::{SqsBatchResponse, SqsEvent},
sqs::{BatchItemFailure, SqsMessage},
};
use lambda_runtime::{run, service_fn, Error, LambdaEvent};
async fn process_record(_: &SqsMessage) -> Result<(), Error> {
Err(Error::from("Error processing message"))
}
async fn function_handler(event: LambdaEvent) -> Result {
let mut batch_item_failures = Vec::new();
for record in event.payload.records {
match process_record(&record).await {
Ok(_) => (),
Err(_) => batch_item_failures.push(BatchItemFailure {
item_identifier: record.message_id.unwrap(),
}),
}
}
Ok(SqsBatchResponse {
batch_item_failures,
})
}
#[tokio::main]
async fn main() -> Result<(), Error> {
run(service_fn(function_handler)).await
}
```
------
Se os eventos com falha não retornarem à fila, consulte [Como soluciono problemas da função do Lambda do SQS ReportBatchItemFailures?](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-sqs-report-batch-item-failures/) no Centro de Conhecimento da AWS.
### Condições de sucesso e falha
O Lambda considera um lote um sucesso total quando a função retorna qualquer um dos seguintes:
+ Uma lista de `batchItemFailures` vazia
+ Uma lista de `batchItemFailures` nula
+ Uma vazia `EventResponse`
+ Uma nula `EventResponse`
O Lambda considera um lote uma falha total quando a função retorna qualquer um dos seguintes:
+ Uma resposta JSON inválida
+ Uma string vazia `itemIdentifier`
+ Uma nula `itemIdentifier`
+ Um `itemIdentifier` com um nome de chave inválido
+ Um valor `itemIdentifier` com um ID de mensagem inexistente
### Métricas do CloudWatch
Para determinar se a função está reportando falhas de itens em lote corretamente, é possível monitorar as métricas do Amazon SQS `NumberOfMessagesDeleted` e `ApproximateAgeOfOldestMessage` no Amazon CloudWatch.
+ `NumberOfMessagesDeleted` rastreia o número de mensagens removidas da sua fila. Se o número cair para 0, é um sinal de que a resposta da função não está retornando corretamente mensagens com falha.
+ `ApproximateAgeOfOldestMessage` rastreia quanto tempo a mensagem mais antiga permaneceu na sua fila. Um aumento acentuado nessa métrica pode indicar que a função não está retornando mensagens com falha corretamente.
### Usar o Powertools para o processador em lote AWS Lambda
O utilitário de processador em lote do Powertools para AWS Lambda lida de maneira automática com a lógica de respostas parciais em lote, reduzindo a complexidade da implementação de relatórios de falhas em lote. Veja a seguir alguns exemplos usando o processador em lote:
**Python**
Para ver exemplos completos e instruções de configuração, consulte a [documentação do processador em lote](https://docs.powertools.aws.dev/lambda/python/latest/utilities/batch/).
Processamento de mensagens do Amazon SQS com o processador em lote AWS Lambda.
```
import json
from aws_lambda_powertools import Logger
from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType, process_partial_response
from aws_lambda_powertools.utilities.data_classes import SQSEvent
from aws_lambda_powertools.utilities.typing import LambdaContext
processor = BatchProcessor(event_type=EventType.SQS)
logger = Logger()
def record_handler(record):
logger.info(record)
# Your business logic here
# Raise an exception to mark this record as failed
def lambda_handler(event, context: LambdaContext):
return process_partial_response(
event=event,
record_handler=record_handler,
processor=processor,
context=context
)
```
**TypeScript**
Para ver exemplos completos e instruções de configuração, consulte a [documentação do processador em lote](https://docs.aws.amazon.com/powertools/typescript/latest/features/batch/).
Processamento de mensagens do Amazon SQS com o processador em lote AWS Lambda.
```
import { BatchProcessor, EventType, processPartialResponse } from '@aws-lambda-powertools/batch';
import { Logger } from '@aws-lambda-powertools/logger';
import type { SQSEvent, Context } from 'aws-lambda';
const processor = new BatchProcessor(EventType.SQS);
const logger = new Logger();
const recordHandler = async (record: any): Promise => {
logger.info('Processing record', { record });
// Your business logic here
// Throw an error to mark this record as failed
};
export const handler = async (event: SQSEvent, context: Context) => {
return processPartialResponse(event, recordHandler, processor, {
context,
});
};
```
# Parâmetros do Lambda para mapeamentos de origem de eventos do Amazon SQS
Todos os tipos de origem de evento Lambda compartilham o mesmo[CreateEventSourceMapping](https://docs.aws.amazon.com/lambda/latest/api/API_CreateEventSourceMapping.html)e[UpdateEventSourceMapping](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateEventSourceMapping.html)Operações de API do. No entanto, apenas alguns dos parâmetros se aplicam ao Amazon SQS.
| Parâmetro | Obrigatório | Padrão | Observações |
| --- | --- | --- | --- |
| BatchSize | N | 10 | Para filas padrão, o máximo é 10 mil. Para filas FIFO, o máximo é dez. |
| Habilitado | N | true | nenhuma |
| EventSourceArn | S | N/D | O ARN do fluxo de dados ou um consumidor de fluxo |
| FunctionName | S | N/D | nenhuma |
| FilterCriteria | N | N/D | [Controlar quais eventos o Lambda envia para a função](invocation-eventfiltering.md) |
| FunctionResponseTypes | N | N/D | Para permitir que sua função reporte falhas específicas em um lote, inclua o valor `ReportBatchItemFailures` em `FunctionResponseTypes`. Para obter mais informações, consulte [Implementar respostas parciais em lote](services-sqs-errorhandling.md#services-sqs-batchfailurereporting). |
| MaximumBatchingWindowInSeconds | N | 0 | A janela de lote não é compatível com filas FIFO |
| ProvisionedPollerConfig | N | N/D | Configura o número mínimo (2-200) e máximo (2-2000) de agentes de sondagem de eventos dedicados para o mapeamento da origem do evento do SQS. Cada agente de sondagem pode tratar até 1 MB/s de throughput e 10 invocações simultâneas. |
| ScalingConfig | N | N/D | [Configuração de simultaneidade máxima para origens de eventos do Amazon SQS](services-sqs-scaling.md#events-sqs-max-concurrency) |
# Usar a filtragem de eventos com uma origem de eventos do Amazon SQS
É possível usar filtragem de eventos para controlar quais registros de um stream ou fila que o Lambda enviará para a função. Para obter informações gerais sobre como a filtragem de eventos funciona, consulte [Controlar quais eventos o Lambda envia para a função](invocation-eventfiltering.md).
Esta seção tem como foco a filtragem de eventos para fontes de eventos do Amazon SMQ.
**nota**
Os mapeamentos das origens dos eventos do Amazon SQS é compatível apenas com filtragem na chave `body`.
**Topics**
+ [Conceitos básicos de filtragem de eventos do Amazon SQS](#filtering-SQS)
## Conceitos básicos de filtragem de eventos do Amazon SQS
Suponha que sua fila do Amazon SQS contenha mensagens no formato JSON a seguir.
```
{
"RecordNumber": 1234,
"TimeStamp": "yyyy-mm-ddThh:mm:ss",
"RequestCode": "AAAA"
}
```
Um exemplo de registro para essa fila seria como a seguir.
```
{
"messageId": "059f36b4-87a3-44ab-83d2-661975830a7d",
"receiptHandle": "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a...",
"body": "{\n "RecordNumber": 1234,\n "TimeStamp": "yyyy-mm-ddThh:mm:ss",\n "RequestCode": "AAAA"\n}",
"attributes": {
"ApproximateReceiveCount": "1",
"SentTimestamp": "1545082649183",
"SenderId": "AIDAIENQZJOLO23YVJ4VO",
"ApproximateFirstReceiveTimestamp": "1545082649185"
},
"messageAttributes": {},
"md5OfBody": "e4e68fb7bd0e697a0ae8f1bb342846b3",
"eventSource": "aws:sqs",
"eventSourceARN": "arn:aws:sqs:us-west-2:123456789012:my-queue",
"awsRegion": "us-west-2"
}
```
Para filtrar com base no conteúdo de suas mensagens do Amazon SQS, use a chave `body` no registro de mensagens do Amazon SQS. Suponha que você queira processar somente os registros onde o `RequestCode` na sua mensagem do Amazon SQS seja “BBBB”. O objeto `FilterCriteria` seria como a seguir.
```
{
"Filters": [
{
"Pattern": "{ \"body\" : { \"RequestCode\" : [ \"BBBB\" ] } }"
}
]
}
```
Para maior clareza, aqui está o valor de `Pattern` do filtro expandido em JSON simples.
```
{
"body": {
"RequestCode": [ "BBBB" ]
}
}
```
É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.
------
#### [ Console ]
Para adicionar esse filtro usando o console, siga as instruções em [Anexar critérios de filtro a um mapeamento de fonte de eventos (console)](invocation-eventfiltering.md#filtering-console) e insira a string a seguir em **Critérios do filtro**.
```
{ "body" : { "RequestCode" : [ "BBBB" ] } }
```
------
#### [ AWS CLI ]
Para criar um novo mapeamento da origem do evento com esses critérios de filtro usando a AWS Command Line Interface (AWS CLI), execute o comando a seguir.
```
aws lambda create-event-source-mapping \
--function-name my-function \
--event-source-arn arn:aws:sqs:us-east-2:123456789012:my-queue \
--filter-criteria '{"Filters": [{"Pattern": "{ \"body\" : { \"RequestCode\" : [ \"BBBB\" ] } }"}]}'
```
Para adicionar esses critérios de filtro a um mapeamento da origem do evento existente, execute o comando a seguir.
```
aws lambda update-event-source-mapping \
--uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--filter-criteria '{"Filters": [{"Pattern": "{ \"body\" : { \"RequestCode\" : [ \"BBBB\" ] } }"}]}'
```
------
#### [ AWS SAM ]
Para adicionar esse filtro usando o AWS SAM, adicione o trecho a seguir ao modelo YAML da origem do evento.
```
FilterCriteria:
Filters:
- Pattern: '{ "body" : { "RequestCode" : [ "BBBB" ] } }'
```
------
Suponha que você queira que sua função processe somente os registros onde `RecordNumber` seja maior que 9999. O objeto `FilterCriteria` seria como a seguir.
```
{
"Filters": [
{
"Pattern": "{ \"body\" : { \"RecordNumber\" : [ { \"numeric\": [ \">\", 9999 ] } ] } }"
}
]
}
```
Para maior clareza, aqui está o valor de `Pattern` do filtro expandido em JSON simples.
```
{
"body": {
"RecordNumber": [
{
"numeric": [ ">", 9999 ]
}
]
}
}
```
É possível adicionar seu filtro usando o console, a AWS CLI ou um modelo do AWS SAM.
------
#### [ Console ]
Para adicionar esse filtro usando o console, siga as instruções em [Anexar critérios de filtro a um mapeamento de fonte de eventos (console)](invocation-eventfiltering.md#filtering-console) e insira a string a seguir em **Critérios do filtro**.
```
{ "body" : { "RecordNumber" : [ { "numeric": [ ">", 9999 ] } ] } }
```
------
#### [ AWS CLI ]
Para criar um novo mapeamento da origem do evento com esses critérios de filtro usando a AWS Command Line Interface (AWS CLI), execute o comando a seguir.
```
aws lambda create-event-source-mapping \
--function-name my-function \
--event-source-arn arn:aws:sqs:us-east-2:123456789012:my-queue \
--filter-criteria '{"Filters": [{"Pattern": "{ \"body\" : { \"RecordNumber\" : [ { \"numeric\": [ \">\", 9999 ] } ] } }"}]}'
```
Para adicionar esses critérios de filtro a um mapeamento da origem do evento existente, execute o comando a seguir.
```
aws lambda update-event-source-mapping \
--uuid "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \
--filter-criteria '{"Filters": [{"Pattern": "{ \"body\" : { \"RecordNumber\" : [ { \"numeric\": [ \">\", 9999 ] } ] } }"}]}'
```
------
#### [ AWS SAM ]
Para adicionar esse filtro usando o AWS SAM, adicione o trecho a seguir ao modelo YAML da origem do evento.
```
FilterCriteria:
Filters:
- Pattern: '{ "body" : { "RecordNumber" : [ { "numeric": [ ">", 9999 ] } ] } }'
```
------
No Amazon SQS, o corpo da mensagem pode ser qualquer string. Porém, isso pode ser problemático se os `FilterCriteria` esperarem que o `body` esteja em um formato JSON válido. O cenário oposto também é verdadeiro: se o corpo da mensagem recebida estiver em formato JSON, mas seus critérios de filtragem esperarem que o `body` seja uma string simples, isso poderá levar um comportamento não pretendido.
Para evitar esse problema, certifique-se de que o formato do corpo nos seus `FilterCriteria` corresponda ao formato esperado do `body` nas mensagens que você receber da fila. Antes de filtrar suas mensagens, o Lambda avalia automaticamente o formato do corpo da mensagem recebida e do seu padrão de filtro para o `body`. Se houver incompatibilidade, o Lambda descartará a mensagem. A tabela a seguir resume essa avaliação:
| Formato do `body` da mensagem recebida | Formato do `body` do padrão de filtro | Ação resultante |
| --- | --- | --- |
| String simples | String simples | Filtros do Lambda com base em seus critérios de filtro. |
| String simples | Nenhum padrão de filtro para propriedades de dados | Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro. |
| String simples | JSON válido | O Lambda descarta a mensagem. |
| JSON válido | String simples | O Lambda descarta a mensagem. |
| JSON válido | Nenhum padrão de filtro para propriedades de dados | Filtros do Lambda (somente nas outras propriedades de metadados) com base nos seus critérios de filtro. |
| JSON válido | JSON válido | Filtros do Lambda com base em seus critérios de filtro. |
# 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)](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/welcome.html). 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.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_resources.png)
Para concluir este tutorial, execute as seguintes tarefas:
1. Crie uma função do Lambda que grave mensagens no CloudWatch Logs.
1. Crie uma fila do Amazon SQS.
1. 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.
1. Teste a configuração ao adicionar mensagens à sua fila e ao monitorar os resultados no CloudWatch Logs.
## Pré-requisitos
### Instalar o AWS Command Line Interface
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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 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](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
## Criar a função de execução
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps1.png)
Um [perfil de execução](lambda-intro-execution-role.md) é um perfil do AWS Identity and Access Management (IAM) que concede a uma função do Lambda permissão para acessar recursos e Serviços 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 [Funções](https://console.aws.amazon.com/iam/home#/roles) no console do IAM.
1. Selecione **Criar perfil**.
1. Em **Tipo de entidade confiável**, escolha **Serviços da AWS**.
1. Em **Caso de uso**, escolha **Lambda**.
1. Escolha **Próximo**.
1. Na caixa de pesquisa **Políticas de permissões**, insira **AWSLambdaSQSQueueExecutionRole**.
1. Selecione a política **AWSLambdaSQSQueueExecutionRole** e, em seguida, escolha **Próximo**.
1. 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
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps2.png)
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 24, mas também fornecemos exemplos de códigos 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 ]
**SDK para .NET**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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 {
@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)**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/blob/main/integration-sqs-to-lambda).
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 => {
for (const message of event.Records) {
await processMessageAsync(message);
}
console.info("done");
};
async function processMessageAsync(message: SQSRecord): Promise {
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**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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
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).**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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**
Há mais no GitHub. Encontre o exemplo completo e saiba como configurar e executar no repositório dos [Exemplos sem servidor](https://github.com/aws-samples/serverless-snippets/tree/main/integration-sqs-to-lambda).
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) -> 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
```
1. Copie o código JavaScript de amostra em um novo arquivo denominado `index.js`.
1. Crie um pacote de implantação usando o comando `zip` a seguir.
```
zip function.zip index.js
```
1. Crie uma função do Lambda usando o comando [create-function](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/create-function.html) 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 nodejs24.x \
--role arn:aws:iam::111122223333:role/lambda-sqs-role
```
## Testar a função
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps3.png)
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"`.
**Example 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"
}
]
}
```
1. Execute o comando [invoke](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/invoke.html) 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](monitoring-cloudwatchlogs-view.md#monitoring-cloudwatchlogs-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](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*.
1. 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
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps4.png)
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](https://console.aws.amazon.com/sqs).
1. Selecione **Criar fila**.
1. Insira um nome para a fila. Deixe todas as outras opções nas configurações padrão.
1. 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
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps5.png)
Conecte a fila do Amazon SQS à função do Lambda ao criar um [mapeamento da origem do evento](invocation-eventsourcemapping.md). 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](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/lambda/create-event-source-mapping.html) 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](https://awscli.amazonaws.com/v2/documentation/api/2.1.29/reference/lambda/list-event-source-mappings.html). Exemplo:
```
aws lambda list-event-source-mappings --function-name ProcessSQSRecord
```
## Envie uma mensagem de teste
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps6.png)
**Enviar uma mensagem do Amazon SQS para a função do Lambda**
1. Abra o [console do Amazon SQS](https://console.aws.amazon.com/sqs).
1. Escolha a fila que você criou anteriormente.
1. Escolha **Enviar e receber mensagens**.
1. Em **Corpo da mensagem**, insira uma mensagem de teste, como “esta é uma mensagem de teste”.
1. 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 êxito, 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
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/sqs_tut_steps7.png)
**Confirmar que a função processou a mensagem**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Escolha a função **ProcessSQSRecord**.
1. Escolha **Monitor**.
1. Escolha **Visualizar logs do CloudWatch**.
1. No console do CloudWatch, escolha o **Fluxo de logs** para a função.
1. 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](https://console.aws.amazon.com/iam/home#/roles) (Funções) no console do IAM.
1. Selecione a função de execução que você criou.
1. Escolha **Excluir**.
1. 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](https://console.aws.amazon.com/lambda/home#/functions) (Funções) no console do Lambda.
1. Selecione a função que você criou.
1. Selecione **Ações**, **Excluir**.
1. Digite **confirm** no campo de entrada de texto e escolha **Delete** (Excluir).
**Para excluir a fila do Amazon SQS**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon SQS em [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/).
1. Selecione a fila que você criou.
1. Escolha **Excluir**.
1. Digite **confirm** no campo de entrada de texto.
1. Escolha **Excluir**.
# Tutorial: Uso de uma fila do Amazon SQS entre contas como a origem de um evento
Neste tutorial, você criará uma função do Lambda que consome mensagens de uma fila do Amazon Simple Queue Service (Amazon SQS) em uma conta da AWS diferente. Este tutorial envolve duas contas da AWS: **Conta A** refere-se à conta que contém sua função do Lambda e **Conta B** refere-se à conta que contém a fila do Amazon SQS.
## Pré-requisitos
### Instalar o AWS Command Line Interface
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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 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](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
## Criar a função de execução (Conta A)
Na **Conta A**, crie uma [função de execução](lambda-intro-execution-role.md) que dê à sua função permissão para acessar os recursos da AWS necessários.
**Para criar uma função de execução**
1. Abra a página [Roles](https://console.aws.amazon.com/iam/home#/roles) (Funções) no console do AWS Identity and Access Management (IAM).
1. Selecione **Criar perfil**.
1. Crie uma função com as propriedades a seguir.
+ **Trusted entity (Entidade confiável** – **AWS Lambda**
+ **Permissões**: **AWSLambdaSQSQueueExecutionRole**.
+ **Role name (Nome da função** – **cross-account-lambda-sqs-role**
A política **AWSLambdaSQSQueueExecutionRole** tem as permissões necessárias para a função ler itens do Amazon SQS e para gravar logs no Amazon CloudWatch Logs.
## Criar a função (Conta A)
Na **Conta A**, crie uma função do Lambda para processar suas mensagens do Amazon SQS. A função do Lambda e a fila do Amazon SQS devem estar na mesma Região da AWS.
A seguir, o exemplo de código Node.js grava cada mensagem em um log do CloudWatch Logs.
**Example index.mjs**
```
export const handler = async function(event, context) {
event.Records.forEach(record => {
const { body } = record;
console.log(body);
});
return {};
}
```
**Para criar a função**
**nota**
Seguir estas etapas cria uma função no Node.js. Para outras linguagens, as etapas são semelhantes, mas alguns detalhes são diferentes.
1. Salve o exemplo de código como um arquivo denominado `index.mjs`.
1. Crie um pacote de implantação.
```
zip function.zip index.mjs
```
1. Crie a função usando o comando `create-function` da AWS Command Line Interface (AWS CLI). Substitua `arn:aws:iam::111122223333:role/cross-account-lambda-sqs-role` pelo ARN do perfil de execução que você criou anteriormente.
```
aws lambda create-function --function-name CrossAccountSQSExample \
--zip-file fileb://function.zip --handler index.handler --runtime nodejs24.x \
--role arn:aws:iam::111122223333:role/cross-account-lambda-sqs-role
```
## Teste a função (Conta A)
Na **Conta A**, invoque sua função do Lambda manualmente usando o comando `invoke` AWS CLI e um evento do Amazon SQS de exemplo.
Se o manipulador obtém um retorno normal sem exceções, o Lambda considerará a mensagem como processada com êxito e começará a ler novas mensagens na fila. Após o processamento com êxito, uma mensagem,o Lambda a exclui automaticamente da fila. Se o manipulador gera uma exceção, o Lambda considera que o batch de mensagens que não foram processadas com êxito e o Lambda invoca novamente a função com o mesmo batch de mensagens.
1. Salve o JSON a seguir como um arquivo denominado `input.txt`.
```
{
"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:example-queue",
"awsRegion": "us-east-1"
}
]
}
```
O JSON anterior simula um evento que o Amazon SQS pode enviar para a função do Lambda, onde `"body"` contém a mensagem real da fila.
1. Execute o comando `invoke` a seguir da AWS CLI.
```
aws lambda invoke --function-name CrossAccountSQSExample \
--cli-binary-format raw-in-base64-out \
--payload file://input.txt outputfile.txt
```
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*.
1. Verifique a saída no arquivo `outputfile.txt`.
## Criar uma fila do Amazon SQS (Conta B)
Na **Conta B**, crie uma fila do Amazon SQS que a função do Lambda na **Conta A** 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](https://console.aws.amazon.com/sqs).
1. Selecione **Criar fila**.
1. Crie uma fila com as propriedades a seguir.
+ **Type** (Tipo): **Standard** (Padrão)
+ **Name** (Nome): **LambdaCrossAccountQueue**
+ **Configuration** (Configuração): mantenha as configurações padrão.
+ **Access policy** (Política de acesso): selecione **Advanced** (Avançado). Cole na seguinte política do JSON. Substitua os valores a seguir:
+ `111122223333`: Conta da AWS ID da **Conta A**
+ `444455556666`: Conta da AWS ID da **Conta B**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "Queue1_Policy_UUID",
"Statement": [
{
"Sid": "Queue1_AllActions",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/cross-account-lambda-sqs-role"
]
},
"Action": "sqs:*",
"Resource": "arn:aws:sqs:us-east-1:444455556666:LambdaCrossAccountQueue"
}
]
}
```
------
Esta política concede à função de execução do Lambda na **Conta A** permissões para consumir mensagens desta fila do Amazon SQS.
1. Depois de criar a fila, registre o nome do recurso da Amazon (ARN). Você precisará dele na próxima etapa, quando for associar a fila à função do Lambda.
## Configurar a origem do evento (Conta A)
Na **Conta A**, crie um mapeamento da origem do evento entre a fila do Amazon SQS na **Conta B** e sua função do Lambda executando o comando `create-event-source-mapping` da AWS CLI a seguir. Substitua `arn:aws:sqs:us-east-1:444455556666:LambdaCrossAccountQueue` pelo ARN da fila do Amazon SQS que você criou na etapa anterior.
```
aws lambda create-event-source-mapping --function-name CrossAccountSQSExample --batch-size 10 \
--event-source-arn arn:aws:sqs:us-east-1:444455556666:LambdaCrossAccountQueue
```
Para obter uma lista de mapeamentos de fonte do evento, execute o comando a seguir.
```
aws lambda list-event-source-mappings --function-name CrossAccountSQSExample \
--event-source-arn arn:aws:sqs:us-east-1:444455556666:LambdaCrossAccountQueue
```
## Testar a configuração
Você agora pode testar a configuração da seguinte forma:
1. Na **Conta B**, abra o [console do Amazon SQS](https://console.aws.amazon.com/sqs).
1. Escolha **LambdaCrossAccountQueue** criada anteriormente.
1. Escolha **Send and receive messages (Enviar e receber mensagens)**.
1. Em **Message body** (Corpo da mensagem), insira uma mensagem de teste.
1. Escolha **Send Message (Enviar mensagem)**.
Sua função do Lambda na **Conta A** deve receber a mensagem. O Lambda continuará a sondar a fila em busca de atualizações. Quando há uma nova mensagem, o Lambda invoca a sua função com esses novos dados de evento da fila. A função é executada e cria logs no Amazon CloudWatch. É possível visualizar os logs no [console do CloudWatch](https://console.aws.amazon.com/cloudwatch).
## 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.
Na **Conta A**, limpe sua função de execução e a função do Lambda.
**Para excluir a função de execução**
1. Abra a página [Roles](https://console.aws.amazon.com/iam/home#/roles) (Funções) no console do IAM.
1. Selecione a função de execução que você criou.
1. Escolha **Excluir**.
1. 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](https://console.aws.amazon.com/lambda/home#/functions) (Funções) no console do Lambda.
1. Selecione a função que você criou.
1. Selecione **Actions**, **Delete**.
1. Digite **confirm** no campo de entrada de texto e escolha **Delete** (Excluir).
Na **Conta B**, limpe a fila do Amazon SQS.
**Para excluir a fila do Amazon SQS**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon SQS em [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/).
1. Selecione a fila que você criou.
1. Escolha **Excluir**.
1. Digite **confirm** no campo de entrada de texto.
1. Escolha **Excluir**.