Llama a terceros APIs en los flujos de trabajo de Step Functions

Una HTTP tarea es un tipo de Estado del flujo de trabajo de tareas estado que te permite llamar a cualquier tercero públicoAPI, como Salesforce y Stripe, en tus flujos de trabajo. Para llamar a un terceroAPI, usa el estado Tarea junto con el arn:aws:states:::http:invoke recurso. A continuación, proporcione los detalles de configuración del API punto final APIURL, como el método que desee utilizar y los detalles de autenticación.

Si usa Workflow Studio para crear una máquina de estados que contenga una HTTP tarea, Workflow Studio generará automáticamente un rol de ejecución con IAM políticas para la HTTP tarea. Para obtener más información, consulte Función para probar las HTTP tareas en Workflow Studio.

HTTPDefinición de tarea

La ASLdefinición representa una HTTP tarea con http:invoke recursos. La siguiente definición de HTTP tarea invoca un Stripe API que devuelve una lista de todos los clientes.

"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
}

HTTPCampos de tareas

Una HTTP tarea incluye los siguientes campos en su definición.

Autenticación para una tarea HTTP

Una HTTP tarea requiere una EventBridge conexión que gestione de forma segura las credenciales de autenticación de un API proveedor. Una conexión especifica el tipo de autorización y las credenciales que se van a utilizar para autorizar a un terceroAPI. El uso de una conexión le ayuda a evitar codificar secretos, como API las claves, en la definición de la máquina de estados. Una EventBridge conexión admite los esquemas de autorización Basic y API Key. OAuth

Al crear una EventBridge conexión, proporciona sus detalles de autenticación. También puede incluir el encabezado, el cuerpo y los parámetros de consulta necesarios para la autorización con unAPI. Debe incluir la conexión ARN en cualquier HTTP tarea que llame a un terceroAPI.

Al crear una conexión y añadir parámetros de autorización, EventBridge crea una entrada secreta AWS Secrets Manager. En este secreto, EventBridge almacena los parámetros de conexión y autorización de forma cifrada. Para crear o actualizar correctamente una conexión, debe usar una persona Cuenta de AWS que tenga permiso para usar Secrets Manager. Para obtener más información sobre los IAM permisos que su máquina estatal necesita para acceder a una EventBridge conexión, consulteIAMpermisos para ejecutar una tarea HTTP.

La siguiente imagen muestra cómo Step Functions gestiona la autenticación de las API llamadas de terceros mediante una EventBridge conexión. La EventBridge conexión que administra las credenciales de un API proveedor externo. EventBridgecrea un código secreto Secrets Manager para almacenar los parámetros de conexión y autorización de forma cifrada.

Combinación de datos de EventBridge conexión y definición de HTTP tareas

Al invocar una HTTP tarea, puede especificar los datos de la EventBridge conexión y de la definición de la HTTP tarea. Estos datos incluyen parámetros Headers, QueryParameters y RequestBody. Antes de llamar a un terceroAPI, Step Functions fusiona el cuerpo de la solicitud con los parámetros del cuerpo de la conexión en todos los casos, excepto si el cuerpo de la solicitud es una cadena y los parámetros del cuerpo de la conexión no están vacíos. En este caso, la HTTP tarea falla y se produce el States.Runtime error.

Si hay claves duplicadas especificadas en la definición de la HTTP tarea y en la EventBridge conexión, Step Functions sobrescribe los valores de la HTTP tarea con los valores de la conexión.

La siguiente lista describe cómo Step Functions combina los datos antes de llamar a un tercero: API

El siguiente ejemplo establece los RequestBody campos y HeadersQueryParameters, tanto en la HTTP tarea como en la EventBridge conexión.

HTTPDefinición de tarea

{
  "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"
        }
      }
    }
  }
}

Conexión de 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"
        }
      ]
    }
  }
}

En este ejemplo, las claves duplicadas se especifican en la HTTP tarea y la EventBridge conexión. Por lo tanto, Step Functions sobrescribe los valores de la HTTP tarea con los valores de la conexión. En el siguiente fragmento de código se muestra la HTTP solicitud que se Step Functions envía al tercero. 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"}

Aplicar URL -coding en el cuerpo de la solicitud

De forma predeterminada, Step Functions envía el cuerpo de la solicitud como JSON datos a un API punto final. Si su API proveedor externo requiere cuerpos de form-urlencoded solicitud, debe especificar URL -coding para los cuerpos de solicitud. Step Functionsa continuación, URL codifica automáticamente el cuerpo de la solicitud en función de la opción de URL codificación que seleccione.

La URL codificación se especifica mediante el campo. Transform Este campo contiene el RequestBodyEncoding campo que especifica si desea aplicar o no la URL codificación -coding a los cuerpos de las solicitudes. Al especificar el RequestBodyEncoding campo, Step Functions convierte el cuerpo de la JSON solicitud en el cuerpo de la form-urlencoded solicitud antes de llamar al terceroAPI. También debes especificar el content-type encabezado como tal application/x-www-form-urlencoded porque los APIs que aceptan datos URL codificados excepto el content-type encabezado.

Para codificar matrices en el cuerpo de la solicitud, Step Functions proporciona las siguientes opciones de codificación de matrices.

IAMpermisos para ejecutar una tarea HTTP

Su función de ejecución de la máquina estatal debe tener los secretsmanager:DescribeSecret permisos states:InvokeHTTPEndpoint events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue,, y para que una HTTP tarea pueda llamar a un terceroAPI. El siguiente ejemplo IAM de política otorga los privilegios mínimos necesarios a tu rol de máquina estatal para llamar a StripeAPIs. Esta IAM política también otorga permiso al rol de máquina de estado para acceder a una EventBridge conexión específica, incluido el secreto de esta conexión que está almacenado en 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/*"
        }
    ]
}

HTTPEjemplo de tarea

La siguiente definición de máquina de estados muestra una HTTP tarea que incluye los RequestBody parámetros Headers QueryParametersTransform,, y. La HTTP tarea llama a StripeAPI, https://api.stripe.com/v1/ las facturas, para generar una factura. La HTTP tarea también especifica la URL codificación -para el cuerpo de la solicitud mediante la opción de INDICES codificación.

Asegúrese de que ha creado una conexión de EventBridge. El siguiente ejemplo muestra una conexión creada con un tipo de BASIC autenticación.

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

Recuerde reemplazar el italicized texto con la información específica del recurso.

{
  "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
    }
  }
}

Para ejecutar esta máquina de estado, proporcione el ID del cliente como entrada, tal como se muestra en el ejemplo siguiente:

{
    "customer_id": "1234567890"
}

El siguiente ejemplo muestra la HTTP solicitud que se Step Functions envía a Stripe. API

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

Probar una HTTP tarea

Puede usarlo TestStateAPIa través de la consola o AWS CLI para probar una HTTP tarea. SDK El siguiente procedimiento describe cómo utilizar el TestState API en la Step Functions consola. Puede probar de forma iterativa la API solicitud, la respuesta y los detalles de autenticación hasta que la HTTP tarea funcione según lo esperado.

Respuestas de tareas no compatibles HTTP

Se produce un States.Runtime error en una HTTP tarea si se cumple una de las siguientes condiciones para la respuesta devuelta: