Conectividad para una tarea HTTP Definición de tarea HTTP Campos de tareas HTTP Combinación de datos de conexión de EventBridge y definición de tarea HTTP Aplicación de codificación URL en el cuerpo de la solicitud Permisos de IAM para ejecutar una tarea HTTP Ejemplo de tarea HTTP Probar una tarea HTTP Respuestas a tareas HTTP no admitidas Errores de conexión

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

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

Para la autorización y la conectividad de red, una tarea HTTP requiere una EventBridge conexión.

Para llamar a una API HTTPS, usa el estado de la tarea con el arn:aws:states:::http:invoke recurso. A continuación, proporciona los detalles de configuración del punto final de la API, como la URL de la API, el método que deseas usar y los detalles de la 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.

nota

Actualmente, HTTP Task solo admite nombres de dominio público con certificados de confianza pública para puntos de conexión HTTPS cuando se utiliza el dominio privado APIs. La tarea HTTP no admite el TLS mutuo (mTLS).

Temas

Conectividad para una tarea HTTP
Definición de tarea HTTP
Campos de tareas HTTP
Combinación de datos de conexión de EventBridge y definición de tarea HTTP
Aplicación de codificación URL en el cuerpo de la solicitud
Permisos de IAM para ejecutar una tarea HTTP
Ejemplo de tarea HTTP
Probar una tarea HTTP
Respuestas a tareas HTTP no admitidas
Errores de conexión

Conectividad para una tarea HTTP

Una tarea HTTP requiere una EventBridgeconexión que gestione 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 se utilizarán para 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 point-to-point red 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 EventBridge conexión admite los esquemas de autorización OAuth de claves básica y API.

Al crear una EventBridge conexión, proporciona sus detalles de autorización y conectividad de 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 HTTPS.

Al crear una conexió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, consultePermisos de IAM para ejecutar una tarea HTTP.

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

Tiempos de espera para las conexiones

Se agotará el tiempo de espera de las solicitudes de tareas HTTP después de 60 segundos.

Step Functions utiliza la autorización y la configuración de red en EventBridge las conexiones para las llamadas a puntos finales HTTPS.

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 pública de Stripe 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.

Resource (Obligatorio)

Para especificar un tipo de tarea, indique su ARN en el campo Resource. Para una tarea HTTP, especifique el campo Resource de la siguiente manera.


"Resource": "arn:aws:states:::http:invoke"

Parameters (Obligatorio)

Contiene los ConnectionArn campos ApiEndpointMethod, y que proporcionan información sobre la API HTTPS a la que quieres llamar. Parameterstambién contiene campos opcionales, como Headers yQueryParameters.

Puede especificar una combinación de JSON estático y JsonPathsintaxis, como Parameters en el Parameters campo. Para obtener más información, consulte Cómo pasar parámetros a una API de servicio en Step Functions.

Para especificar la EventBridge conexión, utilice el InvocationConfig campo Authentication o.

ApiEndpoint(Obligatorio)

Especifica la URL de la API HTTPS a la que quieres llamar. Para añadir parámetros de consulta a la URL, use el campo QueryParameters. En el ejemplo siguiente se muestra cómo se puede llamar a una API de Stripe para recuperar la lista de todos los clientes.


"ApiEndpoint":"https://api.stripe.com/v1/customers"

También puedes especificar una ruta de referencia mediante la JsonPathsintaxis para seleccionar el nodo JSON que contiene la URL de la API HTTPS. Por ejemplo, supongamos que quieres llamar a uno de los centros de Stripe APIs con un identificador de cliente específico. Supongamos que ha proporcionado la siguiente entrada de estado.


{
    "customer_id": "1234567890",
    "name": "John Doe"
}

Para recuperar los detalles de este ID de cliente mediante una API de Stripe, especifique el ApiEndpoint como se muestra en el ejemplo siguiente. En este ejemplo se utiliza una función intrínseca y una ruta de referencia.


"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"

En tiempo de ejecución, Step Functions resuelve el valor de ApiEndpoint de la siguiente manera.


https://api.stripe.com/v1/customers/1234567890

Method(Obligatorio)

Especifica el método HTTP que quieres usar para llamar a una API HTTPS. Puede especificar uno de estos métodos en su tarea HTTP: GET, POST, PUT, DELETE, PATCH, OPTIONS o HEAD.

Por ejemplo, para usar el método GET, especifique el campo Method de la siguiente manera.


"Method": "GET"

También puede usar una ruta de referencia para especificar el método en tiempo de ejecución. Por ejemplo, "Method.$": "$.myHTTPMethod".

Authentication(Condicional)

Debe especificar una de las dos AuthenticationInvocationConfig.

Contiene el ConnectionArn campo que especifica cómo autenticar una llamada pública a la API HTTPS. Step Functionsadmite la autenticación para una persona especificada ApiEndpoint mediante el recurso de conexión deAmazon EventBridge.

ConnectionArn(Obligatorio)

Especifica el ARN de conexión de EventBridge.

Una tarea HTTP requiere una EventBridge conexión que gestione de forma segura las credenciales de autorización de un proveedor de API. Una conexión especifica el tipo de autorización y las credenciales que se van a utilizar para autorizar una API HTTPS. 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. En una conexión, también puede especificar los parámetros Headers, QueryParameters y RequestBody.

Para obtener más información, consulte Conectividad para una tarea HTTP.

En el ejemplo siguiente se muestra cómo se puede especificar el campo Authentication en la definición de tarea HTTP.


"Authentication": {
  "ConnectionArn": "arn:aws:events:us-east-2:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
}

InvocationConfig(Condicional)

Debe especificar una de las dos AuthenticationInvocationConfig.

Contiene la configuración de autorización y conectividad de red para una llamada privada a la API HTTPS. Step Functionsadmite la conexión para una conexión especificada ApiEndpoint mediante el recurso de conexión deAmazon EventBridge. Para obtener más información, consulta Cómo conectarse a un entorno privado APIs en la Guía del EventBridge usuario de Amazon.

ConnectionArn(Obligatorio)

Especifica el ARN de conexión de EventBridge.

Una tarea HTTP requiere una EventBridge conexión, que gestione de forma segura las credenciales de autorización de un proveedor de API. Una conexión especifica el tipo de autorización y las credenciales que se van a utilizar para autorizar una API HTTPS. En el caso de la conexión privada APIs, la conexión también define una conectividad point-to-point de red 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. En una conexión, también puede especificar los parámetros Headers, QueryParameters y RequestBody.

Para obtener más información, consulte Conectividad para una tarea HTTP.

El siguiente ejemplo muestra cómo se puede especificar un InvocationConfig campo en la definición de la tarea HTTP.


"InvocationConfig": {
  "ConnectionArn": "arn:aws:events:region:account-id:connection/connection-id"
}

Headers (opcional)

Proporciona contexto y metadatos adicionales al punto de conexión de la API. Puede especificar encabezados como cadena o como matriz JSON.

Puede especificar encabezados en la conexión de EventBridge y el campo Headers en una tarea HTTP. Le recomendamos que no incluya en el campo Headers detalles de autenticación de sus proveedores de API. Le recomendamos que incluya estos detalles en su conexión de EventBridge.

Step Functions agrega los encabezados que especifique en la conexión de EventBridge a los encabezados que especifique en la definición de tarea HTTP. Si la definición y la conexión contienen las mismas claves de encabezado, Step Functions utiliza los valores correspondientes especificados en la conexión de EventBridge para esos encabezados. Para obtener más información sobre cómo Step Functions realiza combinación de datos, consulte Combinación de datos de conexión de EventBridge y definición de tarea HTTP.

El siguiente ejemplo especifica un encabezado que se incluirá en una llamada a la API HTTPS:content-type.


"Headers": {
  "content-type": "application/json"
}

También puede utilizar una ruta de referencia para especificar los encabezados en tiempo de ejecución. Por ejemplo, "Headers.$": "$.myHTTPHeaders".

Step Functions establece los encabezados User-Agent, Range y Host. Step Functions establece el valor del encabezado Host en función de la API a la que esté llamando. A continuación se muestra un ejemplo de estos encabezados.


User-Agent: Amazon|StepFunctions|HttpInvoke|region,
Range: bytes=0-262144,
Host: api.stripe.com

No puede usar los siguientes encabezados en su definición de tarea HTTP. Si utiliza estos encabezados, la tarea HTTP producirá el error States.Runtime.

A-IM
Accept-Charset
Accept-Datetime
Accept-Encoding
Autorización
Cache-Control
Connection
Content-Encoding
Contenido: MD5
Date
Expect
Forwarded
De
Host
HTTP2-Ajustes
If-Match
If-Modified-Since
If-None-Match
If-Range
If-Unmodified-Since
Max-Forwards
Origen
Pragma
Proxy-Authorization
Referer
Server
TE
Trailer
Transfer-Encoding
Upgrade
Via
Advertencia
x-forwarded-*
x-amz-*
x-amzn-*

QueryParameters (opcional)

Inserta pares de clave-valor al final de la URL de una API. Puede especificar los parámetros de consulta como una cadena, una matriz JSON o un objeto JSON. Step FunctionsCodifica automáticamente los parámetros de consulta mediante URL cuando llama a una API HTTPS.

Por ejemplo, supongamos que desea llamar a la API de Stripe para buscar clientes que realicen sus transacciones en dólares estadounidenses (USD). Supongamos que ha proporcionado los siguientes QueryParameters como entrada de estado.


"QueryParameters": {
  "currency": "usd"
}

En tiempo de ejecución, Step Functions añade los QueryParameters al URL de la API de la siguiente manera.


https://api.stripe.com/v1/customers/search?currency=usd

También puede usar una ruta de referencia para especificar los parámetros de consulta en tiempo de ejecución. Por ejemplo, "QueryParameters.$": "$.myQueryParameters".

Si especificó los parámetros de consulta en su conexión de EventBridge, Step Functions agrega estos parámetros de consulta a los parámetros de consulta que especifique en la definición de tarea HTTP. Si la definición y la conexión contienen los mismos parámetros de consulta, Step Functions utiliza los valores correspondientes especificados en la conexión de EventBridge para esos encabezados. Para obtener más información sobre cómo Step Functions realiza combinación de datos, consulte Combinación de datos de conexión de EventBridge y definición de tarea HTTP.

Transform (opcional)

Contiene los campos RequestBodyEncoding y RequestEncodingOptions. 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 acepta los cuerpos de la solicitud form-urlencoded, utilice el campo Transform para especificar codificación URL de los cuerpos de la solicitud. También debe especificar el encabezado content-type como application/x-www-form-urlencoded. A continuación, Step Functions codifica en URL automáticamente el cuerpo de la solicitud.

RequestBodyEncoding

Especifica la codificación URL del cuerpo de la solicitud. Puede especificar los valores siguientes: NONE o URL_ENCODED.

NONE: el cuerpo de la solicitud HTTP será el JSON serializado del campo RequestBody. Este es el valor predeterminado.
URL_ENCODED: el cuerpo de la solicitud HTTP serán los datos del formulario codificado en URL del campo RequestBody.

RequestEncodingOptions

Determina la opción de codificación que se utilizará para las matrices en el cuerpo de la solicitud si establece RequestBodyEncoding como URL_ENCODED.

Step Functions admite las siguientes opciones de codificación de matrices. Para obtener más información sobre estas opciones y ejemplos, consulte Aplicación de codificación URL en el cuerpo de la solicitud.

INDICES: codifica matrices utilizando el valor de índice de los elementos de la matriz. De forma predeterminada, Step Functions utiliza esta opción de codificación.
REPEAT: repite una clave para cada elemento de una matriz.
COMMAS: codifica todos los valores de una clave como una lista de valores delimitada por comas.
BRACKETS: repite una clave para cada elemento de una matriz y añade un corchete, [], a la clave para indicar que se trata de una matriz.

El siguiente ejemplo establece codificación URL para los datos del cuerpo de la solicitud. También especifica el uso de la opción de codificación COMMAS para matrices en el cuerpo de la solicitud.


"Transform": {
  "RequestBodyEncoding": "URL_ENCODED",
  "RequestEncodingOptions": {
    "ArrayFormat": "COMMAS"
  }
}

RequestBody (opcional)

Acepta los datos JSON que se proporcionan en la entrada de estado. EnRequestBody, puede especificar una combinación de JSON estático y sintaxis. JsonPath Por ejemplo, supongamos que proporciona la siguiente entrada de estado:


{
    "CardNumber": "1234567890",
    "ExpiryDate": "09/25"
}

Para utilizar estos valores de CardNumber y ExpiryDate en el cuerpo de la solicitud en tiempo de ejecución, puede especificar los siguientes datos de JSON en el cuerpo de la solicitud.


"RequestBody": {
  "Card": {
    "Number.$": "$.CardNumber",
    "Expiry.$": "$.ExpiryDate",
    "Name": "John Doe",
    "Address": "123 Any Street, Any Town, USA"
  }
}

Si la API HTTPS a la que quieres llamar requiere cuerpos de form-urlencoded solicitud, debes especificar la codificación URL para los datos del cuerpo de la solicitud. Para obtener más información, consulte Aplicación de codificación URL en el cuerpo de la solicitud.

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 HTTPS, 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 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 se combinan Step Functions los datos antes de llamar a una API HTTPS:

Encabezados: Step Functions agrega los encabezados que especificó en la conexión a los encabezados del campo Headers de la tarea HTTP. Si hay un conflicto entre las claves de los encabezados, Step Functions utiliza los valores especificados en la conexión para esos encabezados. Por ejemplo, si especificó el encabezado content-type tanto en la definición de tarea HTTP como en la conexión de EventBridge, Step Functions utiliza el valor del encabezado content-type especificado en la conexión.
Parámetros de consulta: Step Functions agrega cualquier parámetro de consulta que haya especificado en la conexión a los parámetros de consulta del campo QueryParameters de la tarea HTTP. Si hay un conflicto entre las claves de los parámetros de consulta, Step Functions utiliza los valores especificados en la conexión para esos encabezados de consulta. Por ejemplo, si especificó el parámetro de consulta maxItems tanto en la definición de tarea HTTP como en la conexión de EventBridge, Step Functions utiliza el valor del parámetro de consulta maxItems especificado en la conexión.
Body parameters (Parámetros del cuerpo)
- Step Functions agrega los valores del cuerpo de la solicitud especificados en la conexión al cuerpo de la solicitud en el campo RequestBody de la tarea HTTP. Si hay un conflicto entre las claves de los encabezados de la solicitud, Step Functions utiliza los valores especificados en la conexión para esos encabezados. Por ejemplo, supongamos que especificó un campo Mode en el RequestBody de la definición de tarea HTTP y en la conexión de EventBridge. Step Functions utiliza el valor del campo Mode especificado en la conexión.
- Si especifica el cuerpo de la solicitud como cadena en lugar de como objeto JSON y la conexión de EventBridge también contiene el cuerpo de la solicitud, Step Functions no puede combinar el cuerpo de la solicitud especificado en ambos lugares. La tarea HTTP produce el error States.Runtime.
Step Functions aplica todas las transformaciones y serializa el cuerpo de la solicitud después de completar la combinación del cuerpo de la solicitud.

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

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 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 se Step Functions envía a la 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"}

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 tu proveedor de API HTTPS requiere cuerpos de form-urlencoded solicitud, debes especificar la codificación URL de los cuerpos de solicitud. Step Functionsa continuación, codifica automáticamente la URL del cuerpo de la solicitud en función de la opción de codificación de URL que selecciones.

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 RequestBodyEncoding campo, Step Functions convierte el cuerpo de la solicitud de JSON en el cuerpo de la solicitud antes de llamar a la form-urlencoded API HTTPS. También debes especificar el content-type encabezado como tal application/x-www-form-urlencoded porque los APIs que aceptan datos codificados en URL 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.

INDICES: repite una clave para cada elemento de una matriz y añade un corchete, [], a la clave para indicar que se trata de una matriz. Este paréntesis contiene el índice del elemento de la matriz. Añadir el índice ayuda a especificar el orden de los elementos de la matriz. De forma predeterminada, Step Functions utiliza esta opción de codificación.

Por ejemplo, si el cuerpo de la solicitud contiene la siguiente matriz.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica esta matriz en la siguiente cadena.
```
array[0]=a&array[1]=b&array[2]=c&array[3]=d
```
REPEAT: repite una clave para cada elemento de una matriz.

Por ejemplo, si el cuerpo de la solicitud contiene la siguiente matriz.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica esta matriz en la siguiente cadena.
```
array=a&array=b&array=c&array=d
```
COMMAS: codifica todos los valores de una clave como una lista de valores delimitada por comas.

Por ejemplo, si el cuerpo de la solicitud contiene la siguiente matriz.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica esta matriz en la siguiente cadena.
```
array=a,b,c,d
```
BRACKETS: repite una clave para cada elemento de una matriz y añade un corchete, [], a la clave para indicar que se trata de una matriz.

Por ejemplo, si el cuerpo de la solicitud contiene la siguiente matriz.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica esta matriz en la siguiente cadena.
```
array[]=a&array[]=b&array[]=c&array[]=d
```

Permisos de IAM para ejecutar una tarea HTTP

Su función de ejecución de máquina de estado debe tener los siguientes permisos para que una tarea HTTP llame a una API HTTPS:

states:InvokeHTTPEndpoint
events:RetrieveConnectionCredentials
secretsmanager:GetSecretValue
secretsmanager:DescribeSecret

El siguiente ejemplo de política de IAM otorga los privilegios mínimos necesarios a tu rol de máquina estatal para llamar a Stripe APIs. Esta política de IAM también concede 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:account-id: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:account-id:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a"
        },
        {
            "Sid": "Statement3",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue",
                "secretsmanager:DescribeSecret"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

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/ las facturas, 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"
         },
    }
}

Recuerda sustituir el italicized texto por la información específica de tu 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

Puedes usar la TestStateAPI a través de la consola, el SDK o el AWS CLI para probar una tarea HTTP. El siguiente procedimiento describe cómo usar la TestState API en la Step Functions consola. 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.

Prueba del estado Task de HTTP en la consola de Step Functions

Abra la consola de Step Functions.
Seleccione Crear máquina de estado para empezar a crear una máquina de estado o elija una máquina de estado existente que contenga una tarea HTTP.

Consulte el paso 4 si está probando la tarea en una máquina de estado existente.
En el Modo Diseño de Workflow Studio, configure una tarea HTTP de forma visual. O elija el modo Código para copiar y pegar la definición de la máquina de estado desde su entorno de desarrollo local.
En modo Diseño, elija Probar estado en el panel de Panel del inspector de Workflow Studio.
En el cuadro de diálogo Probar estado, haga lo siguiente:
1. En Rol de ejecución, elija un rol de ejecución para probar el estado. Si no tiene un rol con permisos suficientes para una tarea HTTP, consulte Rol para probar tareas HTTP en Workflow Studio para crear un rol.
2. (Opcional) Proporcione cualquier entrada JSON que necesite el estado seleccionado para la prueba.
3. En Nivel de inspección, mantenga la selección predeterminada de INFO. Este nivel muestra el estado de la llamada a la API y la salida del estado. Resulta útil para comprobar rápidamente la respuesta de la API.
4. Seleccione Iniciar prueba.
5. Si la prueba se realiza correctamente, el resultado del estado aparece en el lado derecho del cuadro de diálogo Probar estado. Si la prueba no se realiza correctamente, aparece un error.
  
  En la pestaña Detalles del estado del cuadro de diálogo puede ver la definición del estado y un enlace a la conexión de EventBridge.
6. Cambie el Nivel de inspección a TRACE. Este nivel muestra la solicitud y la respuesta HTTP sin procesar y es útil para verificar encabezados, parámetros de consulta y otros detalles específicos de la API.
7. Seleccione la casilla Revelar secretos. En combinación con TRACE, esta configuración permite ver los datos confidenciales que inserta la conexión de EventBridge, como claves de API. La identidad del usuario de IAM que utilice para acceder a la consola debe tener permiso para realizar la acción states:RevealSecrets. Sin este permiso, Step Functions produce un error de acceso denegado al iniciar la prueba. Para ver una política de IAM de ejemplo que establece el permiso states:RevealSecrets, consulte IAMpermisos para usar la TestState API.
  
  En la siguiente imagen se muestra una prueba para una tarea HTTP que se ha realizado correctamente. El Nivel de inspección de este estado se establece en TRACE. La pestaña de solicitud y respuesta HTTP de la imagen siguiente muestra el resultado de la llamada a la API HTTPS.
8. Seleccione Iniciar prueba.
9. Si la prueba se realiza correctamente, puede ver sus detalles HTTP en la pestaña Solicitud y respuesta HTTP.

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:

La respuesta contiene un encabezado de tipo de contenido de application/octet-stream, image/*, video/* o audio/*.
La respuesta no se puede leer como una cadena válida. Por ejemplo, datos binarios o de imagen.

Errores de conexión

Si se EventBridge produce 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 llevan el prefijo. Events.ConnectionResource.

Entre estos errores se incluyen:

Events.ConnectionResource.InvalidConnectionState
Events.ConnectionResource.InvalidPrivateConnectionState
Events.ConnectionResource.AccessDenied
Events.ConnectionResource.ResourceNotFound
Events.ConnectionResource.AuthInProgress
Events.ConnectionResource.ConcurrentModification
Events.ConnectionResource.InternalError

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Patrones de integración de servicios

Paso de parámetros