Tratar condições de erro usando uma máquina de estado Step Functions

Neste tutorial, você criará uma máquina de estado do AWS Step Functions com um campo Estados de fallback. O campo Catch usa uma função AWS Lambda para responder com lógica condicional com base no tipo de mensagem de erro. Essa é uma técnica denominada tratamento de erro de função.

Para obter mais informações, consulte Erros da função AWS Lambda no Node.js no Guia do desenvolvedor do AWS Lambda.

nota

Você pode também criar máquinas de estado que usem Tentar novamente para os limites de tempo ou que usem Catch para mudar para um estado específico quando ocorre um erro ou um tempo limite é atingido. Para obter exemplos dessas técnicas de tratamento de erro, consulte Exemplos que usam retry e catch.

Etapa 1: Criar uma função do Lambda que apresenta falha

Use uma função do Lambda para simular uma condição de erro.

Importante

Verifique se a função do Lambda está na mesma conta da AWS e na mesma Região da AWS que a máquina de estado.

1. Abra o console do AWS Lambda em https://console.aws.amazon.com/lambda/.

2. Escolha Create function.

3. Escolha Usar um esquema, insira step-functions na caixa de pesquisa e escolha o esquema Throw a custom error (Lançar um erro personalizado).

4. Em Function name (Nome da função), insira FailFunction.

5. Para Função, retenha a seleção-padrão (Create a new role with basic Lambda permissions (Criar uma função com permissões básicas do Lambda)).

6. O código a seguir é exibido no painel Código de função do Lambda.

   exports.handler = async (event, context) => {
       function CustomError(message) {
           this.name = 'CustomError';
           this.message = message;
       }
       CustomError.prototype = new Error();
   
       throw new CustomError('This is a custom error!');
   };

   O objeto context retorna a mensagem de erro This is a custom error!.

7. Escolha Create function.

8. Depois que a função do Lambda foi criada, copie o nome do recurso da Amazon (ARN) da função exibido no canto superior direito da página. A seguir está um exemplo de ARN.

   arn:aws:lambda:us-east-1:123456789012:function:FailFunction

9. Escolha Implantar.

Etapa 2: testar a função do Lambda

Teste a função do Lambda para vê-la em operação.

1. Na página FailFunction, escolha a guia Teste e então Teste. Não é necessário criar um evento de teste.

2. Para analisar os resultados do teste, em Resultado da execução, expanda Detalhes.

Etapa 3: Criar uma máquina de estado com um campo Capturar

Use o console do Step Functions para criar uma máquina de estado que use um estado Estado de tarefa do fluxo de trabalho com um campo Catch. Adicione uma referência à função do Lambda no estado Tarefa. A máquina de estado invoca a função do Lambda, que falha durante a execução. O Step Functions tenta executar a função duas outras vezes usando recuo exponencial entre novas tentativas.

1. Abra o console do Step Functions e clique em Criar máquina de estado.

2. Na caixa de diálogo Escolher um modelo, selecione Em branco.

3. Escolha Selecionar para abrir o Workflow Studio em Modo de design.

4. Selecione Código para abrir o editor de código. No editor de código, você grava e edita a definição de Amazon States Language (ASL) do fluxo de trabalho.

5. Cole o código a seguir, mas substitua o ARN da função do Lambda criada antes no campo Resource.

   {
      "Comment": "A Catch example of the Amazon States Language using an AWS Lambda function",
      "StartAt": "CreateAccount",
      "States": {
         "CreateAccount": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
            "Catch": [ {
               "ErrorEquals": ["CustomError"],
               "Next": "CustomErrorFallback"
            }, {
               "ErrorEquals": ["States.TaskFailed"],
               "Next": "ReservedTypeFallback"
            }, {
               "ErrorEquals": ["States.ALL"],
               "Next": "CatchAllFallback"
            } ],
            "End": true
         },
         "CustomErrorFallback": {
            "Type": "Pass",
            "Result": "This is a fallback from a custom Lambda function exception",
            "End": true
         },
         "ReservedTypeFallback": {
            "Type": "Pass",
            "Result": "This is a fallback from a reserved error code",
            "End": true
         },
         "CatchAllFallback": {
            "Type": "Pass",
            "Result": "This is a fallback from any error code",
            "End": true
         }
      }
   }

   Essa é uma descrição da máquina de estado usando a Amazon States Language. Ela define um estado Task específico denominado CreateAccount. Para obter mais informações, consulte Estrutura da máquina de estado.

   Para obter mais informações sobre a sintaxe do campo Retry, consulte Exemplos de máquina de estado usando repetição e captura.

   nota

   Os erros não tratados no Lambda são relatados como Lambda.Unknown na saída do erro. Isso inclui erros de falta de memória e tempos limite de função. Você pode combinar com Lambda.Unknown, States.ALL ou States.TaskFailed para lidar com esses erros. Quando o Lambda atinge o número máximo de invocações, o erro é Lambda.TooManyRequestsException. Para ter mais informações sobre os erros Handled e Unhandled do Lambda, consulte FunctionError no Guia do desenvolvedor do AWS Lambda.

6. (Opcional) No Visualização de grafos, veja a visualização gráfica em tempo real do seu fluxo de trabalho.

7. Especifique um nome para a máquina de estado. Para fazer isso, clique no ícone de edição ao lado do nome da máquina de estado padrão MyStateMachine. Em seguida, em Configuração da máquina de estado, insira um nome na caixa Nome da máquina de estado.

   Para este tutorial, insira Catchfailure.

8. (Opcional) Em Configuração da máquina de estado, especifique outras configurações do fluxo de trabalho, como o tipo de máquina de estado e a função de execução.

   Para este tutorial, mantenha todas as seleções padrão nas Configurações da máquina de estado.

9. Na caixa de diálogo Confirmar criação do perfil, selecione Confirmar para continuar.

   Você também pode escolher Exibir configurações do perfil para voltar às Configurações da máquina de estado.

   nota

   Se você excluir o perfil do IAM criado pelo Step Functions, não será possível recriá-lo posteriormente. Da mesma forma, se você modificar a função (por exemplo, removendo o Step Functions das entidades principais na política do IAM), o Step Functions não poderá restaurar as configurações originais dela posteriormente.

Etapa 4: Executar a máquina de estado

Depois que você criar uma máquina de estado, poderá executá-la.

1. Na página Máquinas de estado, escolha Catchfailure.

2. Na página Catchfailure, escolha Iniciar execução. A caixa de diálogo Iniciar execução é exibida.

3. Na caixa de diálogo Iniciar execução, faça o seguinte:

   1. (Opcional) Insira um nome de execução personalizado para substituir o padrão gerado.

      Nomes e registro em log não ASCII

      O Step Functions aceita nomes de máquina de estado, execuções, atividades e rótulos que contenham caracteres não ASCII. Como esses caracteres não funcionarão com o Amazon CloudWatch, recomendamos usar somente caracteres ASCII para que você possa monitorar métricas no CloudWatch.

   2. (Opcional) No campo Entrada, insira os valores de entrada no formato JSON para executar o fluxo de trabalho.

   3. Selecione Iniciar execução.

   4. O console do Step Functions direciona você para uma página em que o título é o ID da execução. Essa página é conhecida como página de Detalhes da execução. Nesta página, você pode revisar os resultados da execução à medida que a execução avança ou após a conclusão.

      Para revisar os resultados da execução, escolha estados individuais na Exibição em gráfico e, em seguida, escolha as guias individuais no painel Detalhes da etapa para visualizar os detalhes de cada estado, incluindo entrada, saída e definição, respectivamente. Para obter detalhes sobre as informações de execução que você pode visualizar na página Detalhes da execução, consulte Visão geral dos detalhes da execução.

   Por exemplo, para visualizar sua mensagem de erro personalizada, escolha a etapa CreateAccount na Exibição em gráfico e escolha a guia Saída.

   

   nota

   Você pode preservar a entrada de estado com o erro usando ResultPath. Consulte Use ResultPath para incluir erro e entrada em um Catch.