Utilisation TestState API pour tester un état dans Step Functions

TestStateAPIAccepte la définition d'un état unique et l'exécute. Vous pouvez tester un état sans créer de machine à états ni mettre à jour une machine à états existante.

À l'aide du TestState API, vous pouvez tester les éléments suivants :

Pour tester un état, vous pouvez également utiliser la Step Functionsconsole ou leSDK. AWS Command Line Interface (AWS CLI)

Le TestState API assume un IAM rôle qui doit contenir les IAM autorisations requises pour les ressources auxquelles votre État accède. Pour plus d'informations sur les autorisations dont un État peut avoir besoin, consultezIAMautorisations d'utilisation TestState API.

Considérations relatives à l'utilisation du TestState API

En utilisant le TestStateAPI, vous ne pouvez tester qu'un seul état à la fois. Les états que vous pouvez tester sont les suivants :

Lorsque vous utilisez le TestStateAPI, gardez à l'esprit les considérations suivantes.

Utilisation des niveaux d'inspection dans TestState API

Pour tester un état à l'aide du TestStateAPI, vous devez fournir la définition de cet état. Le test renvoie ensuite une sortie. Pour chaque État, vous pouvez spécifier la quantité de détails que vous souhaitez afficher dans les résultats des tests. Ces informations fournissent des informations supplémentaires sur l'état que vous testez. Par exemple, si vous avez utilisé des filtres de traitement des données d'entrée et de sortie, tels que InputPathou ResultPathdans un état, vous pouvez afficher les résultats intermédiaires et finaux du traitement des données.

Step Functionsfournit les niveaux suivants pour spécifier les détails que vous souhaitez afficher :

Tous ces niveaux renvoient également les nextState champs status et. statusindique le statut de l'exécution de l'état. Par exemple, SUCCEEDEDFAILED,RETRIABLE, etCAUGHT_ERROR. nextStateindique le nom du prochain état vers lequel effectuer la transition. Si vous n'avez pas défini d'état suivant dans votre définition, ce champ renvoie une valeur vide.

Pour plus d'informations sur le test d'un état à l'aide de ces niveaux d'inspection dans la Step Functions consoleAWS CLI, voir Tester un état (console) etTester un état en utilisant AWS CLI.

INFO inspectionLevel

En cas de succès du test, ce niveau indique l'état de sortie. Si le test échoue, ce niveau indique le résultat de l'erreur. Par défaut, Step Functions définit le niveau d'inspection sur INFOsi vous ne spécifiez aucun niveau.

L'image suivante montre un test de réussite du statut Pass. Le niveau d'inspection pour cet état est défini sur INFOet la sortie de cet état apparaît dans l'onglet Sortie.

L'image suivante montre un test qui a échoué pour un état de tâche lorsque le niveau d'inspection est défini sur INFO. L'onglet Sortie affiche le résultat d'erreur qui inclut le nom de l'erreur et une explication détaillée de la cause de cette erreur.

DEBUG inspectionLevel

Si le test réussit, ce niveau indique l'état de sortie et le résultat du traitement des données d'entrée et de sortie.

Si le test échoue, ce niveau indique le résultat de l'erreur. Ce niveau indique les résultats intermédiaires du traitement des données jusqu'au point de défaillance. Supposons, par exemple, que vous ayez testé un état de tâche qui appelle une Lambda fonction. Imaginez que vous ayez appliqué les Filtrage de la sortie d'état à l'aide OutputPath des flux de travail Step Functions filtres InputPathParamètres,Spécification de la sortie d'état à l'aide ResultPath des flux de travail Step Functions, et à l'état de la tâche. Supposons que l'invocation ait échoué. Dans ce cas, le DEBUG niveau affiche les résultats du traitement des données en fonction de l'application des filtres dans l'ordre suivant :

Les informations de diagnostic disponibles à ce niveau peuvent vous aider à résoudre les problèmes liés à une intégration de services ou à un flux de traitement des données d'entrée et de sortie que vous avez peut-être défini.

L'image suivante montre un test de réussite du statut Pass. Le niveau d'inspection pour cet état est défini sur DEBUG. L'onglet Traitement des entrées/sorties de l'image suivante montre le résultat de l'application de Parameterssur l'entrée prévue pour cet état.

L'image suivante montre un test qui a échoué pour un état de tâche lorsque le niveau d'inspection est défini sur DEBUG. L'onglet Traitement des entrées/sorties de l'image suivante montre le résultat du traitement des données d'entrée et de sortie pour l'état jusqu'à sa défaillance.

TRACE inspectionLevel

Step Functionsfournit le TRACEniveau pour tester une HTTPtâche. Ce niveau renvoie des informations sur la HTTP demande et la réponse renvoyées par un tiersAPI. Step Functions La réponse peut contenir des informations, telles que les en-têtes et le corps de la demande. De plus, vous pouvez visualiser l'état de sortie et le résultat du traitement des données d'entrée et de sortie à ce niveau.

Si le test échoue, ce niveau indique le résultat de l'erreur.

Ce niveau ne s'applique qu'à la HTTP tâche. Step Functionsgénère une erreur si vous utilisez ce niveau pour d'autres types d'états.

Lorsque vous définissez le niveau d'inspection sur TRACE, vous pouvez également consulter les secrets inclus dans la EventBridge connexion. Pour ce faire, vous devez définir le revealSecrets paramètre sur true dans le TestStateAPI. En outre, vous devez vous assurer que l'IAMutilisateur qui appelle le TestState API est autorisé à effectuer l'states:RevealSecretsaction. Pour un exemple de IAM politique définissant l'states:RevealSecretsautorisation, voirIAMautorisations d'utilisation TestState API. Sans cette autorisation, Step Functions renvoie une erreur de refus d'accès.

Si vous définissez le revealSecrets paramètre surfalse, Step Functions omet tous les secrets dans les données de HTTP demande et de réponse.

L'image suivante montre le test d'une HTTP tâche qui aboutit. Le niveau d'inspection pour cet état est défini sur TRACE. L'onglet HTTPDemande et réponse de l'image suivante montre le résultat de l'APIappel d'un tiers.

IAMautorisations d'utilisation TestState API

L'IAMutilisateur qui appelle le TestState API doit être autorisé à effectuer les iam:PassRole actions states:TestState et. En outre, si vous définissez le revealSecretsparamètre surtrue, vous devez vous assurer que l'IAMutilisateur est autorisé à effectuer l'states:RevealSecretsaction. Sans cette autorisation, Step Functions renvoie une erreur de refus d'accès.

Vous devez également vous assurer que votre rôle d'exécution contient les IAM autorisations requises pour les ressources auxquelles votre État accède. Pour plus d'informations sur les autorisations dont un État peut avoir besoin, consultez la section Gestion des rôles d'exécution.

L'exemple IAM de politique suivant définit les states:RevealSecrets autorisations states:TestStateiam:PassRole, et.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "states:TestState",
        "states:RevealSecrets",
        "iam:PassRole"
      ],
      "Resource": "*"
    }
  ]
}

Tester un état (console)

Vous pouvez tester un état dans la console et vérifier l'état de sortie ou le flux de traitement des données d'entrée et de sortie. Pour une HTTPtâche, vous pouvez tester la HTTP demande et la réponse brutes.

Tester un état en utilisant AWS CLI

Vous pouvez tester un état pris en charge TestStateAPIen utilisant leAWS CLI. Cela API accepte la définition d'un état et l'exécute.

Pour chaque État, vous pouvez spécifier la quantité de détails que vous souhaitez afficher dans les résultats des tests. Ces informations fournissent des informations supplémentaires sur l'exécution de l'État, notamment le résultat du traitement des données d'entrée et de sortie et les informations de HTTP demande et de réponse. Les exemples suivants présentent les différents niveaux d'inspection que vous pouvez spécifier pour TestState API. N'oubliez pas de remplacer le italicized texte contenant les informations spécifiques à votre ressource.

Cette section contient les exemples suivants qui décrivent comment vous pouvez utiliser les différents niveaux d'inspection Step Functions fournis dans AWS CLI :

Exemple 1 : Utilisation INFO inspectionLevel pour tester un état Choice

Pour tester un état à l'aide du INFO inspectionLevelin AWS CLI, exécutez la test-state commande comme indiqué dans l'exemple suivant.

aws stepfunctions test-state \
    --definition '{"Type": "Choice", "Choices": [{"Variable": "$.number", "NumericEquals": 1, "Next": "Equals 1"}, {"Variable": "$.number", "NumericEquals": 2, "Next": "Equals 2"}], "Default": "No Match"}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --input '{"number": 2}'

Cet exemple utilise un état Choice pour déterminer le chemin d'exécution de cet état en fonction de l'entrée numérique que vous fournissez. Par défaut, Step Functions définit la valeur inspectionLevel à INFO si vous ne définissez aucun niveau.

Step Functionsrenvoie le résultat suivant.

{
    "output": "{\"number\": 2}",
    "nextState": "Equals 2",
    "status": "SUCCEEDED"
}

Exemple 2 : utilisation DEBUG inspectionLevel pour déboguer le traitement des données d'entrée et de sortie dans un état Passage

Pour tester un état à l'aide du DEBUG inspectionLevelin AWS CLI, exécutez la test-state commande comme indiqué dans l'exemple suivant.

aws stepfunctions test-state \
    --definition '{"Type": "Pass", "InputPath": "$.payload", "Parameters": {"data": 1}, "ResultPath": "$.result", "OutputPath": "$.result.data", "Next": "Another State"}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --input '{"payload": {"foo": "bar"}}' \
    --inspection-level DEBUG

Cet exemple utilise un Passer l'état du flux de travail état pour montrer comment filtrer et manipuler les JSON données d'entrée à l'aide des Step Functions filtres de traitement des données d'entrée et de sortie. Cet exemple utilise les filtres suivants : InputPathParamètres,Spécification de la sortie d'état à l'aide ResultPath des flux de travail Step Functions, etFiltrage de la sortie d'état à l'aide OutputPath des flux de travail Step Functions.

Step Functionsrenvoie le résultat suivant.

{
    "output": "1",
    "inspectionData": {
        "input": "{\"payload\": {\"foo\": \"bar\"}}",
        "afterInputPath": "{\"foo\":\"bar\"}",
        "afterParameters": "{\"data\":1}",
        "afterResultSelector": "{\"data\":1}",
        "afterResultPath": "{\"payload\":{\"foo\":\"bar\"},\"result\":{\"data\":1}}"
    },
    "nextState": "Another State",
    "status": "SUCCEEDED"
}

Exemple 3 : Utiliser TRACE inspectionLevel et revealSecrets inspecter la HTTP demande envoyée à un tiers API

Pour tester une HTTPtâche à l'TRACEinspectionLevelaide du revealSecretsparamètre indiqué dans le AWS CLI, exécutez la test-state commande comme indiqué dans l'exemple suivant.

aws stepfunctions test-state \
    --definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/MyConnection/0000000-0000-0000-0000-000000000000"}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --inspection-level TRACE \
    --reveal-secrets

Cet exemple teste si la HTTP tâche appelle le tiers spécifiéAPI,https://httpbin.org/. Il affiche également les données de HTTP demande et de réponse pour l'APIappel.

{
    "output": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
    "inspectionData": {
        "input": "{}",
        "afterInputPath": "{}",
        "afterParameters": "{\"Method\":\"GET\",\"Authentication\":{\"ConnectionArn\":\"arn:aws:events:us-east-1:123456789012:connection/foo/a59c10f0-a315-4c1f-be6a-559b9a0c6250\"},\"ApiEndpoint\":\"https://httpbin.org/get\",\"Headers\":{\"definitionHeader\":\"h1\"},\"RequestBody\":{\"message\":\"Hello from Step Functions!\"},\"QueryParameters\":{\"queryParam\":\"q1\"}}",
        "result": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
        "afterResultSelector": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
        "afterResultPath": "{\"Headers\":{\"date\":[\"Tue, 21 Nov 2023 00:06:17 GMT\"],\"access-control-allow-origin\":[\"*\"],\"content-length\":[\"620\"],\"server\":[\"gunicorn/19.9.0\"],\"access-control-allow-credentials\":[\"true\"],\"content-type\":[\"application/json\"]},\"ResponseBody\":{\"args\":{\"QueryParam1\":\"QueryParamValue1\",\"queryParam\":\"q1\"},\"headers\":{\"Authorization\":\"Basic XXXXXXXX\",\"Content-Type\":\"application/json; charset=UTF-8\",\"Customheader1\":\"CustomHeaderValue1\",\"Definitionheader\":\"h1\",\"Host\":\"httpbin.org\",\"Range\":\"bytes=0-262144\",\"Transfer-Encoding\":\"chunked\",\"User-Agent\":\"Amazon|StepFunctions|HttpInvoke|us-east-1\",\"X-Amzn-Trace-Id\":\"Root=1-0000000-0000-0000-0000-000000000000\"},\"origin\":\"12.34.567.891\",\"url\":\"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"},\"StatusCode\":200,\"StatusText\":\"OK\"}",
        "request": {
            "protocol": "https",
            "method": "GET",
            "url": "https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1",
            "headers": "[definitionHeader: h1, Authorization: Basic XXXXXXXX, CustomHeader1: CustomHeaderValue1, User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1, Range: bytes=0-262144]",
            "body": "{\"message\":\"Hello from Step Functions!\",\"BodyKey1\":\"BodyValue1\"}"
        },
        "response": {
            "protocol": "https",
            "statusCode": "200",
            "statusMessage": "OK",
            "headers": "[date: Tue, 21 Nov 2023 00:06:17 GMT, content-type: application/json, content-length: 620, server: gunicorn/19.9.0, access-control-allow-origin: *, access-control-allow-credentials: true]",
            "body": "{\n  \"args\": {\n    \"QueryParam1\": \"QueryParamValue1\", \n    \"queryParam\": \"q1\"\n  }, \n  \"headers\": {\n    \"Authorization\": \"Basic XXXXXXXX\", \n    \"Content-Type\": \"application/json; charset=UTF-8\", \n    \"Customheader1\": \"CustomHeaderValue1\", \n    \"Definitionheader\": \"h1\", \n    \"Host\": \"httpbin.org\", \n    \"Range\": \"bytes=0-262144\", \n    \"Transfer-Encoding\": \"chunked\", \n    \"User-Agent\": \"Amazon|StepFunctions|HttpInvoke|us-east-1\", \n    \"X-Amzn-Trace-Id\": \"Root=1-0000000-0000-0000-0000-000000000000\"\n  }, \n  \"origin\": \"12.34.567.891\", \n  \"url\": \"https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1\"\n}\n"
        }
    },
    "status": "SUCCEEDED"
}

Exemple 4 : Utilisation de l'utilitaire jq pour filtrer et imprimer la réponse qui renvoie TestState API

Le TestState API renvoie JSON des données sous forme de chaînes échappées dans sa réponse. L'AWS CLIexemple suivant étend l'exemple 3 et utilise l'jqutilitaire pour filtrer et imprimer la HTTP réponse TestState API renvoyée dans un format lisible par l'homme. Pour plus d'informations jq et ses instructions d'installation, consultez jq on GitHub.

aws stepfunctions test-state \
    --definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/MyConnection/0000000-0000-0000-0000-000000000000"}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
    --role-arn arn:aws:iam::123456789012:role/myRole \
    --inspection-level TRACE \
    --reveal-secrets \
    | jq '.inspectionData.response.body | fromjson'

L'exemple suivant montre le résultat renvoyé dans un format lisible par l'homme.

{
  "args": {
    "QueryParam1": "QueryParamValue1",
    "queryParam": "q1"
  },
  "headers": {
    "Authorization": "Basic XXXXXXXX",
    "Content-Type": "application/json; charset=UTF-8",
    "Customheader1": "CustomHeaderValue1",
    "Definitionheader": "h1",
    "Host": "httpbin.org",
    "Range": "bytes=0-262144",
    "Transfer-Encoding": "chunked",
    "User-Agent": "Amazon|StepFunctions|HttpInvoke|us-east-1",
    "X-Amzn-Trace-Id": "Root=1-0000000-0000-0000-0000-000000000000"
  },
  "origin": "12.34.567.891",
  "url": "https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1"
}

Test et débogage du flux de données d'entrée et de sortie

Cela TestState API est utile pour tester et déboguer les données qui circulent dans votre flux de travail. Cette section fournit quelques concepts clés et explique comment les utiliser TestState à cette fin.

Concepts clés

DansStep Functions, le processus de filtrage et de manipulation JSON des données lorsqu'elles passent par les états de votre machine à états est appelé traitement des entrées et des sorties. Pour plus d'informations sur la façon dont cela fonctionne, consultez Traitement des entrées et des sorties dans Step Functions.

Tous les types d'états figurant dans le champ Amazon States Language (ASL) (Task, Parallel, Map, Pass, Wait, Choice, Succeed et Fail) partagent un ensemble de champs communs permettant de filtrer et de manipuler les JSON données qui les traversent. Ces champs sont les suivants : InputPathParamètres,ResultSelector,Spécification de la sortie d'état à l'aide ResultPath des flux de travail Step Functions, etFiltrage de la sortie d'état à l'aide OutputPath des flux de travail Step Functions. Support pour chaque domaine varie d'un État à l'autre. Au moment de l'exécution, Step Functions applique chaque champ dans un ordre spécifique. Le schéma suivant montre l'ordre dans lequel ces champs sont appliqués aux données dans un état de tâche :

La liste suivante décrit l'ordre d'application des champs de traitement d'entrée et de sortie présentés dans le diagramme.

Ces champs de traitement d'entrée et de sortie sont facultatifs. Si vous n'utilisez aucun de ces champs dans votre définition d'état, la tâche consommera l'entrée d'état brute et renverra le résultat de la tâche en tant que sortie d'état.

Utilisation TestState pour inspecter le traitement des entrées et des sorties

Lorsque vous appelez le TestState API et définissez le inspectionLevel paramètre surDEBUG, la API réponse inclut un objet appeléinspectionData. Cet objet contient des champs qui vous aident à inspecter la manière dont les données ont été filtrées ou manipulées dans l'état dans lequel elles ont été exécutées. L'exemple suivant montre l'inspectionDataobjet correspondant à un état de tâche.

"inspectionData":   {
  "input": string, 
  "afterInputPath": string, 
  "afterParameters": string, 
  "result": string, 
  "afterResultSelector": string, 
  "afterResultPath": string,
  "output": string 
}

Dans cet exemple, chaque champ contenant le after préfixe affiche les données après l'application d'un champ particulier. Par exemple, afterInputPath montre l'effet de l'application du InputPath champ pour filtrer l'entrée d'état brute. Le schéma suivant met en correspondance chaque champ de ASLdéfinition avec le champ correspondant dans l'inspectionDataobjet :

Pour des exemples d'utilisation du traitement TestState API des entrées et des sorties pour déboguer, consultez les pages suivantes :