Appelez les API HTTPS dans les flux de travail Step Functions

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

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

Pour appeler une API HTTPS, utilisez Tâche état avec 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 connexion détails.

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 plus d’informations, consultez Rôle pour tester les tâches HTTP dans Workflow Studio.

Connectivité pour une tâche HTTP

Une tâche HTTP nécessite un EventBridge connexion, qui gère en toute sécurité 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 la connexion pour définir une connectivité réseau point à point sécurisée. L’utilisation d’une connexion vous permet d’éviter de coder en dur des secrets, tels que des clés API, dans la définition de votre machine d’état. Un EventBridge connection prend en charge les schémas d'autorisation Basic, OAuth et API Key.

Lorsque vous créez un 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 forme cryptée. Pour créer ou mettre à jour correctement une connexion, vous devez utiliser Compte AWS qui est autorisé à utiliser Secrets Manager. Pour plus d'informations sur le IAM autorisations dont votre machine d'état a besoin pour accéder à EventBridge connexion, voir Autorisations 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 connection 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 des API privées, EventBridge stocke également les configurations de connectivité réseau.

Définition de la tâche HTTP

Le Définition de l'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:region:account-id: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 de tâches HTTP

Lorsque vous invoquez une tâche HTTP, vous pouvez spécifier des données dans EventBridge connexion et votre définition de tâche HTTP. Ces données incluent Headers, QueryParameters, et RequestBody paramètres. Avant d'appeler une API HTTPS, Step Functions fusionne le corps de la demande avec les paramètres du corps de la 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 States.Runtime erreur.

Si des clés dupliquées sont spécifiées dans la définition de la tâche HTTP et que le 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 le Headers, QueryParameters, et RequestBody champs à la fois 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:region:account-id: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 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|region

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

Postuler URL-encoding organisme sur 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 l'exige form-urlencoded organismes de demande, vous devez spécifier URL-encoding pour les organismes demandeurs. Step Functions puis automatiquement URL-encodes le corps de la demande en fonction du URL-encoding option que vous sélectionnez.

Vous spécifiez URL-encoding à l'aide du Transform champ. Ce champ contient RequestBodyEncoding champ qui indique si vous souhaitez ou non présenter une demande URL-encoding pour les organismes demandeurs. Lorsque vous spécifiez RequestBodyEncoding terrain, Step Functions convertit le corps de votre requête JSON en form-urlencoded corps de la requête avant d'appeler l'API HTTPS. Vous devez également spécifier content-type en-tête en tant que application/x-www-form-urlencoded car les API qui acceptent URL-encoded les données s'attendent à content-type en-tête.

Pour encoder 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 State Machine 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 les API Stripe. Cette politique IAM autorise également le rôle State Machine à accéder à un EventBridge connexion, y compris le secret de cette connexion qui est stocké dans Secrets Manager.

Exemple de tâche HTTP

La définition de machine à états suivante montre une tâche HTTP qui inclut le Headers, QueryParameters, Transform, et RequestBody paramètres. 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 URL-encoding pour le corps de la requête à l'aide du INDICES option d'encodage.

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 contenant 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:region:account-id: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 à états, 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|region

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

Tester une tâche HTTP

Vous pouvez utiliser TestState API via la console, le SDK ou le AWS CLI pour test une tâche HTTP. La procédure suivante décrit comment utiliser TestState API dans Step Functions console. Vous pouvez tester de manière itérative la demande, la réponse et les détails d'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 States.Runtime erreur si l'une des conditions suivantes est vraie pour la réponse renvoyée :

Erreurs de connexion

Si EventBridge rencontre 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écédées par Events.ConnectionResource..

Ces erreurs sont notamment les suivantes :