Conectividade para uma tarefa HTTP Definição da tarefa HTTP Campos da tarefa HTTP Mesclar EventBridge conexão e dados de definição de tarefas HTTP Aplicar a codificação em URL no corpo da solicitação Permissões do IAM para executar uma tarefa HTTP Exemplo de tarefa HTTP Testar uma tarefa HTTP Respostas da tarefa HTTP não compatíveis Erros de conexão

Chame HTTPS APIs nos fluxos de trabalho do Step Functions

Uma tarefa HTTP é um tipo de Estado de tarefa do fluxo de trabalho estado que permite chamar uma API HTTPS em seus fluxos de trabalho. A API pode ser pública, como aplicativos SaaS de terceiros, como Stripe ou Salesforce. Você também pode chamar uma API privada, como aplicativos baseados em HTTPS em uma Amazon Virtual Private Cloud.

Para autorização e conectividade de rede, uma tarefa HTTP requer uma EventBridge conexão.

Para chamar uma API HTTPS, use o estado da tarefa com o arn:aws:states:::http:invoke recurso. Em seguida, forneça os detalhes da configuração do endpoint da API, como o URL da API, o método que você deseja usar e os detalhes da conexão.

Se você usa o Workflow Studio para criar sua máquina de estado que contém uma tarefa HTTP, o Workflow Studio gera automaticamente uma função de execução com IAM políticas para a tarefa HTTP. Para obter mais informações, consulte Perfil para testar tarefas HTTP no Workflow Studio.

nota

Atualmente, o HTTP Task só oferece suporte a nomes de domínio público com certificados publicamente confiáveis para endpoints HTTPS ao usar o modo privado APIs. A tarefa HTTP não oferece suporte a TLS mútuo (mTLS).

Tópicos

Conectividade para uma tarefa HTTP
Definição da tarefa HTTP
Campos da tarefa HTTP
Mesclar EventBridge conexão e dados de definição de tarefas HTTP
Aplicar a codificação em URL no corpo da solicitação
Permissões do IAM para executar uma tarefa HTTP
Exemplo de tarefa HTTP
Testar uma tarefa HTTP
Respostas da tarefa HTTP não compatíveis
Erros de conexão

Conectividade para uma tarefa HTTP

Uma tarefa HTTP requer uma EventBridgeconexão, que gerencia com segurança as credenciais de autenticação de um provedor de API. Uma conexão define o método de autorização e as credenciais a serem usados na conexão com uma determinada API. Se você estiver se conectando a uma API privada, como uma API privada em uma Amazon Virtual Private Cloud (Amazon VPC), você também pode usar a conexão para definir a conectividade de point-to-point rede segura. Usar uma conexão ajuda a evitar segredos de codificação rígida, como chaves de API, na definição da máquina de estado. Uma EventBridge conexão é compatível com os esquemas de autorização Basic OAuth, e API Key.

Ao criar uma EventBridge conexão, você fornece seus detalhes de autorização e conectividade de rede. Também é possível incluir o cabeçalho, o corpo e os parâmetros de consulta necessários para autorização com uma API. Você deve incluir o ARN da conexão em qualquer tarefa HTTP que chame uma API HTTPS.

Quando você cria uma conexão, EventBridge cria uma entrada secreta AWS Secrets Manager. Nesse segredo, EventBridge armazena os parâmetros de conexão e autorização em um formato criptografado. Para criar ou atualizar uma conexão com sucesso, você deve usar uma Conta da AWS que tenha permissão para usar o Secrets Manager. Para obter mais informações sobre o IAM permissões que sua máquina de estado precisa para acessar uma EventBridge conexão, consultePermissões do IAM para executar uma tarefa HTTP.

A imagem a seguir mostra como Step Functions processa a autorização para chamadas de API HTTPS usando um EventBridge conexão. A ferramenta EventBridge A conexão gerencia as credenciais de um provedor de API HTTPS. EventBridge cria um segredo em Secrets Manager para armazenar os parâmetros de conexão e autorização em um formato criptografado. No caso de privado APIs, EventBridge também armazena configurações de conectividade de rede.

Tempos limite para conexões

As solicitações de tarefas HTTP expirarão após 60 segundos.

Step Functions usa autorização e configuração de rede em EventBridge conexões para chamadas para endpoints HTTPS.

Definição da tarefa HTTP

A definição de ASL representa uma tarefa HTTP com o recurso http:invoke. A definição de tarefa HTTP a seguir invoca uma API pública do Stripe que retorna uma lista de todos os 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 da tarefa HTTP

Uma tarefa HTTP inclui os seguintes campos na definição.

Resource (obrigatório)

Para especificar um tipo de tarefa, forneça o ARN no campo Resource. Para uma tarefa HTTP, você vai especificar o campo Resource da forma a seguir.


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

Parameters (obrigatório)

Contém os ConnectionArn campos ApiEndpointMethod, e que fornecem informações sobre a API HTTPS que você deseja chamar. Parameterstambém contém campos opcionais, como Headers QueryParameters e.

Você pode especificar uma combinação de JSON estático e JsonPathsintaxe como Parameters no Parameters campo. Para obter mais informações, consulte Transmitir parâmetros a uma API de serviço no Step Functions.

Para especificar a EventBridge conexão, use o InvocationConfig campo Authentication ou.

ApiEndpoint (Obrigatório)

Especifica o URL da API HTTPS que você deseja chamar. Para acrescentar parâmetros de consulta ao URL, use o campo QueryParameters. O exemplo a seguir mostra como chamar uma API do Stripe para obter a lista de todos os clientes.


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

Você também pode especificar um caminho de referência usando a JsonPathsintaxe para selecionar o nó JSON que contém o URL da API HTTPS. Por exemplo, digamos que você queira ligar para um dos Stripe APIs usando um ID de cliente específico. Imagine que você tenha fornecido a entrada de estado a seguir.


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

Para recuperar os detalhes do ID desse cliente usando uma API do Stripe, especifique o ApiEndpoint conforme mostrado no exemplo a seguir. Este exemplo usa uma função intrínseca e um caminho de referência.


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

Em runtime, o Step Functions resolve o valor de ApiEndpoint da forma a seguir.


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

Method (obrigatório)

Especifica o método HTTP que você deseja usar para chamar uma API HTTPS. É possível especificar um desses métodos na tarefa HTTP: GET, POST, PUT, DELETE, PATCH, OPTIONS ou HEAD.

Por exemplo, para usar o método GET, especifique o campo Method da forma a seguir.


"Method": "GET"

Também é possível usar um caminho de referência para especificar o método em runtime. Por exemplo, "Method.$": "$.myHTTPMethod".

Authentication(Condicional)

Você deve especificar um Authentication ouInvocationConfig.

Contém o ConnectionArn campo que especifica como autenticar uma chamada pública da API HTTPS. Step Functions suporta autenticação para um especificado ApiEndpoint usando o recurso de conexão do Amazon EventBridge.

ConnectionArn (Obrigatório)

Especifica o EventBridge ARN da conexão.

Uma tarefa HTTP requer uma EventBridge conexão, que gerencia com segurança as credenciais de autorização de um provedor de API. Uma conexão especifica o tipo de autorização e as credenciais a serem usadas para autorizar uma API HTTPS. Usar uma conexão ajuda a evitar segredos de codificação rígida, como chaves de API, na definição da máquina de estado. Em uma conexão, também é possível especificar os parâmetros Headers, QueryParameters e RequestBody.

Para obter mais informações, consulte Conectividade para uma tarefa HTTP.

O exemplo a seguir mostra como especificar o campo Authentication na definição da tarefa HTTP.


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

InvocationConfig(Condicional)

Você deve especificar um Authentication ouInvocationConfig.

Contém a configuração de autorização e conectividade de rede para uma chamada privada da API HTTPS. Step Functions suporta conexão para um especificado ApiEndpoint usando o recurso de conexão do Amazon EventBridge. Para obter mais informações, consulte Conectando-se ao privado APIs no Guia EventBridge do usuário da Amazon.

ConnectionArn (Obrigatório)

Especifica o EventBridge ARN da conexão.

Uma tarefa HTTP requer uma EventBridge conexão, que gerencia com segurança as credenciais de autorização de um provedor de API. Uma conexão especifica o tipo de autorização e as credenciais a serem usadas para autorizar uma API HTTPS. Para uso privado APIs, a conexão também define conectividade point-to-point de rede segura. Usar uma conexão ajuda a evitar segredos de codificação rígida, como chaves de API, na definição da máquina de estado. Em uma conexão, também é possível especificar os parâmetros Headers, QueryParameters e RequestBody.

Para obter mais informações, consulte Conectividade para uma tarefa HTTP.

O exemplo a seguir mostra como você pode especificar um InvocationConfig campo na sua definição de tarefa HTTP.


"InvocationConfig": {
  "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/connection-id"
}

Headers (opcional)

Fornece contexto adicional e metadados ao endpoint da API. É possível especificar cabeçalhos como uma string ou uma matriz JSON.

Você pode especificar cabeçalhos no EventBridge conexão e o Headers campo em uma tarefa HTTP. É recomendável não incluir detalhes de autenticação dos provedores de API no campo Headers. Recomendamos que você inclua esses detalhes em seu EventBridge conexão.

Step Functions adiciona os cabeçalhos que você especifica no EventBridge conexão com os cabeçalhos que você especifica na definição da tarefa HTTP. Se as mesmas chaves de cabeçalho estiverem presentes na definição e na conexão, Step Functions usa os valores correspondentes especificados no EventBridge conexão para esses cabeçalhos. Para obter mais informações sobre como Step Functions executa a mesclagem de dados, consulteMesclar EventBridge conexão e dados de definição de tarefas HTTP.

O exemplo a seguir especifica um cabeçalho que será incluído em uma chamada de API HTTPS:content-type.


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

Também é possível usar um caminho de referência para especificar os cabeçalhos em runtime. Por exemplo, "Headers.$": "$.myHTTPHeaders".

Step Functions define os User-Agent Host cabeçalhosRange, e. Step Functions define o valor do Host cabeçalho com base na API que você está chamando. Veja a seguir um exemplo de valor desses cabeçalhos.


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

Não é possível usar os cabeçalhos a seguir na definição da tarefa HTTP. Se você usar esses cabeçalhos, a tarefa HTTP falhará com o erro States.Runtime.

A-IM
Accept-Charset
Accept-Datetime
Accept-Encoding
Cache-Control
Conexão
Content-Encoding
Conteúdo- MD5
Data
Expect
Encaminhado
De
Host
HTTP2-Configurações
If-Match
If-Modified-Since
If-None-Match
If-Range
If-Unmodified-Since
Max-Forwards
Origem
Pragma
Proxy-Authorization
Referer
Servidor
TE
Trailer
Transfer-Encoding
Upgrade
Via
Aviso
x-forwarded-*
x-amz-*
x-amzn-*

QueryParameters (opcional)

Insere pares de chave-valor no final de um URL de API. Você pode especificar parâmetros de consulta como uma string, uma matriz JSON ou um objeto JSON. Step Functions codifica automaticamente os parâmetros de consulta em URL quando chama uma API HTTPS.

Por exemplo, digamos que você queira chamar a API do Stripe para pesquisar clientes que realizam transações em dólares americanos (USD). Imagine que você tenha fornecido QueryParameters a seguir como a entrada de estado.


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

Em runtime, o Step Functions anexa o QueryParameters ao URL da API da forma a seguir.


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

Também é possível usar um caminho de referência para especificar os parâmetros de consulta em runtime. Por exemplo, "QueryParameters.$": "$.myQueryParameters".

Se você especificou parâmetros de consulta em seu EventBridge conexão, Step Functions adiciona esses parâmetros de consulta aos parâmetros de consulta que você especifica na definição da tarefa HTTP. Se as mesmas chaves de parâmetros de consulta estiverem presentes na definição e na conexão, Step Functions usa os valores correspondentes especificados no EventBridge conexão para esses cabeçalhos. Para obter mais informações sobre como Step Functions executa a mesclagem de dados, consulteMesclar EventBridge conexão e dados de definição de tarefas HTTP.

Transform (opcional)

Contém os cabeçalhos RequestBodyEncoding e RequestEncodingOptions. Por padrão, Step Functions envia o corpo da solicitação como dados JSON para um endpoint da API.

Se o provedor de API aceitar corpos de solicitação form-urlencoded, use o campo Transform para especificar a codificação de URL para os corpos de solicitação. Você também deve especificar o content-type cabeçalho comoapplication/x-www-form-urlencoded. Step Functions em seguida, codifica automaticamente o URL do corpo da solicitação.

RequestBodyEncoding

Especifica a codificação do corpo da solicitação em URL. É possível especificar um destes valores: NONE ou URL_ENCODED.

NONE: o corpo da solicitação HTTP será o JSON serializado do campo RequestBody. Este é o valor padrão.
URL_ENCODED: o corpo da solicitação HTTP serão os dados do formulário codificados em URL do campo RequestBody.

RequestEncodingOptions

Determina a opção de codificação a ser usada para matrizes no corpo da solicitação, se você definir RequestBodyEncoding como URL_ENCODED.

Step Functions suporta as seguintes opções de codificação de matriz. Para obter mais informações sobre essas opções e exemplos, consulte Aplicar a codificação em URL no corpo da solicitação.

INDICES: codifica matrizes usando o valor do índice dos elementos da matriz. Por padrão, Step Functions usa essa opção de codificação.
REPEAT: repete uma chave para cada item em uma matriz.
COMMAS: codifica todos os valores em uma chave como uma lista de valores delimitada por vírgula.
BRACKETS: repete uma chave para cada item em uma matriz e acrescenta um colchete, [], à chave para indicar que é uma matriz.

O exemplo a seguir define a codificação em URL dos dados do corpo da solicitação. Também especifica o uso da opção de codificação COMMAS para matrizes no corpo da solicitação.


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

RequestBody (opcional)

Aceita dados JSON fornecidos na entrada de estado. EmRequestBody, você pode especificar uma combinação de JSON estático e JsonPathsintaxe. Por exemplo, vamos supor que você forneça a seguinte entrada de estado:


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

Para usar esses valores de CardNumber e ExpiryDate no corpo da solicitação em runtime, é possível especificar os dados JSON a seguir no corpo da solicitação.


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

Se a API HTTPS que você deseja chamar exigir corpos de form-urlencoded solicitação, você deverá especificar a codificação de URL para os dados do corpo da solicitação. Para obter mais informações, consulte Aplicar a codificação em URL no corpo da solicitação.

Mesclar EventBridge conexão e dados de definição de tarefas HTTP

Ao invocar uma tarefa HTTP, você pode especificar dados em seu EventBridge conexão e sua definição de tarefa HTTP. Esses dados incluem os parâmetros Headers, QueryParameters e RequestBody. Antes de chamar uma API HTTPS, o Step Functions mescla o corpo da solicitação com os parâmetros do corpo da conexão em todos os casos, exceto se o corpo da solicitação for uma string e os parâmetros do corpo da conexão não estiverem vazios. Nesse caso, a tarefa HTTP falhará com o erro States.Runtime.

Se houver alguma chave duplicada especificada na definição da Tarefa HTTP e na EventBridge conexão, Step Functions sobrescreve os valores na tarefa HTTP pelos valores na conexão.

A lista a seguir descreve como Step Functions mescla dados antes de chamar uma API HTTPS:

Cabeçalhos — Step Functions adiciona todos os cabeçalhos que você especificou na conexão aos cabeçalhos no Headers campo da tarefa HTTP. Se houver um conflito entre as teclas do cabeçalho, Step Functions usa os valores especificados na conexão para esses cabeçalhos. Por exemplo, se você especificou o content-type cabeçalho na definição da tarefa HTTP e EventBridge conexão, Step Functions usa o valor do content-type cabeçalho especificado na conexão.
Parâmetros de consulta — Step Functions adiciona quaisquer parâmetros de consulta que você especificou na conexão aos parâmetros de consulta no QueryParameters campo da tarefa HTTP. Se houver um conflito entre as chaves dos parâmetros de consulta, Step Functions usa os valores especificados na conexão para esses parâmetros de consulta. Por exemplo, se você especificou o parâmetro de maxItems consulta na definição da tarefa HTTP e EventBridge conexão, Step Functions usa o valor do parâmetro de maxItems consulta especificado na conexão.
Body parameters (Parâmetros do corpo)
- Step Functions adiciona todos os valores do corpo da solicitação especificados na conexão ao corpo da solicitação no RequestBody campo da tarefa HTTP. Se houver um conflito entre as chaves do corpo da solicitação, Step Functions usa os valores especificados na conexão para o corpo da solicitação. Por exemplo, digamos que você especificou um Mode campo na RequestBody definição da tarefa HTTP e EventBridge conexão. Step Functions usa o valor do Mode campo que você especificou na conexão.
- Se você especificar o corpo da solicitação como uma string em vez de um objeto JSON, e o EventBridge a conexão também contém o corpo da solicitação, Step Functions não é possível mesclar o corpo da solicitação especificado nesses dois locais. A tarefa HTTP falha com o erro States.Runtime.
Step Functions aplica todas as transformações e serializa o corpo da solicitação após concluir a mesclagem do corpo da solicitação.

O exemplo a seguir define os RequestBody campos HeadersQueryParameters, e na Tarefa HTTP e EventBridge conexão.

Definição da tarefa 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 conexão


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

Neste exemplo, chaves duplicadas são especificadas na tarefa HTTP e EventBridge conexão. Portanto, Step Functions sobrescreve os valores na tarefa HTTP pelos valores na conexão. O trecho de código a seguir mostra a solicitação HTTP que Step Functions envia para a 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"}

Aplicar a codificação em URL no corpo da solicitação

Por padrão, Step Functions envia o corpo da solicitação como dados JSON para um endpoint da API. Se seu provedor de API HTTPS exigir corpos de form-urlencoded solicitação, você deverá especificar a codificação de URL para os corpos da solicitação. Step Functions em seguida, codifica automaticamente o corpo da solicitação com base na opção de codificação de URL selecionada.

Você vai especificar a codificação em URL usando o campo Transform. Esse campo contém o campo RequestBodyEncoding que especifica se a codificação em URL será aplicada ou não aos corpos da solicitação. Quando você especifica o RequestBodyEncoding campo, Step Functions converte o corpo da solicitação JSON em corpo da form-urlencoded solicitação antes de chamar a API HTTPS. Você também deve especificar o content-type cabeçalho, application/x-www-form-urlencoded pois aqueles APIs que aceitam dados codificados em URL esperam o cabeçalho. content-type

Para codificar matrizes no corpo da solicitação, Step Functions fornece as seguintes opções de codificação de matriz.

INDICES: repete uma chave para cada item em uma matriz e acrescenta um colchete, [], à chave para indicar que é uma matriz. Esse colchete contém o índice do elemento da matriz. Adicionar o índice ajuda a especificar a ordem dos elementos da matriz. Por padrão, Step Functions usa essa opção de codificação.

Por exemplo, se o corpo da solicitação contiver a matriz a seguir.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica essa matriz para a sequência de caracteres a seguir.
```
array[0]=a&array[1]=b&array[2]=c&array[3]=d
```
REPEAT: repete uma chave para cada item em uma matriz.

Por exemplo, se o corpo da solicitação contiver a matriz a seguir.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica essa matriz para a sequência de caracteres a seguir.
```
array=a&array=b&array=c&array=d
```
COMMAS: codifica todos os valores em uma chave como uma lista de valores delimitada por vírgula.

Por exemplo, se o corpo da solicitação contiver a matriz a seguir.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica essa matriz para a sequência de caracteres a seguir.
```
array=a,b,c,d
```
BRACKETS: repete uma chave para cada item em uma matriz e acrescenta um colchete, [], à chave para indicar que é uma matriz.

Por exemplo, se o corpo da solicitação contiver a matriz a seguir.
```
{"array": ["a","b","c","d"]}
```
Step Functions codifica essa matriz para a sequência de caracteres a seguir.
```
array[]=a&array[]=b&array[]=c&array[]=d
```

Permissões do IAM para executar uma tarefa HTTP

Sua função de execução da máquina de estado deve ter as seguintes permissões para que uma tarefa HTTP chame uma API HTTPS:

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

O exemplo de política do IAM a seguir concede os privilégios mínimos necessários à sua função de máquina de estado para chamar o APIs Stripe. Essa política do IAM também concede permissão à função de máquina de estado para acessar uma EventBridge conexão específica, incluindo o segredo dessa conexão que está armazenado no 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/*"
        }
    ]
}

Exemplo de tarefa HTTP

A definição de máquina de estado a seguir mostra uma tarefa HTTP que inclui os parâmetros Headers, QueryParameters, Transform e RequestBody. A tarefa HTTP chama uma API do Stripe, https://api.stripe.com/v1/ faturas, para gerar uma fatura. A tarefa HTTP também especifica a codificação em URL para o corpo da solicitação usando a opção de codificação INDICES.

Certifique-se de que você criou um EventBridge conexão. O exemplo a seguir mostra uma conexão criada usando o tipo de autenticação básica.


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

Lembre-se de substituir o italicized texto pelas informações específicas do seu 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 executar essa máquina de estado, forneça o ID do cliente como entrada, conforme mostrado no seguinte exemplo:


{
    "customer_id": "1234567890"
}

O exemplo a seguir mostra a solicitação HTTP que Step Functions envia para a API 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

Testar uma tarefa HTTP

Você pode usar a TestStateAPI por meio do console, do SDK ou do AWS CLI para testar uma tarefa HTTP. O procedimento a seguir descreve como usar a TestState API no Step Functions console. É possível testar iterativamente os detalhes da solicitação, da resposta e da autenticação da API até que a tarefa HTTP esteja funcionando conforme o esperado.

Teste um estado de tarefa HTTP em Step Functions console

Abra o console do Step Functions.
Selecione Criar uma máquina de estado para começar a criar uma máquina de estado ou escolha uma máquina de estado que contenha uma tarefa HTTP.

Consulte a Etapa 4 se você estiver testando a tarefa em uma máquina de estado existente.
No Modo de design do Workflow Studio, configure visualmente uma tarefa HTTP. Também é possível selecionar o modo Código para copiar e colar a definição da máquina de estado do ambiente de desenvolvimento local.
No Modo de design, selecione Testar estado no painel Painel Inspetor do Workflow Studio.
Na caixa de diálogo Testar estado, faça o seguinte:
1. Em Perfil de execução, selecione um perfil de execução para testar o estado. Se você não tiver um perfil com permissões suficientes para uma tarefa HTTP, consulte Perfil para testar tarefas HTTP no Workflow Studio para criar um perfil.
2. (Opcional) Forneça todas as entradas JSON de que o estado selecionado precise para o teste.
3. Em nível de inspeção, mantenha a seleção padrão de INFO. Esse nível mostra o status da chamada de API e a saída do estado. Isso é útil para conferir rapidamente a resposta da API.
4. Selecione Iniciar teste.
5. Se o teste for bem-sucedido, a saída do estado aparecerá no lado direito da caixa de diálogo Testar estado. Se o teste falhar, um erro será exibido.
  
  Na guia Detalhes do estado da caixa de diálogo, você pode ver a definição do estado e um link para seu EventBridge conexão.
6. Altere o nível de inspeção para TRACE. Esse nível mostra a solicitação e a resposta HTTP brutas e é útil para verificar cabeçalhos, parâmetros de consulta e outros detalhes específicos da API.
7. Marque a caixa de seleção Revelar segredos. Em combinação com TRACE, essa configuração permite que você veja os dados confidenciais que o EventBridge inserções de conexão, como chaves de API. A ferramenta IAM a identidade do usuário que você usa para acessar o console deve ter permissão para realizar a states:RevealSecrets ação. Sem essa permissão, Step Functions gera um erro de acesso negado quando você inicia o teste. Para um exemplo de IAM política que define a states:RevealSecrets permissão, consulteIAM permissões para usar a TestState API.
  
  A imagem a seguir mostra um teste bem-sucedido para uma tarefa HTTP. O Nível de inspeção para esse estado é definido como TRACE. A guia Solicitação e resposta HTTP na imagem a seguir mostra o resultado da chamada da API HTTPS.
8. Selecione Iniciar teste.
9. Se o teste for bem-sucedido, será possível ver os detalhes HTTP na guia Solicitação e resposta HTTP.

Respostas da tarefa HTTP não compatíveis

Uma tarefa HTTP falhará com o erro States.Runtime se uma das seguintes condições for verdadeira para a resposta exibida:

A resposta contém um cabeçalho do tipo de conteúdo de application/octet-stream, image/*, video/* ou audio/*.
A resposta não pode ser lida como uma string válida. Por exemplo, dados binários ou de imagem.

Erros de conexão

Se EventBridge encontrar um problema ao se conectar à API especificada durante a execução do fluxo de trabalho, o Step Functions gera o erro em seu fluxo de trabalho. Os erros de conexão são prefixados comEvents.ConnectionResource..

Esses erros incluem:

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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Padrões de integração de serviço

Passar parâmetros