Invocação assíncrona

Vários Serviços da AWS, como o Amazon Simple Storage Service (Amazon S3) e o Amazon Simple Notification Service (Amazon SNS), invocam funções de forma assíncrona para processar eventos. Ao invocar uma função de forma assíncrona, não aguarde uma resposta do código da função. Você entrega o evento para o Lambda e ele cuida do resto. Você pode configurar como o Lambda processa os erros e pode enviar registros de invocação para um recurso downstream, como o Amazon Simple Queue Service (Amazon SQS) ou o Amazon EventBridge (EventBridge), para encadear componentes da aplicação.

Como o Lambda trabalha com invocações assíncronas

O diagrama a seguir mostra clientes invocando uma função do Lambda de forma assíncrona. O Lambda coloca os eventos em fila antes de enviá-los para a função.

Para invocação de forma assíncrona, o Lambda coloca o evento em uma fila e retorna uma resposta bem-sucedida sem informações adicionais. Um processo separado lê os eventos na fila e os envia para sua função. Para invocar uma função de maneira assíncrona, defina o parâmetro do tipo de invocação como Event.

aws lambda invoke \
  --function-name my-function  \
  --invocation-type Event \
  --cli-binary-format raw-in-base64-out \
  --payload '{ "key": "value" }' response.json
  

A opção cli-binary-format será necessária se você estiver usando a AWS CLI versão 2. Para que essa seja a configuração padrão, execute aws configure set cli-binary-format raw-in-base64-out. Para obter mais informações, consulte A AWS CLI comporta opções de linha de comando globais no Guia do usuário da AWS Command Line Interface versão 2.

{
    "StatusCode": 202
}

O arquivo de saída (response.json) não contém informações, mas continuará sendo criado quando esse comando for executado. Se o Lambda não conseguir adicionar o evento a uma fila, a mensagem de erro será exibida na saída do comando.

O Lambda gerencia a fila de eventos assíncronos da função e realiza novas tentativas em casos de erro. Se a função retornar um erro, o Lambda tentará executá-la mais duas vezes, com um intervalo de um minuto entre a primeira e a segunda tentativa, e um intervalo de dois minutos entre a segunda e a terceira. Os erros de função incluem erros retornados pelo código e pelo runtime da função, como o tempo ser atingido.

Se a função não tiver simultaneidade suficiente disponível para processar todos os eventos, as solicitações adicionais serão limitadas. Para erros de controle de utilização (429) e de sistema (série 500), o Lambda retorna o evento para a fila e tenta executar a função novamente por até 6 horas. O intervalo de repetição aumenta exponencialmente de 1 segundo após a primeira tentativa para no máximo 5 minutos. Se a fila contém muitas entradas, o Lambda aumenta o intervalo de repetição e reduz a taxa em que lê eventos da fila.

Mesmo que a função não retorne um erro, é possível que ela receba o mesmo evento do Lambda várias vezes, porque a própria fila se tornará consistente. Se a função não conseguir acompanhar os eventos recebidos, é possível que eventos sejam excluídos da fila sem serem enviados para a função. Certifique-se de que seu código de função lide corretamente com eventos duplicados, e de que você tenhas simultaneidade suficiente disponível para lidar com todas as invocações.

Quando a fila é muito longa, novos eventos podem expirar antes de o Lambda ter a chance de enviá-los para sua função. Quando há falha em todas as tentativas de processamento de um evento ou ele expira, o Lambda o descarta. É possível configurar o tratamento de erros para uma função a fim de reduzir o número de tentativas que o Lambda executa ou descartar eventos não processados mais rapidamente.

Também é possível configurar o Lambda para enviar um registro de invocação para outro serviço. O Lambda suporta os destinos a seguir para invocação assíncrona. Observe que as filas do SQS FIFO e os tópicos do SNS FIFO não são compatíveis.

• Amazon SQS— Uma fila SQS padrão.

• Amazon SNS: um padrão do tópico SNS.

• AWS Lambda: uma função do Lambda.

• Amazon EventBridge: u barramento de eventos do EventBridge.

O registro de invocação contém detalhes sobre a solicitação e a resposta no formato JSON. É possível configurar destinos separados para eventos que são processados com êxito e eventos em que há falha no processamento de todas as tentativas. Como alternativa, é possível configurar uma fila padrão do Amazon SQS ou um tópico padrão do Amazon SNS como uma fila de mensagens não entregues para os eventos descartados. Para filas de mensagens mortas, o Lambda envia somente o conteúdo do evento, sem detalhes sobre a resposta.

Se o Lambda não conseguir enviar um registro para um destino que você configurou, ele enviará uma métrica DestinationDeliveryFailures para o Amazon CloudWatch. Isso poderá acontecer se sua configuração incluir um tipo de destino incompatível, como uma fila do Amazon SQS FIFO ou um tópico do Amazon SNS FIFO. Os erros de entrega também podem ocorrer devido a erros de permissão e limites de tamanho. Para obter mais informações sobre as métricas de invocação do Lambda, consulte Métricas de invocação.

nota

Para evitar que uma função seja acionada, você pode definir a simultaneidade reservada da função como zero. Quando você define a simultaneidade reservada como zero para uma função invocada de forma assíncrona, o Lambda começa a enviar novos eventos para a fila de mensagens não entregues configurada ou para o destino do evento em caso de falha, sem novas tentativas. Para processar eventos que foram enviados enquanto a simultaneidade reservada estava definida como zero, você precisa consumir os eventos da fila de mensagens não entregues ou do destino do evento em caso de falha.

Configurar o tratamento de erros para invocação assíncrona

Use o console do Lambda para definir as configurações de tratamento de erros em uma função, uma versão ou um alias.

Como configurar o tratamento de erros

1. Abra a página Funções do console do Lambda.

2. Escolha uma função.

3. Escolha Configuration (Configuração) e, em seguida, Asynchronous invocation (Invocação assíncrona).

4. Em Asynchronous invocation (Invocação assíncrona), escolha Edit (Editar).

5. Configure as definições a seguir.

   • Maximum age of event (Idade máxima do evento): a quantidade máxima de tempo que o Lambda retém um evento na fila de eventos assíncronos, até 6 horas.

   • Retry attempts (Tentativas de repetição): o número de vezes que o Lambda tenta novamente quando a função retorna um erro, entre 0 e 2.

6. Escolha Salvar.

Quando um evento de invocação exceder a idade máxima ou falhar em todas as tentativas de repetição, o Lambda o descartará. Para reter uma cópia de eventos descartados, configure um destino de evento com falha.

Configurar destinos para invocação assíncrona

Para reter registros de invocações assíncronas, adicione um destino à função. Você pode optar por enviar invocações com êxito ou com falha para um destino. Cada função pode ter vários destinos para que você possa configurar destinos separados para eventos com êxito e com falha. Cada registro enviado ao destino é um documento JSON com detalhes sobre a invocação. Da mesma forma que as configurações de tratamento de erros, é possível configurar destinos em uma função, em uma versão de função ou em um alias.

nota

Você também pode reter registros de invocações com falha para determinados tipos de mapeamento da origem do evento. Para ter mais informações, consulte Configurar destinos para invocações de mapeamento da origem do evento.

A tabela a seguir lista os destinos aceitos para registros de invocação assíncrona. Para que o Lambda envie registros com êxito ao destino escolhido, certifique-se de que o perfil de execução da função também contenha as permissões relevantes. A tabela também descreve como cada tipo de destino recebe o registro de invocação JSON.

Tipos de destino	Permissão obrigatória	Formato JSON específico para o destino
Fila do Amazon SQS	sqs:SendMessage	O Lambda passa o registro de invocação como Message para o destino.
Tópico do Amazon SNS	sns:Publish	O Lambda passa o registro de invocação como Message para o destino.
Função do Lambda	InvokeFunction	O Lambda passa o registro de invocação como a carga útil para a função.
EventBridge	events:PutEvents	O Lambda passa o registro de invocação como detail na chamada PutEvents. O valor para o campo do evento source é lambda. O valor para o campo de evento detail-type é “Lambda Function Invocation Result - Success” ou “Lambda Function Invocation Result - Failure”. O campo do evento resource contém nomes do recurso da Amazon (ARN) da função e do destino. Para outros campos de eventos, consulte os eventos do Amazon EventBridge.

O exemplo a seguir mostra um registro de invocação para um evento que teve três falhas de tentativa de processamento devido a um erro de função. O registro de invocação contém detalhes sobre o evento, a resposta e o motivo pelo qual o registro foi enviado.

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

As etapas a seguir descrevem como configurar um destino para uma função usando o console do Lambda.

Configurar um destino para registros de invocação assíncrona

1. Abra a página Funções do console do Lambda.

2. Escolha uma função.

3. Em Function overview (Visão geral da função), escolha Add destination (Adicionar destino).

4. Em Source (Origem), escolha Asynchronous invocation (Invocação assíncrona).

5. Em Condition (Condição), escolha uma das seguintes opções:

   • On failure (Em caso de falha): envie um registro quando o evento falhar em todas as tentativas de processamento ou exceder a idade máxima.

   • On success (Em caso de êxito): envie um registro quando a função processa com êxito uma invocação assíncrona.

6. Em Destination type (Tipo de destino), escolha o tipo de recurso que recebe o registro da invocação.

7. Em Destination (Destino), escolha um recurso.

8. Escolha Salvar.

Quando uma invocação corresponde à condição, o Lambda envia um documento JSON com detalhes sobre a invocação para o destino.

Formato JSON específico para o destino

• No Amazon SQS e no Amazon SNS (SnsDestination e SqsDestination), o registro de invocação é passado como Message para o destino.

• No Lambda (LambdaDestination), o registro de invocação é passado como carga útil para a função.

• No EventBridge (EventBridgeDestination), o registro de invocação é passado como detailna chamada PutEvents. O valor para o campo do evento source é lambda. O valor para o campo de evento detail-type é Lambda Function Invocation Result – Success (Resultado da invocação da função Lambda: sucesso) ou Lambda Function Invocation Result – Failure (Resultado da invocação da função Lambda: falha). O campo do evento resource contém nomes do recurso da Amazon (ARN) da função e do destino. Para outros campos de eventos, consulte os eventos do Amazon EventBridge.

O exemplo a seguir mostra um registro de invocação para um evento que teve três falhas de tentativa de processamento devido a um erro de função.

exemplo registro de invocação

{
    "version": "1.0",
    "timestamp": "2019-11-14T18:16:05.568Z",
    "requestContext": {
        "requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
        "functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:$LATEST",
        "condition": "RetriesExhausted",
        "approximateInvokeCount": 3
    },
    "requestPayload": {
        "ORDER_IDS": [
            "9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
            "637de236-e7b2-464e-xmpl-baf57f86bb53",
            "a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
        ]
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST",
        "functionError": "Unhandled"
    },
    "responsePayload": {
        "errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited before completing request"
    }
}

O registro de invocação contém detalhes sobre o evento, a resposta e o motivo pelo qual o registro foi enviado.

Rastreamento de solicitações até destinos

Você pode usar o AWS X-Ray para exibir uma visualização conectada de cada solicitação à medida que ela é adicionada à fila, processada por uma função do Lambda e passada para o serviço de destino. Quando você ativa o rastreamento com X-Ray para uma função ou um serviço que invoca uma função, o Lambda adiciona um cabeçalho X-Ray à solicitação e passa o cabeçalho para o serviço de destino. Os rastreamentos dos serviços de upstream são vinculados automaticamente aos rastreamentos de funções do Lambda e serviços de downstream, o que cria uma visão completa de toda a aplicação. Para obter mais informações sobre rastreamento, consulte Usar o AWS Lambda com o AWS X-Ray.

API de configuração de invocação assíncrona

Para gerenciar configurações de invocação assíncrona com a AWS CLI ou o AWS SDK, use as operações de API a seguir.

• PutFunctionEventInvokeConfig

• GetFunctionEventInvokeConfig

• UpdateFunctionEventInvokeConfig

• ListFunctionEventInvokeConfigs

• DeleteFunctionEventInvokeConfig

Para configurar a invocação assíncrona com a AWS CLI, use o comando put-function-event-invoke-config. O exemplo a seguir configura uma função com uma idade máxima de evento de 1 hora e nenhuma repetição.

aws lambda put-function-event-invoke-config --function-name error \
--maximum-event-age-in-seconds 3600 --maximum-retry-attempts 0

A seguinte saída deverá ser mostrada:

{
    "LastModified": 1573686021.479,
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
    "MaximumRetryAttempts": 0,
    "MaximumEventAgeInSeconds": 3600,
    "DestinationConfig": {
        "OnSuccess": {},
        "OnFailure": {}
    }
}

O comando put-function-event-invoke-config substitui qualquer configuração existente na função, versão ou alias. Para configurar uma opção sem redefinir outras, use update-function-event-invoke-config. O exemplo a seguir configura o Lambda para enviar um registro a uma fila padrão do SQS denominada destination quando um evento não puder ser processado.

aws lambda update-function-event-invoke-config --function-name error \
--destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-east-2:123456789012:destination"}}'

A seguinte saída deverá ser mostrada:

{
    "LastModified": 1573687896.493,
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
    "MaximumRetryAttempts": 0,
    "MaximumEventAgeInSeconds": 3600,
    "DestinationConfig": {
        "OnSuccess": {},
        "OnFailure": {
            "Destination": "arn:aws:sqs:us-east-2:123456789012:destination"
        }
    }
}

Filas de mensagens mortas

Como alternativa a um destino em caso de falha, é possível configurar a função com uma fila de mensagens mortas para salvar eventos descartados para processamento adicional. Uma fila de mensagens mortas age da mesma forma que um destino em caso de falha na medida em que é usado quando há falha em todas as tentativas de processamento de um evento ou ele expira sem ser processado. No entanto, uma fila de mensagens mortas faz parte da configuração específica da versão de uma função, portanto ela é bloqueada quando você publica uma versão. Destinos em caso de falha também oferecem suporte a destinos adicionais e incluem detalhes sobre a resposta da função no registro de invocação.

Para reprocessar eventos em uma fila de mensagens mortas, você pode defini-la como uma fonte do evento para a função do Lambda. Você também pode recuperar os eventos manualmente.

É possível escolher uma fila padrão do Amazon SQS ou um tópico padrão do Amazon SNS para a sua fila de mensagens não entregues. As filas FIFO e os tópicos do Amazon SNS FIFO são incompatíveis. Se você não tiver uma fila ou um tópico, crie um. Escolha o tipo de destino que corresponde ao seu caso de uso.

• Fila do Amazon SQS: uma fila suspende os eventos falhos até serem recuperados. Escolha uma fila padrão do Amazon SQS caso espere que uma única entidade, como uma função do Lambda ou um alarme do CloudWatch, processe o evento que falhou. Para ter mais informações, consulte Usar o Lambda com o Amazon SQS.

  Crie uma fila no console do Amazon SQS.

• Tópico do Amazon SNS: um tópico retransmite os eventos com falha para um ou mais destinos. Escolha um tópico padrão do Amazon SNS caso espere que várias entidades atuem em um evento com falha. Por exemplo, você pode configurar um tópico para enviar eventos a um endereço de email, uma função do Lambda e/ou um endpoint HTTP. Para ter mais informações, consulte Uso do AWS Lambda com o Amazon SNS.

  Crie um tópico do SNS usando o console do Amazon SNS.

Sua função precisa de permissões adicionais para enviar eventos a uma fila ou um tópico. Adicione uma política com as permissões necessárias à função de execução de sua função.

• Amazon SQS – sqs:SendMessage

• Amazon SNS – sns:Publish

Se a fila ou o tópico de destino for criptografado com uma chave gerenciada pelo cliente, a função de execução também deverá ser um usuário na política baseada em recursos da chave.

Depois de criar o destino e atualizar a função de execução de sua função, adicione a fila de mensagens mortas à função. Você pode configurar várias funções para enviarem eventos ao mesmo destino.

Como configurar uma fila de mensagens mortas

1. Abra a página Funções do console do Lambda.

2. Escolha uma função.

3. Escolha Configuration (Configuração) e, em seguida, Asynchronous invocation (Invocação assíncrona).

4. Em Asynchronous invocation (Invocação assíncrona), escolha Edit (Editar).

5. Definarecurso DLQ para Amazon SQS ou Amazon SNS.

6. Escolha a fila ou o tópico de destino.

7. Escolha Salvar.

Para configurar uma fila de mensagens mortas com o AWS CLI, use o comando update-function-configuration.

aws lambda update-function-configuration --function-name my-function \
--dead-letter-config TargetArn=arn:aws:sns:us-east-2:123456789012:my-topic

O Lambda envia o evento para a fila de mensagens mortas no mesmo estado, mais informações adicionais nos atributos. Você pode usar essas informações para identificar o erro retornado pela função, ou correlacionar o evento com logs ou um rastreamento do AWS X-Ray.

Atributos de mensagens da fila de mensagens mortas

• RequestID (String): o ID de invocação da solicitação. Os IDs de solicitação aparecem nos logs de função. O X-Ray SDK também pode ser usado para registrar o ID de solicitação em um atributo no rastreamento. Em seguida, os rastreamentos podem ser procurados por ID de solicitação no console do X-Ray. Para ver um exemplo, consulte a amostra de processador de erros.

• ErrorCode (Número): o código de status HTTP.

• ErrorMessage (String): o primeiro 1 KB da mensagem de erro.

Se o Lambda não puder enviar uma mensagem para a fila de mensagens mortas, ele excluirá o evento e emitirá a métrica DeadLetterErrors. Isso pode acontecer por causa de falta de permissões, ou se o tamanho total da mensagem exceder o limite da fila ou do tópico de destino. Por exemplo, digamos que uma notificação do Amazon SNS com um tamanho de quase 256 KB acione uma função que resulte em erro. Nesse caso, os dados do evento incluídos pelo Amazon SNS, combinados aos atributos adicionados pelo Lambda, podem fazer com que a mensagem exceda o tamanho máximo permitido na fila de mensagens não entregues.

Se você está usando o Amazon SQS como uma fonte de eventos, configure uma fila de mensagens mortas na própria fila do Amazon SQS e não na função do Lambda. Para ter mais informações, consulte Usar o Lambda com o Amazon SQS.