Appelez des API tierces

Une tâche HTTP est un type d'État de la tâcheétat qui vous permet d'appeler n'importe quelle API publique tierce, telle que Salesforce et Stripe, dans vos flux de travail. Pour appeler une API tierce, utilisez l'état de la tâche avec la arn:aws:states:::http:invoke ressource. Fournissez ensuite les détails de configuration du point de terminaison de l'API, tels que l'URL de l'API, la méthode que vous souhaitez utiliser et les détails d'authentification.

Si vous utilisez Workflow Studio pour créer votre machine d'état contenant une tâche HTTP, Workflow Studio génère automatiquement un rôle d'exécution avec des IAM politiques pour la tâche HTTP. Pour plus d’informations, consultez Rôle pour tester les tâches HTTP dans Workflow Studio.

Définition de tâche HTTP

La définition ASL représente une tâche HTTP avec http:invoke ressource. La définition de tâche HTTP suivante invoque une API Stripe qui renvoie une liste de tous les clients.

"Call third-party API": {
  "Type": "Task",
  "Resource": "arn:aws:states:::http:invoke",
  "Parameters": {
    "ApiEndpoint": "https://api.stripe.com/v1/customers",
    "Authentication": {
      "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

Champs de tâches HTTP

Une tâche HTTP inclut les champs suivants dans sa définition.

Resource (Obligatoire)

Pour spécifier un type de tâche, indiquez son ARN dans le Resource champ. Pour une tâche HTTP, vous devez spécifier le Resource champ comme suit.

"Resource": "arn:aws:states:::http:invoke"

Parameters (Obligatoire)

Contient les ConnectionArn champs ApiEndpointMethod, et qui fournissent des informations sur l'API tierce que vous souhaitez appeler. Parameterscontient également des champs facultatifs, tels que Headers etQueryParameters.

Vous pouvez spécifier une combinaison de JSON statique et de JsonPathsyntaxe comme Parameters dans le Parameters champ. Pour plus d’informations, consultez Transmettre des paramètres à une API de service.

ApiEndpoint(Obligatoire)

Spécifie l'URL de l'API tierce que vous souhaitez appeler. Pour ajouter des paramètres de requête à l'URL, utilisez le champ. QueryParameters L'exemple suivant montre comment vous pouvez appeler une API Stripe pour récupérer la liste de tous les clients.

"ApiEndpoint":"https://api.stripe.com/v1/customers"

Vous pouvez également spécifier un chemin de référence à l'aide de la JsonPathsyntaxe permettant de sélectionner le nœud JSON contenant l'URL de l'API tierce. Supposons, par exemple, que vous souhaitiez appeler l'une des API de Stripe à l'aide d'un identifiant client spécifique. Imaginez que vous avez fourni l'entrée d'état suivante.

{
    "customer_id": "1234567890",
    "name": "John Doe"
}

Pour récupérer les détails de cet identifiant client à l'aide d'une API Stripe, spécifiez le ApiEndpoint comme indiqué dans l'exemple suivant. Cet exemple utilise une fonction intrinsèque et un chemin de référence.

"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"

Au moment de l'exécution, Step Functions résout la valeur de la manière ApiEndpoint suivante.

https://api.stripe.com/v1/customers/1234567890

Method(Obligatoire)

Spécifie la méthode HTTP que vous souhaitez utiliser pour appeler une API tierce. Vous pouvez spécifier l'une des méthodes suivantes dans votre tâche HTTP : GET, POST, PUT, DELETE, PATCH, OPTIONS ou HEAD.

Par exemple, pour utiliser la méthode GET, spécifiez le Method champ comme suit.

"Method": "GET"

Vous pouvez également utiliser un chemin de référence pour spécifier la méthode lors de l'exécution. Par exemple, "Method.$": "$.myHTTPMethod".

Authentication(Obligatoire)

Contient le ConnectionArn champ qui indique comment authentifier un appel d'API tiers. Step Functionsprend en charge l'authentification pour un élément spécifié ApiEndpoint à l'aide de la ressource de connexion deAmazon EventBridge.

ConnectionArn(Obligatoire)

Spécifie l'ARN de EventBridge connexion.

Une tâche HTTP nécessite une EventBridge connexion qui gère de manière sécurisée les informations d'authentification d'un fournisseur d'API. Une connexion indique le type d'autorisation et les informations d'identification à utiliser pour autoriser une API tierce. L'utilisation d'une connexion vous permet d'éviter de coder en dur des secrets, tels que des clés d'API, dans la définition de votre machine à états. Dans une connexion, vous pouvez également spécifier HeadersQueryParameters, et des RequestBody paramètres.

Lorsque vous créez une EventBridge connexion, vous fournissez vos informations d'authentification. Pour plus d'informations sur le fonctionnement de l'authentification pour une tâche HTTP, consultezAuthentification pour une tâche HTTP.

L'exemple suivant montre comment vous pouvez spécifier le Authentication champ dans votre définition de tâche HTTP.

"Authentication": {
  "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
}

Headers (facultatif)

Fournit un contexte et des métadonnées supplémentaires au point de terminaison de l'API. Vous pouvez spécifier les en-têtes sous forme de chaîne ou de tableau JSON.

Vous pouvez spécifier des en-têtes dans la EventBridge connexion et dans le Headers champ d'une tâche HTTP. Nous vous recommandons de ne pas inclure les informations d'authentification de vos fournisseurs d'API Headers sur le terrain. Nous vous recommandons d'inclure ces informations dans votre EventBridge connexion.

Step Functionsajoute les en-têtes que vous spécifiez dans la EventBridge connexion aux en-têtes que vous spécifiez dans la définition de la tâche HTTP. Si les mêmes clés d'en-tête sont présentes dans la définition et la connexion, Step Functions utilise les valeurs correspondantes spécifiées dans la EventBridge connexion pour ces en-têtes. Pour plus d'informations sur le Step Functions mode de fusion des données, consultezFusion des données de définition de EventBridge connexion et de tâche HTTP.

L'exemple suivant spécifie un en-tête qui sera inclus dans un appel d'API tiers :content-type.

"Headers": {
  "content-type": "application/json"
}

Vous pouvez également utiliser un chemin de référence pour spécifier les en-têtes lors de l'exécution. Par exemple, "Headers.$": "$.myHTTPHeaders".

Step Functionsdéfinit les Host en-têtes User-AgentRange, et. Step Functionsdéfinit la valeur de l'Hosten-tête en fonction de l'API que vous appelez. Voici un exemple de ces en-têtes.

User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1,
Range: bytes=0-262144,
Host: api.stripe.com

Vous ne pouvez pas utiliser les en-têtes suivants dans votre définition de tâche HTTP. Si vous utilisez ces en-têtes, la tâche HTTP échoue avec l'States.Runtimeerreur.

• A-IM

• Accept-Charset

• Accept-Datetime

• Accept-Encoding

• Cache-Control

• Connexion

• Encodage-Contenu

• Content-MD5

• Date

• Expect

• Forwarded

• De

• Host (Hôte)

• HTTP2-Settings

• If-Match

• If-Modified-Since

• If-None-Match

• If-Range

• If-Unmodified-Since

• Max-Forwards

• Origin

• Pragma

• Proxy-Authorization

• Référent

• Serveur

• TE

• Trailer

• Transfer-Encoding

• Upgrade

• Via

• Avertissement

• X-Forwarded-*

• x-amz-*

• x-amzn-*

QueryParameters (facultatif)

Insère des paires clé-valeur à la fin d'une URL d'API. Vous pouvez spécifier les paramètres de requête sous forme de chaîne, de tableau JSON ou d'objet JSON. Step Functionsencode automatiquement les paramètres de requête en URL lorsqu'il appelle une API tierce.

Supposons, par exemple, que vous souhaitiez appeler l'API Stripe pour rechercher des clients qui effectuent leurs transactions en dollars américains (USD). Imaginez que vous avez fourni ce qui suit QueryParameters comme entrée d'état.

"QueryParameters": {
  "currency": "usd"
}

Lors de l'exécution, Step Functions ajoute l'URL QueryParameters à l'API comme suit.

https://api.stripe.com/v1/customers/search?currency=usd

Vous pouvez également utiliser un chemin de référence pour spécifier les paramètres de requête lors de l'exécution. Par exemple, "QueryParameters.$": "$.myQueryParameters".

Si vous avez spécifié des paramètres de requête dans votre EventBridge connexion, Step Functions ajoutez ces paramètres de requête aux paramètres de requête que vous spécifiez dans la définition de la tâche HTTP. Si les mêmes clés de paramètres de requête sont présentes dans la définition et la connexion, Step Functions utilise les valeurs correspondantes spécifiées dans la EventBridge connexion pour ces en-têtes. Pour plus d'informations sur le Step Functions mode de fusion des données, consultezFusion des données de définition de EventBridge connexion et de tâche HTTP.

Transform (facultatif)

Contient les RequestEncodingOptions champs RequestBodyEncoding et. Par défaut, Step Functions envoie le corps de la requête sous forme de données JSON à un point de terminaison d'API.

Si votre fournisseur d'API accepte les corps de form-urlencoded requête, utilisez le Transform champ pour spécifier le codage URL des corps de requête. Vous devez également spécifier l'content-typeen-tête sous la formeapplication/x-www-form-urlencoded. Step Functionspuis encode automatiquement l'URL du corps de votre demande.

RequestBodyEncoding

Spécifie le codage URL du corps de votre demande. Vous pouvez spécifier l'une des valeurs suivantes : NONE ouURL_ENCODED.

• NONE— Le corps de la requête HTTP sera le JSON sérialisé du RequestBody champ. C’est la valeur par défaut.

• URL_ENCODED— Le corps de la requête HTTP sera constitué des données de formulaire codées en URL du RequestBody champ.

RequestEncodingOptions

Détermine l'option de codage à utiliser pour les tableaux dans le corps de votre demande si vous définissez surRequestBodyEncoding. URL_ENCODED

Step Functionsprend en charge les options de codage de tableau suivantes. Pour plus d'informations sur ces options et leurs exemples, consultezAppliquer le codage d'URL sur le corps de la demande.

• INDICES— Encode les tableaux en utilisant la valeur d'index des éléments du tableau. Step FunctionsUtilise cette option de codage par défaut.

• REPEAT— Répète une clé pour chaque élément d'un tableau.

• COMMAS— Encode toutes les valeurs d'une clé sous forme de liste de valeurs séparées par des virgules.

• BRACKETS— Répète une clé pour chaque élément d'un tableau et ajoute un crochet, [], à la clé pour indiquer qu'il s'agit d'un tableau.

L'exemple suivant définit le codage URL pour les données du corps de la demande. Il indique également d'utiliser l'option d'COMMASencodage pour les tableaux dans le corps de la requête.

"Transform": {
  "RequestBodyEncoding": "URL_ENCODED",
  "RequestEncodingOptions": {
    "ArrayFormat": "COMMAS"
  }
}

RequestBody (facultatif)

Accepte les données JSON que vous fournissez dans l'entrée d'état. DansRequestBody, vous pouvez spécifier une combinaison de JSON statique et de JsonPathsyntaxe. Supposons, par exemple, que vous fournissiez l'entrée d'état suivante :

{
    "CardNumber": "1234567890",
    "ExpiryDate": "09/25"
}

Pour utiliser ces valeurs de CardNumber et ExpiryDate dans le corps de votre demande lors de l'exécution, vous pouvez spécifier les données JSON suivantes dans le corps de votre demande.

"RequestBody": {
  "Card": {
    "Number.$": "$.CardNumber",
    "Expiry.$": "$.ExpiryDate",
    "Name": "John Doe",
    "Address": "123 Any Street, Any Town, USA"
  }
}

Si l'API tierce que vous souhaitez appeler nécessite des corps de form-urlencoded requête, vous devez spécifier le codage URL pour les données du corps de votre demande. Pour plus d’informations, consultez Appliquer le codage d'URL sur le corps de la demande.

Authentification pour une tâche HTTP

Une tâche HTTP nécessite une EventBridge connexion qui gère de manière sécurisée les informations d'authentification d'un fournisseur d'API. Une connexion indique le type d'autorisation et les informations d'identification à utiliser pour autoriser une API tierce. L'utilisation d'une connexion vous permet d'éviter de coder en dur des secrets, tels que des clés d'API, dans la définition de votre machine à états. Une EventBridge connexion prend en charge les schémas d'autorisation Basic, OAuth et API Key.

Lorsque vous créez une EventBridge connexion, vous fournissez vos informations d'authentification. Vous pouvez également inclure les paramètres d'en-tête, de corps et de requête requis pour l'autorisation auprès d'une API. Vous devez inclure l'ARN de connexion dans toute tâche HTTP qui appelle une API tierce.

Lorsque vous créez une connexion et que vous ajoutez des paramètres d'autorisation, EventBridge crée un secret dans AWS Secrets Manager. Dans ce secret, EventBridge stocke les paramètres de connexion et d'autorisation sous une forme cryptée. Pour créer ou mettre à jour correctement une connexion, vous devez utiliser une Compte AWS personne autorisée à utiliser Secrets Manager. Pour plus d'informations sur les IAM autorisations dont votre machine d'état a besoin pour accéder à une EventBridge connexion, consultezAutorisations IAM pour exécuter une tâche HTTP.

L'image suivante montre comment Step Functions gère l'authentification pour les appels d'API tiers à l'aide d'une EventBridge connexion.

Fusion des données de définition de EventBridge connexion et de tâche HTTP

Lorsque vous appelez une tâche HTTP, vous pouvez spécifier des données dans votre EventBridge connexion et dans votre définition de tâche HTTP. Ces données incluent HeadersQueryParameters, et les RequestBody paramètres. Avant d'appeler une API tierce, Step Functions fusionne le corps de la requête avec les paramètres du corps de connexion dans tous les cas, sauf si le corps de votre demande est une chaîne et que les paramètres du corps de connexion ne sont pas vides. Dans ce cas, la tâche HTTP échoue avec l'States.Runtimeerreur.

Si des clés dupliquées sont spécifiées dans la définition de la tâche HTTP et dans la EventBridge connexionStep Functions, les valeurs de la tâche HTTP sont remplacées par celles de la connexion.

La liste suivante décrit comment Step Functions fusionner les données avant d'appeler une API tierce :

• En-têtes : Step Functions ajoute tous les en-têtes que vous avez spécifiés dans la connexion aux en-têtes du Headers champ de la tâche HTTP. En cas de conflit entre les clés d'en-tête, Step Functions utilise les valeurs spécifiées dans la connexion pour ces en-têtes. Par exemple, si vous avez spécifié l'content-typeen-tête dans la définition de la tâche HTTP et dans la EventBridge connexion, Step Functions utilise la valeur content-type d'en-tête spécifiée dans la connexion.

• Paramètres de requête : Step Functions ajoute tous les paramètres de requête que vous avez spécifiés dans la connexion aux paramètres de requête dans le QueryParameters champ de la tâche HTTP. En cas de conflit entre les clés des paramètres de requête, Step Functions utilise les valeurs spécifiées dans la connexion pour ces paramètres de requête. Par exemple, si vous avez spécifié le paramètre de maxItems requête à la fois dans la définition de la tâche HTTP et dans la EventBridge connexion, Step Functions utilise la valeur du paramètre de maxItems requête spécifiée dans la connexion.

• Paramètres de corps

  • Step Functionsajoute toutes les valeurs du corps de requête spécifiées dans la connexion au corps de la demande dans le RequestBody champ de la tâche HTTP. En cas de conflit entre les clés du corps de la demande, Step Functions utilise les valeurs spécifiées dans la connexion pour le corps de la demande. Supposons, par exemple, que vous ayez spécifié un Mode champ dans la définition RequestBody de la tâche HTTP et dans la EventBridge connexion. Step Functionsutilise la valeur du Mode champ que vous avez spécifiée dans la connexion.

  • Si vous spécifiez le corps de la demande sous forme de chaîne au lieu d'un objet JSON et que la EventBridge connexion contient également le corps de la demande, Step Functions vous ne pouvez pas fusionner le corps de demande spécifié à ces deux endroits. La tâche HTTP échoue avec l'States.Runtimeerreur.

  Step Functionsapplique toutes les transformations et sérialise le corps de la demande une fois la fusion terminée.

L'exemple suivant définit les RequestBody champs HeadersQueryParameters, et dans la tâche HTTP et dans la EventBridge connexion.

Définition de tâche HTTP

{
  "Comment": "Data merging example for HTTP Task and EventBridge connection",
  "StartAt": "ListCustomers",
  "States": {
    "ListCustomers": {
      "Type": "Task",
      "Resource": "arn:aws:states:::http:invoke",
      "Parameters": {
        "Authentication": {
          "ConnectionArn": "arn:aws:events:us-east-1:123456789012:connection/Example/81210c42-8af1-456b-9c4a-6ff02fc664ac"
        },
        "ApiEndpoint": "https:/example.com/path",
        "Method": "GET",
        "Headers": {
          "Request-Id": "my_request_id",
          "Header-Param": "state_machine_header_param"
        },
        "RequestBody": {
          "Job": "Software Engineer",
          "Company": "AnyCompany",
          "BodyParam": "state_machine_body_param"
        },
        "QueryParameters": {
          "QueryParam": "state_machine_query_param"
        }
      }
    }
  }
}

Connexion EventBridge

{
  "AuthorizationType": "API_KEY",
  "AuthParameters": {
    "ApiKeyAuthParameters": {
      "ApiKeyName": "ApiKey",
      "ApiKeyValue": "key_value"
    },
    "InvocationHttpParameters": {
      "BodyParameters": [
        {
          "Key": "BodyParam",
          "Value": "connection_body_param"
        }
      ],
      "HeaderParameters": [
        {
          "Key": "Header-Param",
          "Value": "connection_header_param"
        }
      ],
      "QueryStringParameters": [
        {
          "Key": "QueryParam",
          "Value": "connection_query_param"
        }
      ]
    }
  }
}

Dans cet exemple, les clés dupliquées sont spécifiées dans la tâche et la EventBridge connexion HTTP. Par conséquent, Step Functions remplace les valeurs de la tâche HTTP par celles de la connexion. L'extrait de code suivant montre la requête HTTP envoyée à Step Functions l'API tierce.

POST /path?QueryParam=connection_query_param HTTP/1.1
Apikey: key_value
Content-Length: 79
Content-Type: application/json; charset=UTF-8
Header-Param: connection_header_param
Host: example.com
Range: bytes=0-262144
Request-Id: my_request_id
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}

Appliquer le codage d'URL sur le corps de la demande

Par défaut, Step Functions envoie le corps de la requête sous forme de données JSON à un point de terminaison d'API. Si votre fournisseur d'API tiers a besoin de corps de form-urlencoded requête, vous devez spécifier le codage URL pour les corps de requête. Step Functionsencode ensuite automatiquement le corps de la demande en fonction de l'option de codage d'URL que vous avez sélectionnée.

Vous spécifiez le codage des URL à l'aide du Transform champ. Ce champ contient le RequestBodyEncoding champ qui indique si vous souhaitez ou non appliquer un codage URL aux corps de vos demandes. Lorsque vous spécifiez le RequestBodyEncoding champ, Step Functions convertit le corps de votre demande JSON en corps de form-urlencoded demande avant d'appeler l'API tierce. Vous devez également spécifier l'content-typeen-tête, application/x-www-form-urlencoded car les API qui acceptent les données codées en URL attendent l'content-typeen-tête.

Pour coder des tableaux dans le corps de votre requête, Step Functions fournit les options de codage des tableaux suivantes.

• INDICES— Répète une clé pour chaque élément d'un tableau et ajoute un crochet, [], à la clé pour indiquer qu'il s'agit d'un tableau. Ce crochet contient l'index de l'élément du tableau. L'ajout de l'index permet de définir l'ordre des éléments du tableau. Step FunctionsUtilise cette option de codage par défaut.

  Par exemple, si le corps de votre requête contient le tableau suivant.

  {"array": ["a","b","c","d"]}

  Step Functionscode ce tableau dans la chaîne suivante.

  array[0]=a&array[1]=b&array[2]=c&array[3]=d

• REPEAT— Répète une clé pour chaque élément d'un tableau.

  Par exemple, si le corps de votre requête contient le tableau suivant.

  {"array": ["a","b","c","d"]}

  Step Functionscode ce tableau dans la chaîne suivante.

  array=a&array=b&array=c&array=d

• COMMAS— Encode toutes les valeurs d'une clé sous forme de liste de valeurs séparées par des virgules.

  Par exemple, si le corps de votre requête contient le tableau suivant.

  {"array": ["a","b","c","d"]}

  Step Functionscode ce tableau dans la chaîne suivante.

  array=a,b,c,d

• BRACKETS— Répète une clé pour chaque élément d'un tableau et ajoute un crochet, [], à la clé pour indiquer qu'il s'agit d'un tableau.

  Par exemple, si le corps de votre requête contient le tableau suivant.

  {"array": ["a","b","c","d"]}

  Step Functionscode ce tableau dans la chaîne suivante.

  array[]=a&array[]=b&array[]=c&array[]=d

Autorisations IAM pour exécuter une tâche HTTP

Votre rôle d'exécution de machine à états doit disposer des secretsmanager:DescribeSecret autorisations states:InvokeHTTPEndpoint events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue,, et pour qu'une tâche HTTP appelle une API tierce. L'exemple de politique IAM suivant accorde le minimum de privilèges requis à votre rôle de machine d'état pour appeler les API Stripe. Cette politique IAM autorise également le rôle de machine d'état à accéder à une EventBridge connexion spécifique, y compris le secret de cette connexion qui est stocké dans Secrets Manager.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": "states:InvokeHTTPEndpoint",
            "Resource": "arn:aws:states:us-east-2:123456789012:stateMachine:myStateMachine",
            "Condition": {
                "StringEquals": {
                    "states:HTTPMethod": "GET"
                },
                "StringLike": {
                    "states:HTTPEndpoint": "https://api.stripe.com/*"
                }
            }
        },
        {
            "Sid": "Statement2",
            "Effect": "Allow",
            "Action": [
                "events:RetrieveConnectionCredentials",
            ],
            "Resource": "arn:aws:events:us-east-2:123456789012:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a"
        },
        {
            "Sid": "Statement3",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

Exemple de tâche HTTP

La définition de machine à états suivante montre une tâche HTTP qui inclut les RequestBody paramètres Headers QueryParametersTransform,, et. La tâche HTTP appelle une API Stripe, https://api.stripe.com/v1/invoices, pour générer une facture. La tâche HTTP spécifie également le codage URL pour le corps de la requête à l'aide de l'option d'INDICESencodage.

Assurez-vous d'avoir créé une EventBridge connexion. L'exemple suivant montre une connexion créée à l'aide du type d'authentification BASIC.

{
    "Type": "BASIC",
    "AuthParameters": { 
        "BasicAuthParameters": { 
            "Password": "myPassword",
            "Username": "myUsername"
         },
    }
}

N'oubliez pas de remplacer le texte en italique par les informations spécifiques à votre ressource.

{
  "Comment": "A state machine that uses HTTP Task",
  "StartAt": "CreateInvoiceAPI",
  "States": {
    "CreateInvoiceAPI": {
      "Type": "Task",
      "Resource": "arn:aws:states:::http:invoke",
      "Parameters": {
        "ApiEndpoint": "https://api.stripe.com/v1/invoices",
        "Method": "POST",
        "Authentication": {
          "ConnectionArn": ""arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
        },
        "Headers": {
          "Content-Type": "application/x-www-form-urlencoded"
        },
        "RequestBody": {
          "customer.$": "$.customer_id",
          "description": "Monthly subscription",
          "metadata": {
            "order_details": "monthly report data"
          }
        },
        "Transform": {
          "RequestBodyEncoding": "URL_ENCODED",
          "RequestEncodingOptions": {
            "ArrayFormat": "INDICES"
          }
        }
      },
      "Retry": [
        {
          "ErrorEquals": [
            "States.Http.StatusCode.429",
            "States.Http.StatusCode.503",
            "States.Http.StatusCode.504",
            "States.Http.StatusCode.502"
          ],
          "BackoffRate": 2,
          "IntervalSeconds": 1,
          "MaxAttempts": 3,
          "JitterStrategy": "FULL"
        }
      ],
      "Catch": [
        {
          "ErrorEquals": [
            "States.Http.StatusCode.404",
            "States.Http.StatusCode.400",
            "States.Http.StatusCode.401",
            "States.Http.StatusCode.409",
            "States.Http.StatusCode.500"
          ],
          "Comment": "Handle all non 200 ",
          "Next": "HandleInvoiceFailure"
        }
      ],
      "End": true
    }
  }
}

Pour exécuter cette machine d'état, entrez l'ID client comme entrée, comme indiqué dans l'exemple suivant :

{
    "customer_id": "1234567890"
}

L'exemple suivant montre la requête HTTP envoyée Step Functions à l'API Stripe.

POST /v1/invoices HTTP/1.1
Authorization: Basic <base64 of username and password>
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1

description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890

Test d'une tâche HTTP

Vous pouvez utiliser l'TestStateAPI via la console, le SDK ou le AWS CLI pour tester une tâche HTTP. La procédure suivante décrit comment utiliser l' TestState API dans la Step Functions console. Vous pouvez tester de manière itérative les détails de la demande, de la réponse et de l'authentification de l'API jusqu'à ce que votre tâche HTTP fonctionne comme prévu.

Tester l'état d'une tâche HTTP dans Step Functions la console

1. Ouvrez la console Step Functions.

2. Choisissez Créer une machine à états pour commencer à créer une machine à états ou choisissez une machine à états existante contenant une tâche HTTP.

   Reportez-vous à l'étape 4 si vous testez la tâche sur une machine à états existante.

3. Dans Workflow Studio, configurez visuellement une tâche HTTP. Mode de conception Vous pouvez également choisir le mode Code pour copier-coller la définition de la machine à états depuis votre environnement de développement local.

4. En mode Design, choisissez Test state dans le Inspector panneau de Workflow Studio.

5. Dans la boîte de dialogue État du test, procédez comme suit :

   1. Pour Rôle d'exécution, choisissez un rôle d'exécution pour tester l'état. Si vous ne disposez pas d'un rôle doté d'autorisations suffisantes pour une tâche HTTP, consultez la section Rôle pour tester les tâches HTTP dans Workflow Studio pour créer un rôle.

   2. (Facultatif) Fournissez toute entrée JSON dont l'état sélectionné a besoin pour le test.

   3. Pour le niveau d'inspection, conservez la sélection par défaut INFO. Ce niveau indique le statut de l'appel d'API et l'état de sortie. Cela est utile pour vérifier rapidement la réponse de l'API.

   4. Choisissez Démarrer le test.

   5. Si le test réussit, la sortie d'état apparaît sur le côté droit de la boîte de dialogue État du test. Si le test échoue, une erreur apparaît.

      Dans l'onglet Détails de l'état de la boîte de dialogue, vous pouvez voir la définition de l'état et un lien vers votre EventBridgeconnexion.

   6. Changez le niveau d'inspection en TRACE. Ce niveau affiche la requête et la réponse HTTP brutes et est utile pour vérifier les en-têtes, les paramètres de requête et d'autres détails spécifiques à l'API.

   7. Cochez la case Révéler les secrets. Associé à TRACE, ce paramètre vous permet de voir les données sensibles insérées par la EventBridge connexion, telles que les clés d'API. L'identité IAM utilisateur que vous utilisez pour accéder à la console doit être autorisée à effectuer l'states:RevealSecretsaction. Sans cette autorisation, Step Functions génère une erreur de refus d'accès lorsque vous démarrez le test. Pour un exemple de IAM politique définissant l'states:RevealSecretsautorisation, consultezIAMautorisations d'utilisation de l' TestState API.

      L'image suivante montre un test de réussite d'une tâche HTTP. Le niveau d'inspection pour cet état est défini sur TRACE. L'onglet Requête et réponse HTTP de l'image suivante montre le résultat de l'appel d'API tiers.

      

   8. Choisissez Démarrer le test.

   9. Si le test réussit, vous pouvez voir les détails de votre protocole HTTP sous l'onglet Requête et réponse HTTP.

Réponses aux tâches HTTP non prises en charge

Une tâche HTTP échoue avec l'States.Runtimeerreur si l'une des conditions suivantes est vraie pour la réponse renvoyée :

• La réponse contient un en-tête de type contenuapplication/octet-stream, image/*video/*, ou. audio/*

• La réponse ne peut pas être lue comme une chaîne valide. Par exemple, des données binaires ou d'image.