As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Chame HTTPS APIs nos fluxos de trabalho do Step Functions
Uma tarefa HTTP é um tipo de [Estado de tarefa do fluxo de trabalho](state-task.md) estado que você pode usar para chamar HTTPS APIs em seus fluxos de trabalho. A API pode ser pública, como aplicações SaaS de terceiros, como Stripe ou Salesforce. Você também pode chamar uma API privada, como aplicações baseadas 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 [Tarefa](state-task.md) com o recurso `arn:aws:states:::http:invoke`. Depois, forneça os detalhes da configuração do endpoint da API, como o URL da API, o método a ser utilizado e os detalhes da [conexão](#http-task-authentication).
Se você usa o [Workflow Studio](workflow-studio.md) para criar a máquina de estado que contém uma tarefa HTTP, o Workflow Studio gera automaticamente um perfil de execução com as políticas do IAM para a tarefa HTTP. Para obter mais informações, consulte [Perfil para testar tarefas HTTP no Workflow Studio](manage-state-machine-permissions.md#test-state-role-http).
**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 é compatível com TLS mútuo (mTLS).
**Topics**
+ [
## Conectividade para uma tarefa HTTP
](#http-task-authentication)
+ [
## Definição da tarefa HTTP
](#connect-http-task-definition)
+ [
## Campos da tarefa HTTP
](#connect-http-task-fields)
+ [
## Mesclar a conexão com o EventBridge e os dados da definição de tarefa HTTP
](#http-task-data-merge)
+ [
## Aplicar a codificação em URL no corpo da solicitação
](#url-encode-request-body)
+ [
## Permissões do IAM para executar uma tarefa HTTP
](#connect-http-task-permissions)
+ [
## Exemplo de tarefa HTTP
](#connect-http-task-example)
+ [
## Testar uma tarefa HTTP
](#http-task-test)
+ [
## Respostas da tarefa HTTP não compatíveis
](#unsupported-http-task-responses)
+ [Erros de conexão](#connect-http-task-errors)
## Conectividade para uma tarefa HTTP
Uma tarefa HTTP requer uma [EventBridgeconexão](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html), que gerencia com segurança as credenciais de autenticação de um provedor de API. Uma *conexão* define o método e as credenciais de autorização a serem usadas na conexão com 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. É necessário 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 [https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) 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 as IAM permissões que sua máquina de estado precisa para acessar uma EventBridge conexão, consulte[Permissões do IAM para executar uma tarefa HTTP](#connect-http-task-permissions).
A imagem a seguir mostra como o Step Functions processa a autorização para chamadas de API HTTPS usando uma conexão com o EventBridge. A conexão com o EventBridge gerencia as credenciais de um provedor de API HTTPS. O EventBridge cria um [https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) no Secrets Manager para armazenar os parâmetros de conexão e de 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 HTTP expiram após 60 segundos.
![\[Step Functions usa autorização e configuração de rede em EventBridge conexões para chamadas para endpoints HTTPS.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/connections-overview_step-functions_conceptual.png)
## Definição da tarefa HTTP
A [definição de ASL](concepts-amazon-states-language.md) representa uma tarefa HTTP com o recurso `http:invoke`. A definição da tarefa HTTP a seguir invoca uma API pública do Stripe que exibe 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:region:account-id: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](state-task.md#task-types), 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 campos `ApiEndpoint`, `Method` e `ConnectionArn` que fornecem informações sobre a API HTTPS a ser chamada. `Parameters` também contém campos opcionais, como `Headers` e `QueryParameters`.
Você pode especificar uma combinação de JSON estático e [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintaxe como `Parameters` no `Parameters` campo. Para obter mais informações, consulte [Transmitir parâmetros a uma API de serviço no Step Functions](connect-parameters.md).
Para especificar a EventBridge conexão, use o `InvocationConfig` campo `Authentication` *ou*.
`ApiEndpoint`**(Obrigatório)**
Especifica o URL da API HTTPS a ser chamada. 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](amazon-states-language-paths.md#amazon-states-language-reference-paths) usando a [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintaxe 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](intrinsic-functions.md) 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 a ser usado 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](amazon-states-language-paths.md#amazon-states-language-reference-paths) para especificar o método em runtime. Por exemplo, .**"Method.\$1": "\$1.myHTTPMethod"**
`Authentication`**(Condicional)**
*Recomendamos usar `InvocationConfig` em vez de `Authentication` para chamadas de API HTTPS públicas e privadas.*
As referências de `Authentication` existentes são mantidas para compatibilidade com versões anteriores. Dentro do campo, você deve especificar um campo `ConnectionArn` que especifique um recurso de conexão de Amazon EventBridge para se conectar ao `ApiEndpoint`.
`InvocationConfig`**(Condicional)**
Contém a configuração de autorização e conectividade de rede para chamadas de API HTTPS públicas **e** privadas.
O Step Functions manipula a conexão de um `ApiEndpoint` especificado usando o recurso de conexão do Amazon EventBridge. Para obter mais informações, consulte [Conectando-se ao privado APIs](https://docs.aws.amazon.com/eventbridge/latest/userguide/connection-private.html) no *Guia EventBridge do usuário da Amazon*.
`ConnectionArn`**(Obrigatório)**
Especifica o ARN da conexão com o EventBridge.
Uma tarefa HTTP requer uma [EventBridge conexão](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html), 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 utilizadas 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](#http-task-authentication).
O seguinte exemplo mostra o formato de `InvocationConfig` em uma tarefa HTTP:
```
"InvocationConfig": {
"ConnectionArn": "arn:aws:events:region:account-id: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.
É possível especificar cabeçalhos na conexão com o EventBridge e no campo `Headers` em uma tarefa HTTP. É recomendável não incluir detalhes de autenticação dos provedores de API no campo `Headers`. Recomendamos incluir esses detalhes na conexão com o EventBridge.
O Step Functions adiciona os cabeçalhos da conexão com o EventBridge aos cabeçalhos na especificados na definição da tarefa HTTP. Se as mesmas chaves de cabeçalho estiverem presentes na definição e na conexão, o Step Functions usará os valores correspondentes especificados na conexão com o EventBridge nesses cabeçalhos. Para obter mais informações sobre como o Step Functions realiza a mesclagem de dados, consulte [Mesclar a conexão com o EventBridge e os dados da definição de tarefa HTTP](#http-task-data-merge).
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](amazon-states-language-paths.md#amazon-states-language-reference-paths) para especificar os cabeçalhos em runtime. Por exemplo, .**"Headers.\$1": "\$1.myHTTPHeaders"**
O Step Functions define os cabeçalhos `User-Agent`, `Range` e `Host`. O Step Functions define o valor do cabeçalho `Host` com base na API que você está chamando. Veja a seguir um exemplo de valor desses cabeçalhos.
```
User-Agent: Amazon|StepFunctions|HttpInvoke|region,
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
+ Autorização
+ 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-\$1
+ x-amz-\$1
+ x-amzn-\$1
`QueryParameters` (Opcional)
Insere pares de chave-valor no final de um URL de API. É possível especificar parâmetros de consulta como uma string, uma matriz JSON ou um objeto JSON. O Step Functions codifica automaticamente os parâmetros de consulta em URL ao chamar 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](amazon-states-language-paths.md#amazon-states-language-reference-paths) para especificar os parâmetros de consulta em runtime. Por exemplo, .**"QueryParameters.\$1": "\$1.myQueryParameters"**
Se você tiver especificado parâmetros de consulta na conexão com o EventBridge, o Step Functions adicionará esses parâmetros aos parâmetros de consulta especificados na definição da tarefa HTTP. Se as mesmas chaves de parâmetros de consulta estiverem presentes na definição e na conexão, o Step Functions usará os valores correspondentes especificados na conexão com o EventBridge nesses cabeçalhos. Para obter mais informações sobre como o Step Functions realiza a mesclagem de dados, consulte [Mesclar a conexão com o EventBridge e os dados da definição de tarefa HTTP](#http-task-data-merge).
`Transform` (Opcional)
Contém os cabeçalhos `RequestBodyEncoding` e `RequestEncodingOptions`. Por padrão, o Step Functions envia o corpo da solicitação como dados JSON a 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. Também é necessário especificar o cabeçalho `content-type` como `application/x-www-form-urlencoded`. Depois, o Step Functions codifica automaticamente o corpo da solicitação em URL.
`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`.
O Step Functions é compatível com as opções de codificação de matriz a seguir. Para obter mais informações sobre essas opções e exemplos, consulte [Aplicar a codificação em URL no corpo da solicitação](#url-encode-request-body).
+ `INDICES`: codifica matrizes usando o valor do índice dos elementos da matriz. Por padrão, 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. Em`RequestBody`, você pode especificar uma combinação de JSON estático e [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintaxe. 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 a ser chamada exigir corpos de solicitação `form-urlencoded`, será necessário especificar a codificação em URL dos dados do corpo da solicitação. Para obter mais informações, consulte [Aplicar a codificação em URL no corpo da solicitação](#url-encode-request-body).
## Mesclar a conexão com o EventBridge e os dados da definição de tarefa HTTP
Ao invocar uma tarefa HTTP, é possível especificar dados na conexão com o EventBridge e na definição da 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 conexão com o EventBridge, o Step Functions substituirá os valores na tarefa HTTP pelos valores na conexão.
A seguinte lista descreve como o Step Functions mescla dados antes de chamar uma API HTTPS:
+ **Cabeçalhos**: o Step Functions adiciona todos os cabeçalhos especificados na conexão com os cabeçalhos no campo `Headers` da tarefa HTTP. Se houver um conflito entre as chaves do cabeçalho, o Step Functions usará os valores especificados na conexão para esses cabeçalhos. Por exemplo, se você especificou o cabeçalho `content-type` na definição da tarefa HTTP e na conexão com o EventBridge, o Step Functions usará o valor do cabeçalho `content-type` especificado na conexão.
+ **Parâmetros da consulta**: o Step Functions adiciona todos os parâmetros da consulta especificados na conexão aos parâmetros da consulta no campo `QueryParameters` da tarefa HTTP. Se houver um conflito entre as chaves de parâmetros da consulta, o Step Functions usará os valores especificados na conexão para esses cabeçalhos. Por exemplo, se você especificou o cabeçalho da consulta `maxItems` na definição da tarefa HTTP e na conexão com o EventBridge, o Step Functions usará o valor do parâmetro da consulta `maxItems` especificado na conexão.
+ **Body parameters (Parâmetros do corpo)**
+ O Step Functions adiciona todos os valores do corpo da solicitação especificados na conexão com o corpo da solicitação no campo `RequestBody` da tarefa HTTP. Se houver um conflito entre as chaves do corpo da solicitação, o Step Functions usará os valores especificados na conexão para o corpo da solicitação. Por exemplo, digamos que você tenha especificado um campo `Mode` no `RequestBody` da definição da tarefa HTTP e da conexão com o EventBridge. O Step Functions usará o valor do campo `Mode` especificado na conexão.
+ Se você especificar o corpo da solicitação como uma string em vez de um objeto JSON e a conexão com o EventBridge também contiver o corpo da solicitação, o Step Functions não poderá mesclar o corpo da solicitação especificado nesses dois locais. A tarefa HTTP falha com o erro `States.Runtime`.
O Step Functions aplica todas as transformações e serializa o corpo da solicitação depois de concluir a mesclagem do corpo da solicitação.
O exemplo a seguir define os campos `Headers`, `QueryParameters` e `RequestBody` na tarefa HTTP e na conexão com o EventBridge.
**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: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"
}
}
}
}
}
```
**Conexão com o 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"
}
]
}
}
}
```
Neste exemplo, chaves duplicadas são especificadas na tarefa HTTP e na conexão com o EventBridge. Portanto, o Step Functions substitui os valores na tarefa HTTP pelos valores na conexão. O trecho de código a seguir mostra a solicitação HTTP que o Step Functions envia à 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"}
```
## Aplicar a codificação em URL no corpo da solicitação
Por padrão, o Step Functions envia o corpo da solicitação como dados JSON a um endpoint da API. Se o provedor da API HTTPS exigir corpos da solicitação `form-urlencoded`, será necessário especificar a codificação em URL para os corpos da solicitação. Depois, o Step Functions codifica automaticamente o corpo da solicitação com base na opção de codificação em 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. Ao especificar o campo `RequestBodyEncoding`, o Step Functions converte o corpo da solicitação JSON em corpo da solicitação `form-urlencoded` 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, o Step Functions oferece as opções de codificação de matriz a seguir.
+ `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, 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"]}
```
O Step Functions codifica essa matriz para a string 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"]}
```
O Step Functions codifica essa matriz para a string 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"]}
```
O Step Functions codifica essa matriz para a string 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"]}
```
O Step Functions codifica essa matriz para a string a seguir.
```
array[]=a&array[]=b&array[]=c&array[]=d
```
## Permissões do IAM para executar uma tarefa HTTP
O perfil de execução da máquina de estado deve ter as seguintes permissões de uma tarefa HTTP para chamar 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`.
Verifique se você criou uma conexão com o EventBridge. 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: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 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 o Step Functions envia à API do Stripe.
```
POST /v1/invoices HTTP/1.1
Authorization: Basic
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
```
## Testar uma tarefa HTTP
Você pode usar a [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API por meio do console, do SDK ou do AWS CLI para [testar](test-state-isolation.md) 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.
**Testar o estado de uma tarefa HTTP no console do Step Functions**
1. Abra o [console do Step Functions](https://console.aws.amazon.com/states/home?region=us-east-1#/).
1. 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.
1. No [Modo de design](workflow-studio.md#wfs-interface-design-mode) 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.
1. No Modo de design, selecione **Testar estado** no painel [Painel Inspetor](workflow-studio.md#workflow-studio-components-formdefinition) do Workflow Studio.
1. 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](#connect-http-task-permissions) para uma tarefa HTTP, consulte [Perfil para testar tarefas HTTP no Workflow Studio](manage-state-machine-permissions.md#test-state-role-http) para criar um perfil.
1. (Opcional) Forneça todas as entradas JSON de que o estado selecionado precise para o teste.
1. 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.
1. Selecione **Iniciar teste**.
1. 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, é possível ver a definição do estado e um link para a [conexão com o EventBridge](#http-task-authentication).
1. 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.
1. Marque a caixa de seleção **Revelar segredos**. Em combinação com **TRACE**, essa configuração permite que você veja os dados confidenciais que a conexão com o EventBridge insere, como chaves de API. A identidade do usuário do IAM que você usa para acessar o console deve ter permissão para realizar a ação `states:RevealSecrets`. Sem essa permissão, o Step Functions gera um erro de acesso negado ao iniciar o teste. Para ver um exemplo de política do IAM que concede essas permissões `states:RevealSecrets`, consulte [IAMpermissões para usar a TestState API](test-state-isolation.md#test-state-permissions).
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 de API HTTPS.
![\[Saída de um estado selecionado que foi bem-sucedido no teste para o nível TRACE.\]](http://docs.aws.amazon.com/pt_br/step-functions/latest/dg/images/test-state-trace-success.png)
1. Selecione **Iniciar teste**.
1. 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 com `Events.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`