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á. # Descobrir padrões de integração de serviços no Step Functions Para integrações de serviços, você pode especificar vários padrões de integração para controlar como sua máquina de estado interage com os serviços integrados da AWS : + [Resposta de solicitação](#connect-default): chame um serviço e o Step Functions avançará para o próximo estado imediatamente após receber uma resposta HTTP. + [Executar um trabalho (.sync)](#connect-sync): chame um serviço e faça o Step Functions aguardar a conclusão de uma tarefa. + [Aguardar um retorno de chamada com um token de tarefa](#connect-wait-token): chame um serviço com um token de tarefa e faça com que o Step Functions aguarde até que esse token retorne com uma carga útil. Cada um desses padrões de integração de serviços é controlado pelo modo como você cria um URI no campo `"Resource"` da sua [definição de tarefa](state-task.md). Um valor de recurso ASL no Step Functions é um nome exclusivo (URI) que está em conformidade com o [formato ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html#arns-syntax), mas normalmente não identifica um *recurso* real em sua conta. O prefixo “`arn:aws:states:`” configura um namespace que o Step Functions usa para integrações. A parte `:::` do valor indica campos `region` e `account-id` vazios, desnecessários porque ambos são inferidos da região e da conta em que o fluxo de trabalho é executado. As integrações antigas AWS Lambda são a única exceção em que o valor do recurso especifica um recurso real da função Lambda. O console do Step Functions exibirá esses recursos legados, mas não é possível criar ou editar esses recursos na interface atual, a menos que você opte por editar o código ASL diretamente. ## Suporte ao padrão de integração Os fluxos de trabalho padrão e expresso comportam as mesmas **integrações**, mas não os mesmos **padrões de integração**. + Os **fluxos de trabalho padrão** comportam integrações de *resposta a solicitações*. Alguns serviços oferecem suporte a *Run a Job (.sync)* ou *Wait for Callback (). waitForTaskToken)* e ambos em alguns casos. Consulte a tabela de integrações otimizadas a seguir para saber detalhes. + **Os fluxos de trabalho expressos** comportam somente integrações de *resposta à solicitação*. Para ajudar a decidir entre os dois tipos, consulte [Escolher o tipo de fluxo de trabalho no Step Functions](choosing-workflow-type.md). **AWS Integrações de SDK em Step Functions** | Serviço integrado | Resposta de solicitação | Executar um trabalho: *.sync* | *Aguarde o retorno de chamada -. waitForTaskToken* | | --- | --- | --- | --- | | [Mais de duzentos serviços](supported-services-awssdk.md#supported-services-awssdk-list) | Padrão e expresso | Sem compatibilidade | Standard | **Integrações otimizadas ao Step Functions** | Serviço integrado | Resposta de solicitação | Executar um trabalho: *.sync* | *Aguarde o retorno de chamada -. waitForTaskToken* | | --- | --- | --- | --- | | [Amazon API Gateway](connect-api-gateway.md) | Padrão e expresso | Sem compatibilidade | Standard | | [Amazon Athena](connect-athena.md) | Padrão e expresso | Standard | Sem compatibilidade | | [AWS Batch](connect-batch.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon Bedrock](connect-bedrock.md) | Padrão e expresso | Standard | Standard | | [AWS CodeBuild](connect-codebuild.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon DynamoDB](connect-ddb.md) | Padrão e expresso | Sem compatibilidade | Sem compatibilidade | | [Amazon ECS/Fargate](connect-ecs.md) | Padrão e expresso | Standard | Standard | | [Amazon EKS](connect-eks.md) | Padrão e expresso | Standard | Standard | | [Amazon EMR](connect-emr.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon EMR on EKS](connect-emr-eks.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon EMR Serverless](connect-emr-serverless.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon EventBridge](connect-eventbridge.md) | Padrão e expresso | Sem compatibilidade | Standard | | [AWS Glue](connect-glue.md) | Padrão e expresso | Standard | Sem compatibilidade | | [AWS Glue DataBrew](connect-databrew.md) | Padrão e expresso | Standard | Sem compatibilidade | | [AWS Lambda](connect-lambda.md) | Padrão e expresso | Sem compatibilidade | Standard | | [AWS Elemental MediaConvert](connect-mediaconvert.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon SageMaker AI](connect-sagemaker.md) | Padrão e expresso | Standard | Sem compatibilidade | | [Amazon SNS](connect-sns.md) | Padrão e expresso | Sem compatibilidade | Standard | | [Amazon SQS](connect-sqs.md) | Padrão e expresso | Sem compatibilidade | Standard | | [AWS Step Functions](connect-stepfunctions.md) | Padrão e expresso | Standard | Standard | ## Resposta de solicitação Quando você especifica um serviço na string `"Resource"` do seu estado de tarefa, e você fornece *apenas* o recurso, o Step Functions aguarda uma resposta HTTP e, então, 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 publicar um tópico do Amazon SNS. ``` "Send message to SNS": { "Type":"Task", "Resource":"arn:aws:states:::sns:publish", "Parameters": { "TopicArn":"arn:aws:sns:region:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" } ``` Este exemplo se refere à API [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) do Amazon SNS. O fluxo de trabalho seguirá para o próximo estado após a chamada da API `Publish`. **dica** Para implantar um exemplo de fluxo de trabalho que usa o padrão de integração do serviço Request Response, consulte [Integrar um serviço](getting-started.md#step-4-integrate-a-service) no tutorial de introdução deste guia ou no [módulo Request Response](https://catalog.workshops.aws/stepfunctions/integrating-services/1-request-response) no *The AWS Step Functions Workshop*. ## Executar um trabalho (.sync) Para serviços integrados, como AWS Batch o Amazon ECS, o Step Functions pode aguardar a conclusão de uma solicitação antes de passar para o próximo estado. Para que o Step Functions aguarde, especifique o campo `"Resource"` na definição do seu estado de tarefa com o sufixo `.sync` anexado depois do URI do recurso. 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" } ``` A parte `.sync` anexada ao nome do recurso da Amazon (ARN) do recurso indica que o Step Functions aguarda até que o trabalho seja concluído. 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:[Gerenciar um trabalho em lote com o AWS Batch e o Amazon SNS](batch-job-notification.md). 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 tarefa `states:startExecution.sync` do Step Functions for cancelada, ela chamará a ação da API `StopExecution` do 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 execução do IAM não tem permissão para fazer a chamada de API 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](concepts-access-cross-acct-resources.md), o Step Functions usa apenas pesquisa. Por exemplo, for`states:StartExecution.sync`, Step Functions realiza pesquisas na [DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html)API e usa sua cota atribuída. **dica** Para implantar um exemplo de fluxo de trabalho que usa o padrão de integração.sync, consulte [Run a Job (.sync)](https://catalog.workshops.aws/stepfunctions/integrating-services/2-sync-job) no *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 [Integrar serviços ao Step Functions](integrate-optimized.md). **nota** As integrações de serviços que usam os padrões `.sync` ou `.waitForTaskToken` exigem permissões adicionais do IAM. Para obter mais informações, consulte [Como o Step Functions gera políticas do IAM para serviços integrados](service-integration-iam-templates.md). 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](#connect-wait-token). Para fazer isso, passe um token de tarefa para seu trabalho e, em seguida, retorne-o usando uma chamada de API [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) ou [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html). 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](service-quotas.md#service-limits-api-state-throttling)) 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 serviços do AWS SDK e também para algumas integrações de serviços otimizados. A tarefa será pausada até o retorno de um token com uma chamada [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) ou [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html). 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](input-output-contextobject.md#contextobject-access). **nota** Um token de tarefa deve conter pelo menos um caractere e não pode exceder 1024 caracteres. Para usar `.waitForTaskToken` com uma integração do AWS SDK, a 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 de token de tarefa de retorno de chamada, consulte [Callback com token de tarefa](https://catalog.workshops.aws/stepfunctions/integrating-services/3-callback-token) no *The AWS Step Functions * Workshop. Para ver uma lista de quais serviços integrados oferecem suporte à espera de um token de tarefa (`.waitForTaskToken`), consulte [Integrar serviços ao Step Functions](integrate-optimized.md). **Topics** + [Exemplo de token de tarefa](#connect-wait-example) + [Obter um token para o objeto de contexto](#wait-token-contextobject) + [Configurar um tempo limite de pulsação para uma tarefa de espera](#wait-token-hearbeat) ### 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. O Step Functions publica uma mensagem do Amazon SQS que inclui um token de tarefa como parte da mensagem. Um sistema externo se integra ao Amazon SQS e obtém 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. ![\[Tarefa do SQS aguardando o retorno de um token de tarefa\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/wait-for-task-token.png) O campo `"Resource"` da definição da tarefa que se refere ao Amazon SQS inclui o `.waitForTaskToken` anexado no 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](#wait-token-contextobject) e obtenha o token da tarefa para a tarefa atual em uma execução em andamento. Após a conclusão, o serviço externo chama [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) ou [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) com o `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](#wait-token-hearbeat). ### Obter um token para o objeto de contexto O objeto de contexto é um objeto JSON interno com informações sobre a 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:region:account-id:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::account-id: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:region:account-id: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 `.$` ao nome do parâmetro. O trecho de código a seguir especifica os nós de entrada e do objeto de contexto em uma especificação de `"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 em andamento. No exemplo do Amazon SQS, `.waitForTaskToken` no campo `"Resource"` informa ao Step Functions para aguardar o retorno do token da tarefa. O parâmetro `"TaskToken.$": "$$.Task.Token"` transmite esse token como parte da mensagem do Amazon SQS. ``` "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 [Acessar dados de execução do objeto de contexto no Step Functions](input-output-contextobject.md) na seção [Processar entrada e saída](concepts-input-output-filtering.md) 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](service-quotas.md#service-limits-api-state-throttling)). 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`](state-task.md) 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 } } } ``` Nesta definição de máquina de estado, uma tarefa envia uma mensagem ao Amazon SQS e aguarda que um processo externo retorne a chamada 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 de tarefa com uma dessas ações de API: + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html) 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: [Criar um exemplo de padrão de retorno de chamada com o Amazon SQS, o Amazon SNS e o Lambda](callback-task-sample-sqs.md).