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

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. Você pode controlar esses AWS serviços usando três padrões de integração de serviços:

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 a configuração AWS Identity and Access Management (IAM) para serviços integrados, consulteComo o Step Functions gera IAM políticas para serviços integrados.

Suporte ao padrão de integração

Os fluxos de trabalho padrão e os fluxos de trabalho expressos oferecem suporte às mesmas integrações, mas não aos mesmos padrões de integração.

Para ajudar a decidir entre os dois tipos, consulteEscolhendo o tipo de fluxo de trabalho em Step Functions.

AWS SDKintegrações em Step Functions

Integrações otimizadas em Step Functions

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

Executar um trabalho (.sync)

Para serviços integrados, como AWS Batch e AmazonECS, Step Functions podem esperar 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 job, 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 ligar AWS Batch submitJob, 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 AWS Batch projeto 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:

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:

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.

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

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 Aguarde um retorno de chamada com o 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.

Aguarde um retorno de chamada com o 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 o AWS SDKintegrações de serviços e também a 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.

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

Para ver uma lista de quais serviços integrados oferecem suporte à espera de um token de tarefa (.waitForTaskToken), consulte Integrando serviços com Step Functions.

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.

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:

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.