Conectividad para una tarea HTTP Definición de tarea HTTP Campos de tareas HTTP Fusión EventBridge datos de conexión y definición de tareas 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 usa Workflow Studio para crear una máquina de estados que contenga una tarea HTTP, Workflow Studio generará automáticamente un rol de ejecución con IAM políticas 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 usa en 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
Fusión EventBridge datos de conexión y definición de tareas 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 acerca de IAM permisos que su máquina de estado 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 un EventBridge conexión. La EventBridge la conexión administra las credenciales de un proveedor de API HTTPS. EventBridge crea un secreto en Secrets Manager para almacenar los parámetros de conexión y autorización de forma cifrada. En el caso de las privadas APIs, EventBridge también almacena las configuraciones de conectividad de red.

Tiempos de espera para las conexiones

Las solicitudes de tareas HTTP se agotarán 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:us-east-2:123456789012: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 Functions admite la autenticación para una persona especificada ApiEndpoint mediante el recurso de conexión de Amazon EventBridge.

ConnectionArn(Obligatorio)

Especifica el EventBridge conexión ARN.

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:123456789012: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 Functions admite la conexión para una conexión especificada ApiEndpoint mediante el recurso de conexión de Amazon 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 EventBridge conexión ARN.

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:us-east-2:123456789012: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 los encabezados en EventBridge la conexión y el Headers campo de 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 EventBridge conexión.

Step Functions agrega los encabezados que especifique en el EventBridge conexión a los encabezados que especifique en la definición de la tarea HTTP. Si las mismas claves de encabezado están presentes en la definición y la conexión, Step Functions utiliza los valores correspondientes especificados en el EventBridge conexión para esos encabezados. Para obtener más información sobre cómo Step Functions realiza la fusión de datos, consulteFusión EventBridge datos de conexión y definición de tareas 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 Host encabezados User-AgentRange, y. Step Functions establece el valor del Host encabezado en función de la API a la que estés llamando. A continuación se muestra un ejemplo de estos encabezados.


User-Agent: Amazon|StepFunctions|HttpInvoke|us-east-1,
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
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 Functions Codifica 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 EventBridge conexión, Step Functions agrega estos parámetros de consulta a los parámetros de consulta que especifique en la definición de la tarea HTTP. Si las mismas claves de parámetros de consulta están presentes en la definición y la conexión, Step Functions utiliza los valores correspondientes especificados en el EventBridge conexión para esos encabezados. Para obtener más información sobre cómo Step Functions realiza la fusión de datos, consulteFusión EventBridge datos de conexión y definición de tareas 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 final 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 debes especificar el content-type encabezado comoapplication/x-www-form-urlencoded. Step Functions a continuación, codifica automáticamente la URL del 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 JsonPathsintaxis. 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.

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

Al invocar una tarea HTTP, puede especificar datos en su EventBridge conexión y tu 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 alguna clave duplicada especificada en la definición de la tarea HTTP y en el EventBridge conexión, Step Functions sobrescribe los valores de la tarea HTTP con los valores de la conexión.

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

Encabezados — Step Functions agrega cualquier encabezado que haya especificado en la conexión a los encabezados del Headers campo 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 content-type encabezado tanto en la definición de tarea HTTP como EventBridge conexión, Step Functions utiliza el valor de content-type encabezado 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 en el QueryParameters campo 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 parámetros de consulta. Por ejemplo, si especificó el parámetro de maxItems consulta tanto en la definición de la tarea HTTP como EventBridge conexión, Step Functions utiliza el valor del parámetro de maxItems consulta especificado en la conexión.
Body parameters (Parámetros del cuerpo)
- Step Functions agrega cualquier valor del cuerpo de la solicitud especificado en la conexión al cuerpo de la solicitud en el RequestBody campo de la tarea HTTP. Si hay un conflicto entre las claves del cuerpo de la solicitud, Step Functions utiliza los valores especificados en la conexión para el cuerpo de la solicitud. Por ejemplo, supongamos que especificó un Mode campo tanto en la definición RequestBody de tarea HTTP como EventBridge conexión. Step Functions utiliza el valor de Mode campo que especificó en la conexión.
- Si especificas el cuerpo de la solicitud como una cadena en lugar de un objeto JSON, y el EventBridge la conexión también contiene el cuerpo de la solicitud, Step Functions no se puede combinar el cuerpo de la solicitud especificado en estos dos 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 fusión del cuerpo de la solicitud.

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

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

EventBridge conexión


{
  "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 tarea HTTP y EventBridge conexión. Por lo 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 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|us-east-1

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

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úrate de haber creado una EventBridge conexión. 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 sustituir el italicized texto 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: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 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|us-east-1

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 AWS CLI para probar una tarea HTTP. El siguiente procedimiento describe cómo utilizar la TestState API en el Step Functions console. 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.

Pruebe el estado de una tarea HTTP en Step Functions consola

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 de detalles del estado del cuadro de diálogo, puede ver la definición del estado y un enlace a su EventBridge conexión.
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 le permite ver los datos confidenciales que EventBridge inserciones de conexión, como claves de API. La IAM la identidad de usuario que utilice para acceder a la consola debe tener permiso para realizar la states:RevealSecrets acción. Sin este permiso, Step Functions arroja un error de acceso denegado al iniciar la prueba. Para ver un ejemplo de IAM política que establece el states:RevealSecrets permiso, consulteIAM permisos 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 siguiente imagen 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.

Estos errores 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