Llamada a API de HTTPS en flujos de trabajo de Step Functions

Una tarea HTTP es un tipo de estado Estado de un flujo de trabajo de tarea que puede usar para llamar a las API de HTTPS en sus flujos de trabajo. La API puede ser pública, por ejemplo, las aplicaciones SaaS de terceros como Stripe o Salesforce. También puede llamar a una API privada, como las aplicaciones basadas en HTTPS en una Amazon Virtual Private Cloud.

Una tarea HTTP requiere una conexión a EventBridge para la autorización y la conectividad de red.

Para llamar a una API de HTTPS, utilice el estado Task con el recurso arn:aws:states:::http:invoke. A continuación, proporcione los detalles de configuración del punto de conexión de la API, como la URL de la API, el método que desea utilizar y los detalles de conexión.

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

Conectividad de una tarea HTTP

Una tarea HTTP requiere una conexión de EventBridge, que gestiona de forma segura las credenciales de autenticación de un proveedor de API. Una conexión define el método de autorización y las credenciales que debe utilizar al conectarse a una API determinada. Si se conecta a una API privada, como una API privada en una Amazon Virtual Private Cloud (Amazon VPC), también puede usar la conexión para definir una conectividad de red punto a punto segura. El uso de una conexión ayuda a evitar secretos de codificación rígida, como claves de API, en la definición de la máquina de estado. Una conexión de EventBridge admite los esquemas de autorización de claves Basic, OAuth y API.

Cuando crea una conexión de EventBridge debe proporcionar los detalles de autenticación y de conectividad de la red. También puede incluir el encabezado, el cuerpo y los parámetros de consulta necesarios para la autorización con una API. Debe incluir el ARN de conexión en cualquier tarea HTTP que llame a una API de HTTPS.

Al crear una conexión, EventBridge crea un secreto en 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 Cuenta de AWS que tenga permiso para usar Secrets Manager. Para obtener más información sobre los permisos de IAM que su máquina de estado necesita para acceder a una conexión de EventBridge, consulte Permisos de IAM para ejecutar una tarea HTTP.

En la siguiente imagen se muestra cómo Step Functions gestiona la autenticación de las llamadas a la API de HTTPS mediante una conexión de EventBridge. La conexión EventBridge administra las credenciales de un proveedor de API de HTTPS. EventBridge crea un secreto en Secrets Manager para almacenar la conexión y los parámetros de autorización en forma cifrada. En el caso de las API privadas, EventBridge también almacena las configuraciones de conectividad de red.

Definición de tarea HTTP

La definición de ASL representa una tarea HTTP con un recurso http:invoke. La siguiente definición de tarea HTTP invoca una API de Stripe pública que devuelve una lista de todos los clientes.

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

Campos de tareas HTTP

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

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

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

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

En la siguiente lista se describe cómo combina Step Functions los datos antes de llamar a una API de HTTPS:

El siguiente ejemplo establece los campos Headers, QueryParameters y RequestBody en la tarea HTTP y en la conexión de EventBridge.

Definición de tarea 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"
        }
      }
    }
  }
}

EventBridge Conexión de

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

Aplicación de codificación URL en el cuerpo de la solicitud

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

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

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

Permisos de IAM para ejecutar una tarea HTTP

Su rol de ejecución de la máquina de estado debe tener los siguientes permisos para que una tarea HTTP pueda llamar a una API de HTTPS:

El siguiente ejemplo de política de IAM otorga los privilegios mínimos necesarios para el rol de la máquina de estado para llamar a las API de Stripe. Esta política de IAM también concede permiso al rol de máquina de estado para acceder a una conexión de EventBridge específica, incluido el secreto de esta conexión que se almacena en Secrets Manager.

Ejemplo de tarea HTTP

La siguiente definición de máquina de estado muestra una tarea HTTP que incluye los parámetros Headers, QueryParameters, Transform y RequestBody. La tarea HTTP llama a una API de Stripe, https://api.stripe.com/v1/invoices, para generar una factura. La tarea HTTP también especifica la codificación URL del cuerpo de la solicitud mediante la opción de codificación INDICES.

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

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

Recuerde reemplazar el texto en cursiva por 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: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
    }
  }
}

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 ejemplo siguiente muestra la solicitud HTTP que Step Functions envía a la API de 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

Probar una tarea HTTP

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

Respuestas a tareas HTTP no admitidas

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

Errores de conexión

Si EventBridge encuentra un problema al conectarse a la API especificada durante la ejecución del flujo de trabajo, Step Functions genera el error en el flujo de trabajo. Los errores de conexión tienen el prefijo Events.ConnectionResource..

Estos errores incluyen: