Appelez un tiers APIs dans les flux de travail Step Functions

Une HTTP tâche est un type d'État du flux de travail des tâchesétat qui vous permet d'appeler n'importe quel public, tiersAPI, tel que Salesforce et Stripe, dans vos flux de travail. Pour appeler un tiersAPI, utilisez l'état de tâche associé à la arn:aws:states:::http:invoke ressource. Fournissez ensuite les détails de configuration du point de API terminaison APIURL, tels que 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 HTTP tâche, Workflow Studio génère automatiquement un rôle d'exécution avec des IAM politiques pour la HTTP tâche. Pour de plus amples informations, veuillez consulter Rôle pour tester les HTTP tâches dans Workflow Studio.

HTTPDéfinition de la tâche

La ASLdéfinition représente une HTTP tâche avec une http:invoke ressource. La définition de HTTP tâche suivante invoque un Stripe API 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
}

HTTPChamps de tâches

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

Authentification pour une HTTP tâche

Une HTTP tâche nécessite une EventBridge connexion qui gère de manière sécurisée les informations d'authentification d'un API fournisseur. Une connexion indique le type d'autorisation et les informations d'identification à utiliser pour autoriser un tiersAPI. L'utilisation d'une connexion vous permet d'éviter de coder en dur des secrets, tels que API des clés, 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'authentification. Vous pouvez également inclure les paramètres d'en-tête, de corps et de requête requis pour l'autorisation avec unAPI. Vous devez inclure la connexion ARN dans toute HTTP tâche qui appelle un tiersAPI.

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, consultezIAMautorisations pour exécuter une HTTP tâche.

L'image suivante montre comment Step Functions gère l'authentification pour les API appels tiers via une EventBridge connexion. La EventBridge connexion qui gère les informations d'identification d'un API fournisseur tiers. EventBridgecrée un secret Secrets Manager pour stocker les paramètres de connexion et d'autorisation sous une forme cryptée.

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

Lorsque vous appelez une HTTP tâche, vous pouvez spécifier des données dans votre EventBridge connexion et dans votre définition de HTTP tâche. Ces données incluent HeadersQueryParameters, et les RequestBody paramètres. Avant d'appeler un tiersAPI, 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 HTTP tâche échoue avec l'States.Runtimeerreur.

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

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

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

HTTPDéfinition de la tâche

{
  "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 HTTP tâche et la EventBridge connexion. Par conséquent, Step Functions remplace les valeurs de la HTTP tâche par celles de la connexion. L'extrait de code suivant montre la HTTP demande envoyée Step Functions au tiers. API

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 l'URLencodage au corps de la demande

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

Vous spécifiez URL -encoding à l'aide du Transform champ. Ce champ contient le RequestBodyEncoding champ qui indique si vous souhaitez ou non appliquer l'URLencodage aux corps de vos demandes. Lorsque vous spécifiez le RequestBodyEncoding champ, Step Functions convertit le corps de votre JSON demande en corps de form-urlencoded demande avant d'appeler le tiersAPI. Vous devez également spécifier l'content-typeen-tête application/x-www-form-urlencoded car APIs les données URL codées par acceptation 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.

IAMautorisations pour exécuter une HTTP tâche

Votre rôle d'exécution de machine à états doit disposer des secretsmanager:DescribeSecret autorisations states:InvokeHTTPEndpoint events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue,, et pour qu'une HTTP tâche puisse appeler un tiersAPI. L'exemple IAM de politique suivant accorde le minimum de privilèges requis à votre rôle de machine d'État pour appeler StripeAPIs. Cette IAM politique 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/*"
        }
    ]
}

HTTPExemple de tâche

La définition de machine à états suivante montre une HTTP tâche qui inclut les RequestBody paramètres Headers QueryParametersTransform,, et. La HTTP tâche appelle un StripeAPI, https://api.stripe.com/v1/ des factures, pour générer une facture. La HTTP tâche spécifie également URL -encoding pour le corps de la demande à l'aide de l'option INDICES encoding.

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

{
    "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: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 HTTP demande Step Functions envoyée au StripeAPI.

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

Tester une HTTP tâche

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

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

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