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

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.

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.

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.

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

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

Support des modèles d'intégration

Les flux de travail standard et les flux de travail express prennent en charge les mêmes intégrations, mais pas les mêmes modèles d'intégration.

Pour vous aider à choisir entre les deux types, voirChoix du type de flux de travail dans Step Functions.

AWS Intégrations du SDK dans Step Functions

Intégrations optimisées dans Step Functions

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 réponse HTTP, puis passe à l'état suivant. Step Functions n'attendra pas qu'une tâche soit terminée.

L'exemple suivant montre comment publier une rubrique Amazon SNS.

"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 à l'API de publication d'Amazon SNS. Le flux de travail progresse à l'état suivant après l'appel de l'API Publish.

Exécuter une tâche (.sync)

Pour les services intégrés tels qu' AWS Batch Amazon ECS, 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 l'URI de la ressource.

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 and 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 :

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'action StopExecution API 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 :

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 l'DescribeExecutionAPI et utilise le quota qui vous a été attribué.

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égrer les services avec Step Functions.

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 un jeton de tâche services. Pour ce faire, transmettez un jeton de tâche à votre tâche, puis renvoyez-le à l'aide d'un appel d'SendTaskFailureAPI SendTaskSuccessou d'API. 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 un 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 services du AWS SDK, 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 à partir de l'objet Context.

Pour être utilisée dans le cadre .waitForTaskToken d'une intégration au AWS SDK, l'API que vous utilisez doit comporter un champ de paramètres dans lequel placer le jeton de tâche.

Pour afficher la liste des services intégrés qui prennent en charge l'attente d'un jeton de tâche (.waitForTaskToken), consultez Intégrer les services avec 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 message Amazon SQS qui inclut un jeton de tâche dans le message. Un système externe s'intègre à Amazon SQS et extrait 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.

Le "Resource" champ de la définition de tâche qui fait référence à Amazon SQS est .waitForTaskToken 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). L'initiale $$. indique que le chemin accède à l'objet Context et obtient le jeton de tâche pour la tâche en cours d'exécution.

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.

Obtenir un jeton à partir de l'objet Context

L'objet Context est un objet JSON 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 Context, vous devez d'abord spécifier que le paramètre sera un chemin en ajoutant un .$ au nom du paramètre. Ce qui suit spécifie les nœuds provenant à la fois de l'entrée et de l'objet Context dans une "Parameters" spécification.

"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 second cas, $$. indique que le chemin permettra d'accéder à l'objet Context et $$.Task.Token définit le paramètre sur la valeur du jeton de tâche dans l'objet Context d'une exécution en cours.

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

Pour plus d'informations sur l'objet Context, consultez Accès aux données d'exécution depuis l'objet Context dans Step Functions la Traitement des entrées et des sorties section 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 attend que le jeton de tâche soit renvoyé avec l'une de ces actions d'API :

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éation d'un exemple de modèle de rappel avec Amazon SQS, Amazon SNS et Lambda.