Descubra padrões de integração de serviços em Step Functions

AWS Step Functions se integra aos serviços diretamente no Amazon States Language. É possível controlar esses serviços da AWS usando três padrões de integração de serviço:

• Chame um serviço e deixe o Step Functions avançar para o próximo estado imediatamente após receber uma HTTP resposta.

• Chame um serviço e faça o Step Functions aguardar a conclusão de uma tarefa.

• Chame um serviço com um token da tarefa e faça com que o Step Functions aguarde até que esse token retorne com uma carga.

Cada um desses padrões de integração de serviços é controlado pela forma como você cria um URI no "Resource" campo da definição de sua tarefa.

Para obter informações sobre como configurar AWS Identity and Access Management (IAM) para serviços integrados, consulteComo o Step Functions gera IAM políticas para serviços integrados.

Resposta de solicitação

Quando você especifica um serviço na "Resource" sequência de caracteres do estado da sua tarefa e fornece apenas o recurso, o Step Functions espera por uma HTTP resposta e, em seguida, avança para o próximo estado. O Step Functions não esperará a conclusão de um trabalho.

O exemplo a seguir mostra como você pode publicar um SNS tópico da Amazon.

"Send message to SNS":{
            "Type":"Task",
            "Resource":"arn:aws:states:::sns:publish",
            "Parameters":{
            "TopicArn":"arn:aws:sns:us-east-1:123456789012:myTopic",
            "Message":"Hello from Step Functions!"
            },
            "Next":"NEXT_STATE"
            }

Este exemplo faz referência ao Publish API of AmazonSNS. O fluxo de trabalho avança para o próximo estado depois de chamar o. Publish API

dica

Para implantar um exemplo de fluxo de trabalho que usa o padrão de integração do serviço de Solicitação de Resposta no seu Conta da AWS, consulte o Módulo 2 - Resposta de Solicitação do AWS Step Functions Workshop.

Executar um trabalho (.sync)

Para serviços integrados, como AWS Batch o AmazonECS, o Step Functions pode aguardar a conclusão de uma solicitação antes de avançar para o próximo estado. Para que o Step Functions espere, especifique o "Resource" campo na definição do estado da tarefa com o .sync sufixo anexado após o recurso. URI

Por exemplo, ao enviar um AWS Batch trabalho, use o "Resource" campo na definição da máquina de estado, conforme mostrado neste exemplo.

"Manage Batch task": {
            "Type": "Task",
            "Resource": "arn:aws:states:::batch:submitJob.sync",
            "Parameters": {
            "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition",
            "JobName": "testJob",
            "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue"
            },
            "Next": "NEXT_STATE"
            }

Ter a .sync parte anexada ao recurso Amazon Resource Name (ARN) significa que o Step Functions aguarda a conclusão do trabalho. Depois de chamar submitJob do AWS Batch , o fluxo de trabalho é pausado. Quando o trabalho é concluído, o Step Functions avança para o próximo estado. Para obter mais informações, consulte o projeto AWS Batch de amostra:Gerencie um trabalho em lotes com AWS Batch e Amazon SNS.

Se uma tarefa usando esse padrão de integração de serviço (.sync) for cancelada e o Step Functions não conseguir cancelar a tarefa, você poderá incorrer em cobranças adicionais do serviço integrado. Uma tarefa pode ser cancelada se:

• A execução da máquina de estado for interrompida.

• Uma ramificação diferente de um estado paralelo falha com um erro não detectado.

• Uma iteração de um estado Mapa falha com um erro não detectado.

O Step Functions fará o possível para cancelar a tarefa. Por exemplo, se uma states:startExecution.sync tarefa do Step Functions for abortada, ela chamará a StopExecution API ação Step Functions. No entanto, é possível que o Step Functions não consiga cancelar a tarefa. Os motivos para isso incluem, entre outros:

• Sua função de IAM execução não tem permissão para fazer a API chamada correspondente.

• Ocorreu uma interrupção temporária do serviço.

Quando você usa o padrão de integração do serviço .sync, o Step Functions usa uma pesquisa que consome a cota e os eventos atribuídos para monitorar o status de um trabalho. Para .sync invocações na mesma conta, o Step Functions usa EventBridge eventos e enquetes APIs que você especifica no estado. Task Para invocações .sync entre contas, o Step Functions usa apenas pesquisa. Por exemplo, forstates:StartExecution.sync, Step Functions realiza uma pesquisa no DescribeExecutionAPIe usa sua cota atribuída.

dica

Para implantar um exemplo de fluxo de trabalho que usa o padrão de integração do serviço Run a Job (.sync) no seu Conta da AWS, consulte o Módulo 3 - Executar um trabalho (.sync) do The AWS Step Functions Workshop.

Para ver uma lista de quais serviços integrados oferecem suporte à espera da conclusão de um trabalho (.sync), consulte Integrações otimizadas para o Step Functions.

nota

As integrações de serviços que usam os .waitForTaskToken padrões .sync ou exigem IAM permissões adicionais. Para obter mais informações, consulte Como o Step Functions gera IAM políticas para serviços integrados.

Em alguns casos, você pode querer que o Step Functions continue com o fluxo de trabalho antes que o trabalho seja totalmente concluído. Você pode fazer isso da mesma forma que ao usar o padrão de integração de serviços Aguardar um retorno de chamada com um token de tarefa. Para fazer isso, passe um token de tarefa para seu trabalho e, em seguida, retorne-o usando uma SendTaskFailureAPIchamada SendTaskSuccessou. O Step Functions usará os dados fornecidos nessa chamada para concluir a tarefa, parar de monitorar o trabalho e continuar o fluxo de trabalho.

Aguardar um retorno de chamada com um token de tarefa

As tarefas de retorno de chamada oferecem uma maneira de pausar um fluxo de trabalho até o retorno do token da tarefa. Uma tarefa pode precisar aguardar uma aprovação humana, integrar-se a terceiros ou chamar sistemas legados. Para tarefas como essas, você pode pausar o Step Functions até que a execução do fluxo de trabalho atinja a cota de serviço de um ano (consulte Cotas relacionadas aos controles de utilização de estado) e aguardar a conclusão de um processo ou fluxo de trabalho externo. Para essas situações, o Step Functions permite que você passe um token de tarefa para as integrações de AWS SDK serviços e também para algumas integrações de serviços otimizadas. A tarefa será pausada até o retorno de um token com uma chamada SendTaskSuccess ou SendTaskFailure.

Se um estado Task usando o token da tarefa de retorno de chamada expirar, um novo token aleatório será gerado. Você pode acessar os tokens da tarefa a partir do objeto de contexto.

nota

Um token de tarefa deve conter pelo menos um caractere e não pode exceder 1024 caracteres.

Para usar .waitForTaskToken com uma AWS SDK integração, o API que você usa deve ter um campo de parâmetro no qual colocar o token da tarefa.

nota

Você deve passar tokens de tarefas dos diretores da mesma AWS conta. Os tokens não funcionarão se você os enviar de diretores em uma AWS conta diferente.

dica

Para implantar um exemplo de fluxo de trabalho que usa um padrão de integração do serviço de token de tarefa de retorno de chamada no seu Conta da AWS, consulte o Módulo 4 - Aguarde um retorno de chamada com o token de tarefa do AWS Step Functions workshop.

Para ver uma lista de quais serviços integrados oferecem suporte à espera de um token de tarefa (.waitForTaskToken), consulte Integrações otimizadas para o Step Functions.

Tópicos

• Exemplo de token de tarefa
• Obter um token para o objeto de contexto
• Configurar um tempo limite de pulsação para uma tarefa de espera

Exemplo de token de tarefa

Neste exemplo, um fluxo de trabalho do Step Functions precisa se integrar a um microsserviço externo para realizar uma verificação de crédito como parte de um fluxo de trabalho de aprovação. Step Functions publica uma SQS mensagem da Amazon que inclui um token de tarefa como parte da mensagem. Um sistema externo se integra à Amazon SQS e retira a mensagem da fila. Quando isso é concluído, ele retorna o resultado e o token da tarefa original. O Step Functions então continua com seu fluxo de trabalho.

O "Resource" campo da definição da tarefa que faz referência à Amazon SQS inclui .waitForTaskToken anexado ao final.

"Send message to SQS": {
                "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                "Parameters": {
                "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
                "MessageBody": {
                "Message": "Hello from Step Functions!",
                "TaskToken.$": "$$.Task.Token"
                }
                },
                "Next": "NEXT_STATE"
                }

Isso informa ao Step Functions para pausar e aguardar o token da tarefa. Quando você especifica um recurso usando .waitForTaskToken, o token da tarefa pode ser acessado no campo "Parameters" da definição de estado com uma designação de caminho especial ($$.Task.Token). O primeiro $$. define que o caminho acesse o objeto de contexto e obtenha o token da tarefa para a tarefa atual em uma execução que está em andamento.

Após a conclusão, o serviço externo chama SendTaskSuccess ou SendTaskFailure com taskToken incluído. Somente depois disso, o fluxo de trabalho segue para o próximo estado.

nota

Para evitar aguardar indefinidamente caso um processo não envie o token da tarefa com SendTaskSuccess ou SendTaskFailure, consulte Configurar um tempo limite de pulsação para uma tarefa de espera.

Obter um token para o objeto de contexto

O objeto de contexto é um JSON objeto interno que contém informações sobre sua execução. Assim como a entrada de estado, ele pode ser acessado com um caminho do campo "Parameters" durante uma execução. Quando acessado dentro de uma definição de tarefa, ele inclui informações sobre a execução específica, incluindo o token da tarefa.

{
                "Execution": {
                "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName",
                "Input": {
                "key": "value"
                },
                "Name": "executionName",
                "RoleArn": "arn:aws:iam::123456789012:role...",
                "StartTime": "2019-03-26T20:14:13.192Z"
                },
                "State": {
                "EnteredTime": "2019-03-26T20:14:13.192Z",
                "Name": "Test",
                "RetryCount": 3
                },
                "StateMachine": {
                "Id": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName",
                "Name": "name"
                },
                "Task": {
                "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
                }
                }

É possível acessar o token da tarefa usando um caminho especial dentro do campo "Parameters" da sua definição de tarefa. Para acessar o objeto de contexto ou entrada, primeiro especifique que o parâmetro será um caminho anexando um .$ ao nome do parâmetro. O seguinte especifica os nós de entrada e do objeto de contexto em uma especificação "Parameters".

"Parameters": {
                "Input.$": "$",
                "TaskToken.$": "$$.Task.Token"
                },

Em ambos os casos, anexar .$ ao nome de parâmetro informa ao Step Functions para aguardar um caminho. No primeiro caso, "$" é um caminho que inclui a entrada completa. No segundo caso, $$. especifica que o caminho acessará o objeto de contexto, e $$.Task.Token define o parâmetro como o valor do token da tarefa no objeto de contexto de uma execução que está em andamento.

No SQS exemplo da Amazon, .waitForTaskToken no "Resource" campo, diz ao Step Functions que espere o token da tarefa ser retornado. O "TaskToken.$": "$$.Task.Token" parâmetro passa esse token como parte da SQS mensagem da Amazon.

"Send message to SQS": {
                "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                "Parameters": {
                "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
                "MessageBody": {
                "Message": "Hello from Step Functions!",
                "TaskToken.$": "$$.Task.Token"
                }
                },
                "Next": "NEXT_STATE"
                }

Para obter mais informações sobre o objeto de contexto, consulte Objeto de contexto na seção Processando entrada e saída deste guia.

Configurar um tempo limite de pulsação para uma tarefa de espera

Uma tarefa que aguarda um token de tarefa aguardará até que a execução atinja a cota de serviço de um ano (consulte Cotas relacionadas aos controles de utilização de estado). Para evitar execuções presas, configure um intervalo de tempo limite de pulsação na sua definição de máquina de estado. Use o campo HeartbeatSeconds para especificar o intervalo do tempo limite.

{
                "StartAt": "Push to SQS",
                "States": {
                "Push to SQS": {
                "Type": "Task",
                "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
                "HeartbeatSeconds": 600,
                "Parameters": {
                "MessageBody": { "myTaskToken.$": "$$.Task.Token" },
                "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue"
                },
                "ResultPath": "$.SQS",
                "End": true
                }
                }
                }

Nessa definição de máquina de estado, uma tarefa envia uma mensagem para a Amazon SQS e espera que um processo externo ligue de volta com o token de tarefa fornecido. O campo "HeartbeatSeconds": 600 define o intervalo de tempo limite de pulsação como 10 minutos. A tarefa aguardará o retorno do token da tarefa com uma das seguintes API ações:

• SendTaskSuccess

• SendTaskFailure

• SendTaskHeartbeat

Se a tarefa de espera não receber um token válido em até 10 minutos, ela falhará com um nome de erro States.Timeout.

Para obter mais informações, consulte o exemplo de projeto de tarefa de retorno de chamada: Crie um exemplo de padrão de retorno de chamada com Amazon SQSSNS, Amazon e Lambda.