Découvrez les modèles d'intégration des services dans Step Functions - AWS Step Functions
Réponse à la requêteExécuter une tâche (.sync)Attendre un rappel avec le jeton de tâche

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Découvrez les modèles d'intégration des services dans Step Functions

AWS Step Functions s'intègre aux services directement dans l'Amazon States Language. Vous pouvez contrôler ces services AWS à l'aide de trois modèles d'intégration de service.

  • Appelez un service et laissez Step Functions passer à l'état suivant immédiatement après avoir reçu une HTTP réponse.

  • Appelez un service et demandez à Step Functions d'attendre qu'une tâche soit terminée.

  • Appelez un service avec un jeton de tâche et demandez à Step Functions d'attendre que ce jeton soit renvoyé avec une charge utile.

Chacun de ces modèles d'intégration de services est contrôlé par la façon dont vous créez un URI dans le "Resource" champ de définition de votre tâche.

Pour plus d'informations sur la configuration AWS Identity and Access Management (IAM) pour les services intégrés, consultezComment Step Functions génère IAM des politiques pour les services intégrés.

Réponse à la requête

Lorsque vous spécifiez un service dans la "Resource" chaîne de l'état de votre tâche et que vous ne fournissez que la ressource, Step Functions attend une HTTP réponse, puis passe à l'état suivant. Step Functions n'attendra pas qu'une tâche soit terminée.

L'exemple suivant montre comment publier un SNS sujet 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"
            }

Cet exemple fait référence à la publication API d'AmazonSNS. Le flux de travail passe à l'état suivant après avoir appelé le PublishAPI.

Astuce

Pour déployer un exemple de flux de travail utilisant le modèle d'intégration du service Request Response sur votre Compte AWS ordinateur, consultez le Module 2 - Demande de réponse de The AWS Step Functions Workshop.

Exécuter une tâche (.sync)

Pour les services intégrés tels qu' AWS Batch AmazonECS, Step Functions peut attendre qu'une demande soit terminée avant de passer à l'état suivant. Pour que Step Functions attende, spécifiez le "Resource" champ dans la définition de l'état de votre tâche avec le .sync suffixe ajouté après la ressource. URI

Par exemple, lorsque vous soumettez une AWS Batch tâche, utilisez le "Resource" champ dans la définition de la machine à états, comme indiqué dans cet exemple.

"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"
            }

L'ajout de la .sync partie à la ressource Amazon Resource Name (ARN) signifie que Step Functions attend que le travail soit terminé. Après l'appel de AWS Batch submitJob, le flux de travail s'interrompt. Lorsque le travail est terminé, Step Functions passe à l'état suivant. Pour plus d'informations, consultez l' AWS Batch exemple de projet :Gérez un traitement par lots avec AWS Batch et Amazon SNS.

Si une tâche utilisant ce modèle d'intégration de service (.sync) est abandonnée et que Step Functions ne parvient pas à annuler la tâche, le service intégré peut vous facturer des frais supplémentaires. Une tâche peut être abandonnée si :

  • L'exécution de la machine à états est arrêtée.

  • Une branche différente d'un état parallèle échoue avec une erreur non détectée.

  • Une itération de l'état d'une carte échoue avec une erreur non détectée.

Step Functions fera de son mieux pour annuler la tâche. Par exemple, si une states:startExecution.sync tâche Step Functions est abandonnée, elle appellera l'StopExecutionAPIaction Step Functions. Cependant, il est possible que Step Functions ne soit pas en mesure d'annuler la tâche. Les raisons en sont notamment les suivantes :

  • Votre rôle IAM d'exécution n'est pas autorisé à effectuer l'APIappel correspondant.

  • Une interruption de service temporaire s'est produite.

Lorsque vous utilisez le modèle d'intégration des .sync services, Step Functions utilise des sondages qui utilisent le quota et les événements qui vous ont été assignés pour surveiller le statut d'une tâche. Pour les .sync invocations au sein d'un même compte, Step Functions utilise les EventBridge événements et les sondages APIs que vous spécifiez dans l'Taskétat. Pour les .syncinvocations entre comptes, Step Functions utilise uniquement le sondage. Par exemple, pourstates:StartExecution.sync, Step Functions interroge DescribeExecutionAPIet utilise le quota qui vous a été attribué.

Astuce

Pour déployer un exemple de flux de travail utilisant le modèle d'intégration du service Run a Job (.sync) sur votre ordinateur Compte AWS, consultez le module 3 - Run a Job (.sync) de The AWS Step Functions Workshop.

Pour afficher la liste des services intégrés qui prennent en charge l'attente de la fin d'exécution d'une tâche (.sync), consultez Intégrations optimisées pour Step Functions.

Note

Les intégrations de services qui utilisent les .waitForTaskToken modèles .sync or nécessitent des IAM autorisations supplémentaires. Pour de plus amples informations, veuillez consulter Comment Step Functions génère IAM des politiques pour les services intégrés.

Dans certains cas, vous souhaiterez peut-être que Step Functions continue votre flux de travail avant que le travail ne soit complètement terminé. Vous pouvez y parvenir de la même manière que lorsque vous utilisez le modèle d'intégration des Attendre un rappel avec le jeton de tâche services. Pour ce faire, transmettez un jeton de tâche à votre tâche, puis renvoyez-le à l'aide d'un SendTaskFailureAPIappel SendTaskSuccessor. Step Functions utilisera les données que vous fournissez lors de cet appel pour terminer la tâche, arrêter de surveiller la tâche et poursuivre le flux de travail.

Attendre un rappel avec le jeton de tâche

Les tâches de rappel fournissent un moyen de suspendre un flux de travail jusqu'à ce qu'un jeton de tâche soit renvoyé. Une tâche peut avoir besoin d'attendre une approbation humaine, de s'intégrer à un tiers ou d'appeler un système existant. Pour de telles tâches, vous pouvez suspendre Step Functions jusqu'à ce que l'exécution du flux de travail atteigne le quota de service d'un an (voir,Quotas liés à l'étranglement de l'État), et attendre qu'un processus ou un flux de travail externe soit terminé. Dans ces situations, Step Functions vous permet de transmettre un jeton de tâche aux intégrations de AWS SDK services, ainsi qu'à certaines intégrations de services optimisées. La tâche s'arrête jusqu'à ce qu'elle reçoive à nouveau le jeton de tâche avec un appel SendTaskSuccess ou SendTaskFailure.

Si un Task état utilisant le jeton de tâche de rappel expire, un nouveau jeton aléatoire est généré. Vous pouvez accéder aux jetons de tâche depuis l'objet de contexte.

Note

Un jeton de tâche doit contenir au moins un caractère et ne peut pas dépasser 1 024 caractères.

Pour être utilisé .waitForTaskToken dans le AWS SDK cadre d'une intégration, API vous devez disposer d'un champ de paramètre dans lequel placer le jeton de tâche.

Note

Vous devez transmettre les jetons de tâches des principaux d'un même AWS compte. Les jetons ne fonctionneront pas si vous les envoyez depuis un compte principal sur un autre AWS compte.

Astuce

Pour déployer un exemple de flux de travail utilisant un modèle d'intégration du service de jeton de tâche de rappel sur votre Compte AWS ordinateur, consultez le module 4 - Attendre un rappel avec le jeton de tâche de The AWS Step Functions Workshop.

Pour afficher la liste des services intégrés qui prennent en charge l'attente d'un jeton de tâche (.waitForTaskToken), consultez Intégrations optimisées pour Step Functions.

Exemple de jeton de tâche

Dans cet exemple, un flux de travail Step Functions doit être intégré à un microservice externe pour effectuer une vérification de solvabilité dans le cadre d'un flux de travail d'approbation. Step Functions publie un SQS message Amazon qui inclut un jeton de tâche dans le message. Un système externe s'intègre à Amazon SQS et retire le message de la file d'attente. Lorsque cela est terminé, il renvoie le résultat et le jeton de tâche d'origine. Step Functions poursuit ensuite son flux de travail.

SQStâche en attente du renvoi d'un jeton de tâche

Le "Resource" champ de la définition de tâche qui fait référence à SQS Amazon .waitForTaskToken est ajouté à la fin.

"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"
                }

Cela indique à Step Functions de faire une pause et d'attendre le jeton de tâche. Lorsque vous spécifiez une ressource à l'aide de .waitForTaskToken, le jeton de tâche est accessible dans le champ "Parameters" de votre définition d'état avec une désignation de chemin spécifique ($$.Task.Token). La première $$. désigne que le chemin accède à l'objet de contexte, et obtient le jeton de la tâche pour la tâche courante d'une exécution en cours.

Une fois qu'il a terminé, le service externe appelle SendTaskSuccess ou SendTaskFailure avec taskToken inclus. Seul alors le flux de travail continue à l'état suivant.

Note

Pour éviter d'attendre indéfiniment si un processus échoue à envoyer le jeton de tâche en même temps que SendTaskSuccess ou SendTaskFailure, veuillez consulter Configurer un délai de pulsation pour une tâche en attente.

Obtenir un jeton à partir de l'objet de contexte

L'objet de contexte est un JSON objet interne qui contient des informations sur votre exécution. Comme entrée d'état, il peut être consulté avec un chemin d'accès à partir du champ "Parameters" pendant une exécution. En cas d'accès à partir d'une définition de tâche, l'objet comprend des informations sur l'exécution spécifique, y compris le jeton de tâche.

{
                "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"
                }
                }

Vous pouvez accéder au jeton de tâche à l'aide d'un chemin d'accès spécial depuis l'intérieur du champ "Parameters" de votre définition de tâche. Pour accéder à l'entrée ou l'objet de contexte, vous devez d'abord spécifier que le paramètre sera un chemin d'accès en ajoutant un .$ au nom de paramètre. La commande suivante spécifie les nœuds des données d'entrée et de l'objet de contexte dans une spécification "Parameters".

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

Dans les deux cas, l'ajout au nom du paramètre indique .$ à Step Functions de s'attendre à un chemin. Dans le premier cas, "$" est un chemin d'accès qui inclut l'ensemble de l'entrée. Dans le deuxième cas, $$. spécifie que le chemin doit accéder à l'objet de contexte et $$.Task.Token définit le paramètre avec la valeur du jeton de tâche dans l'objet de contexte d'une exécution en cours.

Dans l'SQSexemple d'Amazon, .waitForTaskToken le "Resource" champ indique à Step Functions d'attendre que le jeton de tâche soit renvoyé. Le "TaskToken.$": "$$.Task.Token" paramètre transmet ce jeton dans le SQS message 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"
                }

Pour plus d'informations sur l'objet de contexte, consultez Objet Contexte dans la section Traitement des entrées et des sorties de ce guide.

Configurer un délai de pulsation pour une tâche en attente

Une tâche qui attend un jeton de tâche attendra jusqu'à ce que l'exécution ait atteint le quota d'une année de service (consultez, Quotas liés à l'étranglement de l'État). Pour éviter les exécutions bloquées, vous pouvez configurer un intervalle de pulsation dans la définition de votre machine d'état. Utilisez le champ HeartbeatSeconds pour spécifier l'intervalle de délai d'expiration.

{
                "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
                }
                }
                }

Dans cette définition de machine à états, une tâche envoie un message à Amazon SQS et attend qu'un processus externe le rappelle avec le jeton de tâche fourni. Le champ "HeartbeatSeconds": 600 définit l'intervalle de pulsation sur 10 minutes. La tâche attendra que le jeton de tâche soit renvoyé avec l'une des API actions suivantes :

Si la tâche d'attente ne reçoit pas un jeton de tâche valide au sein de cette période de 10 minutes, la tâche échoue avec un nom d'erreur States.Timeout.

Pour de plus amples informations, veuillez consulter l'exemple de projet de tâche de rappel Créez un exemple de modèle de rappel avec Amazon SQSSNS, Amazon et Lambda.