Appelez HTTPS APIs dans les flux de travail Step Functions

Une tâche HTTP est un type d'État du flux de travail des tâchesétat qui vous permet d'appeler une API HTTPS dans vos flux de travail. L'API peut être publique, comme les applications SaaS tierces telles que Stripe ou Salesforce. Vous pouvez également appeler une API privée, telle que des applications basées sur HTTPS dans un Amazon Virtual Private Cloud.

Pour l'autorisation et la connectivité réseau, une tâche HTTP nécessite une EventBridge connexion.

Pour appeler une API HTTPS, 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 de connexion.

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 IAM politiques pour la tâche HTTP. Pour de plus amples informations, veuillez consulter Rôle pour tester les tâches HTTP dans Workflow Studio.

Connectivité pour une tâche HTTP

Une tâche HTTP nécessite une EventBridgeconnexion qui gère de manière sécurisée les informations d'authentification d'un fournisseur d'API. Une connexion définit la méthode d'autorisation et les informations d'identification à utiliser pour se connecter à une API donnée. Si vous vous connectez à une API privée, telle qu'une API privée dans un Amazon Virtual Private Cloud (Amazon VPC), vous pouvez également utiliser cette connexion pour définir une connectivité point-to-point réseau sécurisée. 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 OAuth d'autorisation Basic et API Key.

Lorsque vous créez une EventBridge connexion, vous fournissez vos informations d'autorisation et de connectivité réseau. 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 HTTPS.

Lorsque vous créez une connexion, 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 le IAM autorisations dont votre machine d'état a besoin pour accéder à une EventBridge connexion, voirAutorisations IAM pour exécuter une tâche HTTP.

L'image suivante montre comment Step Functions gère l'autorisation pour les appels d'API HTTPS à l'aide d'un EventBridge connexion. Le EventBridge La connexion gère les informations d'identification d'un fournisseur d'API HTTPS. EventBridge crée un secret dans Secrets Manager pour stocker les paramètres de connexion et d'autorisation sous forme cryptée. Dans le cas du mode privé APIs, stocke EventBridge également les configurations de connectivité réseau.

Définition de la 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 publique qui renvoie une liste de tous les clients.

"Call HTTPS 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.

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

Lorsque vous invoquez une tâche HTTP, vous pouvez spécifier des données dans votre EventBridge connexion et votre définition de tâche HTTP. Ces données incluent HeadersQueryParameters, et les RequestBody paramètres. Avant d'appeler une API HTTPS, 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 EventBridge connexion, Step Functions remplace les valeurs de la tâche HTTP par celles de la connexion.

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

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

Définition de la 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"
        }
      }
    }
  }
}

EventBridge connexion

{
  "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 HTTP et EventBridge connexion. 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 qui Step Functions envoie à l'API HTTPS.

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 HTTPS nécessite des corps de form-urlencoded requête, vous devez spécifier le codage URL pour les corps de requête. Step Functions encode 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 requête JSON en corps de form-urlencoded requête avant d'appeler l'API HTTPS. Vous devez également spécifier l'content-typeen-tête, application/x-www-form-urlencoded car ceux APIs 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 de tableau suivantes.

Autorisations IAM pour exécuter une tâche HTTP

Votre rôle d'exécution de machine à états doit disposer des autorisations suivantes pour qu'une tâche HTTP puisse appeler une API HTTPS :

L'exemple de politique IAM suivant accorde le minimum de privilèges requis à votre rôle de machine d'État pour appeler Stripe APIs. 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/ les factures, 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éé un 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 italicized texte 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 qui Step Functions envoie à 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 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.

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 :

Erreurs de connexion

Si vous EventBridge rencontrez un problème lors de la connexion à l'API spécifiée pendant l'exécution du flux de travail, Step Functions génère l'erreur dans votre flux de travail. Les erreurs de connexion sont préfixées parEvents.ConnectionResource..

Ces erreurs incluent :