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á.

Tratamento de erros no Step Functions

Todos os estados, exceto Pass e Wait, podem encontrar erros de runtime. Erros podem ocorrer por diversos motivos, como nos seguintes exemplos:

Por padrão, quando um estado relata um erro, o AWS Step Functions faz com que a execução falhe totalmente.

Nomes de erro

O Step Functions identifica os erros na Amazon States Language usando strings que fazem distinção de maiúsculas e 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, esses nomes de erro não podem começar com o prefixo States..

Como uma melhor prática, verifique se o seu código de produção pode lidar com exceções do serviço do AWS Lambda (Lambda.ServiceException e Lambda.SdkClientException). Para obter mais informações, consulte Lidar com exceções do serviço Lambda.

Nova tentativa 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 retriers. 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 recuperadores na ordem listada na matriz. Quando o nome do erro aparece no valor do campo ErrorEquals de um retrier, a máquina de estado faz novas tentativas conforme definido no campo Retry.

Se a execução do seu redriven executar novamente um estado Estado da tarefa, Paralelo ou Mapa inline, para o qual você definiu novas tentativas, a contagem de novas tentativas para esses estados será redefinida para 0 a fim de permitir o número máximo de tentativas realizadas 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 Redriving execuções.

Um retrier contém os seguintes campos:

Exemplos do campo de nova tentativa

Essa seção inclui os seguintes exemplos do campo Retry.

Exemplo 1 — Nova tentativa com BackOffRate

O exemplo a seguir de uma Retry faz duas novas tentativas, com a primeira ocorrendo após uma espera de três segundos. Com base no BackoffRate especificado, o Step Functions aumenta o intervalo entre cada nova tentativa até que o número máximo de novas tentativas seja atingido. No exemplo a seguir, a segunda nova tentativa começa depois de uma espera de três segundos após a primeira nova tentativa.

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

Exemplo 2 — Nova tentativa com MaxDelaySeconds

O exemplo a seguir faz três novas tentativas e limita o tempo de espera resultante de BackoffRate para 5 segundos. A primeira nova tentativa ocorre após uma espera de três segundos. A segunda e a terceira novas tentativas ocorrem depois de uma espera de cinco segundos após a nova tentativa 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 nova tentativa ocorreria seis segundos após a primeira e a terceira ocorreria 12 segundos após a segunda.

Exemplo 3 — Nova tentativa de 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 segundo exemplo de um campo Retry faz nova tentativa em relação a qualquer erro, exceto States.Timeout.

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

Exemplo 4 — Cenário complexo de nova tentativa

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:us-east-1: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 os seguintes 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 novas tentativas não conseguem resolver o erro, o Step Functions examina os catchers 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 catch, 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.

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

Assim, para o primeiro catcher do exemplo, o catcher adicionará a saída de erro à entrada como um campo chamado error-info se ainda não houver um campo com esse nome na entrada. Em seguida, o catcher envia toda a entrada para RecoveryState. Para o segundo catcher, a saída de erro substitui a entrada e o catcher envia somente a saída de erro para EndState.

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

Cargas de causa e integrações de serviços

Um catcher retorna uma carga de string como saída. Ao trabalhar com integrações de serviços, como Amazon Athena ou AWS CodeBuild, talvez você queira converter a string Cause 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áquina de estado que usam Nova tentativa e Detecção

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 ver mais informações sobre a criação de 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 hiberna por 10 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);
};

Tratamento de falhas usando novas tentativas

Essa máquina de estado usa um campo Retry para tentar novamente uma função que falha e gera o nome de erro HandledError. Duas novas tentativas dessa função são feitas com um recuo exponencial entre as novas tentativas.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1: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": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Retry": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Tratamento de falhas usando detecção

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

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1: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": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FailFunction",
         "Catch": [ {
            "ErrorEquals": ["States.TaskFailed"],
            "Next": "fallback"
         } ],
      "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}

Tratamento de tempo limite usando novas tentativas

Essa máquina de estado usa um campo Retry para fazer uma nova tentativa do estado Task que atinge o tempo limite, com base no valor de tempo limite especificado em TimeoutSeconds. O Step Functions faz duas novas tentativas da invocação da função do Lambda nesse estado Task, com um recuo exponencial entre as novas tentativas.

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Retry": [ {
            "ErrorEquals": ["States.Timeout"],
            "IntervalSeconds": 1,
            "MaxAttempts": 2,
            "BackoffRate": 2.0
         } ],
         "End": true
      }
   }
}

Tratamento de tempo limite usando detecção

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

{
   "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
   "StartAt": "HelloWorld",
   "States": {
      "HelloWorld": {
         "Type": "Task",
         "Resource": "arn:aws:lambda:us-east-1:123456789012:function:sleep10",
         "TimeoutSeconds": 2,
         "Catch": [ {
            "ErrorEquals": ["States.Timeout"],
            "Next": "fallback"
         } ],
         "End": true
      },
      "fallback": {
         "Type": "Pass",
         "Result": "Hello, AWS Step Functions!",
         "End": true
      }
   }
}