As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Tratar erros em fluxos de trabalho do Step Functions

Todos os estados, exceto Pass e Wait, podem encontrar erros de tempo de execução. Os erros podem ocorrer por vários motivos, incluindo os seguintes:

Quando um estado relata um erro, o padrão do Step Functions é falhar em toda a execução da máquina de estado. O Step Functions também tem recursos mais avançados de tratamento de erros. Você pode configurar sua máquina de estado para capturar erros, repetir estados com falha e implementar protocolos de tratamento de erros com facilidade.

Os coletores Step Functions estão disponíveis para os estados Task, Parallel e Map, mas não para falhas de execução de máquinas de estado de alto nível. Para lidar com as execuções que você prevê que possam falhar, seu chamador pode lidar com o erro ou você pode agrupar essas execuções em fluxos de trabalho secundários para detectar erros no fluxo de trabalho principal. Como alternativa, você pode optar por ouvir TIMED_OUT os eventos dos fluxos de trabalho padrão com um EventBridge barramento e invocar uma ação para lidar com a falha na execução.

Nomes de erro

Step Functions identifica erros usando cadeias de caracteres que diferenciam maiúsculas de minúsculas, conhecidas como nomes de erro. A Amazon States Language define um conjunto de strings integradas que nomeiam erros conhecidos, todos iniciados com o prefixo States.

Os estados podem relatar erros com outros nomes. No entanto, os nomes dos erros não podem começar com o States. prefixo.

Certifique-se de que seu código de produção possa lidar com exceções de AWS Lambda serviço (Lambda.ServiceExceptioneLambda.SdkClientException). Para obter mais informações, consulte como fazer Processar exceções transitórias do serviço Lambda isso em Melhores práticas.

Repetir após um erro

Os estados Task, Parallel e Map podem ter um campo denominado Retry, cujo valor deve ser uma matriz de objetos conhecidos como agentes de repetição. Um retrier individual representa determinado número de novas tentativas, geralmente em intervalos de tempo crescentes.

Quando um desses estados relata um erro e há um campo Retry, o Step Functions examina os agentes de repetição na ordem listada na matriz. Quando o nome do erro aparece no valor do campo ErrorEquals de um agente de repetição, a máquina de estado faz repetições, conforme definido no campo Retry.

Se a execução de redriven executar novamente Estado de tarefa do fluxo de trabalho, Estado paralelo do fluxo de trabalho ou um estado de mapa em linha, para o qual você tenha definido repetições, a contagem de repetições para esses estados será redefinida como 0 para possibilitar o número máximo de tentativas em redrive. Para uma execução redriven, você pode monitorar tentativas individuais desses estados usando o console. Para obter mais informações, consulte Repetir o comportamento das execuções redriven em Reiniciar as execuções da máquina de estado com redrive no Step Functions.

Um retrier contém os seguintes campos:

Exemplos de campo de repetição

Esta seção inclui os exemplos de campo Retry a seguir.

Exemplo 1 — Tente novamente com BackoffRate

O exemplo a seguir de uma Retry faz duas tentativas de repetição. A primeira ocorre depois de uma espera de três segundos. Com base na BackoffRate especificada, o Step Functions aumenta o intervalo entre cada repetição até que o número máximo de tentativas de repetição seja atingido. No exemplo a seguir, a segunda tentativa começa depois de uma espera de três segundos após a primeira repetição.

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "IntervalSeconds": 3,
   "MaxAttempts": 2,
   "BackoffRate": 1
} ]

Exemplo 2 — Tente novamente com MaxDelaySeconds

O exemplo a seguir faz três tentativas de repetição e limita o tempo de espera resultante de BackoffRate em 5 segundos. A primeira repetição ocorre depois de uma espera de três segundos. A segunda e a terceira tentativas de repetição ocorrem após uma espera de cinco segundos após a tentativa de repetição anterior, devido ao limite máximo de tempo de espera definido por MaxDelaySeconds.

"Retry": [ {
    "ErrorEquals": [ "States.Timeout" ],
    "IntervalSeconds": 3,
    "MaxAttempts": 3,
    "BackoffRate":2,
    "MaxDelaySeconds": 5,
    "JitterStrategy": "FULL"
} ]

Sem MaxDelaySeconds, a segunda tentativa ocorreria seis segundos após a primeira tentativa, e a terceira ocorreria 12 segundos após a segunda tentativa.

Exemplo 3: repetir todos os erros, exceto States.Timeout

O nome reservado States.ALL que aparece no campo ErrorEquals de um retrier é um curinga que corresponde a qualquer nome de erro. Ele deve aparecer sozinho na matriz ErrorEquals e também no último retrier na matriz Retry. O nome States.TaskFailed também atua como um curinga e corresponde a qualquer erro, exceto States.Timeout.

O exemplo de campo Retry a seguir repete qualquer erro, exceto States.Timeout.

"Retry": [ {
   "ErrorEquals": [ "States.Timeout" ],
   "MaxAttempts": 0
}, {
   "ErrorEquals": [ "States.ALL" ]
} ]

Exemplo 4: cenário complexo de repetição

Parâmetros de um retrier em todas as visitas ao retrier no contexto de uma única execução de estado.

Considere o seguinte estado Task.

"X": {
   "Type": "Task",
   "Resource": "arn:aws:states:region:123456789012:task:X",
   "Next": "Y",
   "Retry": [ {
      "ErrorEquals": [ "ErrorA", "ErrorB" ],
      "IntervalSeconds": 1,
      "BackoffRate": 2.0,
      "MaxAttempts": 2
   }, {
      "ErrorEquals": [ "ErrorC" ],
      "IntervalSeconds": 5
   } ],
   "Catch": [ {
      "ErrorEquals": [ "States.ALL" ],
      "Next": "Z"
   } ]
}

Essa tarefa falha quatro vezes sucessivas, produzindo estes nomes de erro: ErrorA, ErrorB, ErrorC e ErrorB. O seguinte ocorre em consequência disso:

Estados de fallback

Os estados Task, Map e Parallel podem ter um campo denominado Catch. O valor desse campo deve ser uma matriz de objetos, conhecidos como catchers.

Um catcher contém os campos a seguir.

Quando um estado relata um erro e não existe nenhum campo Retry ou as repetições não conseguem resolver o erro, o Step Functions examina os coletores na ordem listada na matriz. Quando o nome do erro é exibido no valor do campo ErrorEquals de um catcher, a máquina de estado muda para o estado denominado no campo Next.

O nome reservado States.ALL que aparece em um campo ErrorEquals do catcher é um curinga que corresponde a qualquer nome de erro. Ele deve aparecer sozinho na matriz ErrorEquals e também no último catcher na matriz Catch. O nome States.TaskFailed também atua como um curinga e corresponde a qualquer erro, exceto States.Timeout.

O exemplo a seguir de um campo Catch muda para o estado denominado RecoveryState quando uma função do Lambda gera uma exceção Java não tratada. Do contrário, o campo muda para o estado EndState.

"Catch": [ {
   "ErrorEquals": [ "java.lang.Exception" ],
   "ResultPath": "$.error-info",
   "Next": "RecoveryState"
}, {
   "ErrorEquals": [ "States.ALL" ],
   "Next": "EndState"
} ]

Error output (Saída de erro)

Quando o Step Functions muda para o estado especificado em um nome de captura, o objeto normalmente contém o campo Cause. O valor desse campo é uma descrição de erro humanamente. Esse objeto é conhecido como saída de erro.

No JSONPath exemplo anterior, o primeiro coletor contém um ResultPath campo. Ele funciona de modo semelhante a um campo ResultPath em um nível superior do estado, o que resulta em duas possibilidades:

Portanto, no exemplo, o primeiro agente de captura adiciona a saída de erro à entrada como um campo chamado error-info caso ainda não haja um campo com esse nome na entrada. Depois, o agente de captura envia toda a entrada a RecoveryState. Em relação ao segundo agente de captura, a saída de erro substitui a entrada e o agente de captura só envia a saída de erro a EndState.

Para JSONPath fluxos de trabalho, se você não especificar o ResultPath campo, o padrão é$, que seleciona e substitui toda a entrada.

Quando um estado tem os campos Retry e Catch, o Step Functions usa primeiro qualquer agente de repetição apropriado. Se a política de repetição não solucionar o erro, o Step Functions aplicará a transição correspondente do agente de captura.

Causar cargas úteis e integrações de serviços

Um agente de captura exibe uma carga útil de string como saída. Ao trabalhar com integrações de serviços, como Amazon Athena AWS CodeBuild ou, talvez você queira converter Cause a string em JSON. O exemplo a seguir de um estado Pass com funções intrínsecas mostra como converter uma string Cause em JSON.

"Handle escaped JSON with JSONtoString": {
  "Type": "Pass",
  "Parameters": {
    "Cause.$": "States.StringToJson($.Cause)"
  },
  "Next": "Pass State with Pass Processing"
},

Exemplos de máquinas de estado usando Retry e Catch

As máquinas de estado definidas nos exemplos a seguir presumem que existem duas funções do Lambda: uma que sempre falha e uma que aguarda tempo suficiente para permitir que haja um tempo limite definido na máquina de estado.

Essa é uma definição de função do Lambda Node.js que sempre falha, retornando a mensagem error. Nos exemplos de máquina de estado a seguir, essa função do Lambda é denominada FailFunction. Para ter mais informações sobre como criar uma função do Lambda, consulte a seção Etapa 1: criar uma função do Lambda.

exports.handler = (event, context, callback) => {
    callback("error");
};

Essa é uma definição de função do Lambda Node.Js que permanece desativada por dez segundos. Nos exemplos de máquina de estado a seguir, essa função do Lambda é denominada sleep10.

exports.handler = (event, context, callback) => {
    setTimeout(function(){
    }, 11000);
};

Tratar uma falha usando repetição

Essa máquina de estado usa um campo Retry para tentar novamente uma função que falha e gera o nome de erro HandledError. Ela repete essa função duas vezes com um recuo exponencial entre as repetições.

{
   "Comment": "A Hello World example invoking Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["HandledError"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
      "End": true
      }
   }
}

Essa variante usa o código de erro predefinido States.TaskFailed, que corresponde a qualquer erro gerado por uma função do Lambda.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Tratar uma falha usando captura

Este exemplo usa um campo Catch. Quando uma função do Lambda gera um erro, ele é detectado e a máquina de estado muda para o estado fallback.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["HandledError"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Essa variante usa o código de erro predefinido States.TaskFailed, que corresponde a qualquer erro gerado por uma função do Lambda.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "Next": "fallback"
         } ],
      "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Tratar um tempo limite usando repetição

Essa máquina de estado usa um campo Retry para repetir um estado Task que atinge o tempo limite, com base no valor de tempo limite especificado em TimeoutSeconds. O Step Functions repete a invocação da função do Lambda nesse estado Task duas outras vezes, com recuo exponencial entre as repetições.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Retry": [ {
            "ErrorEquals": ["States.Timeout"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Tratar um tempo limite usando captura

Este exemplo usa um campo Catch. Quando ocorre um tempo limite, a máquina de estado muda para o estado fallback.

{
   "Comment": "Hello World example which invokes a AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:region:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Catch": [ {
            "ErrorEquals": ["States.Timeout"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}