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á.
# Chamar APIs HTTPS nos fluxos de trabalho do Step Functions
Uma tarefa HTTP é um tipo de estado [Estado de tarefa do fluxo de trabalho](state-task.md) que você pode usar para chamar APIs HTTPS 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 HTTPS-based aplicativos 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, a tarefa HTTP só oferece suporte a nomes de domínio público com certificados publicamente confiáveis para endpoints HTTPS ao usar APIs privadas. 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 EventBridge conexão e dados de definição de tarefas HTTP](#http-task-data-merge)
+ [URL-encoding Formulário de inscrição mediante 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), também pode usar a conexão para definir uma conectividade segura de rede ponto a ponto. 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 APIs privadas, EventBridge também armazena configurações de conectividade de rede.
**Tempos limite para conexões**
As solicitações HTTP expiram após 60 segundos.
## 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 chamar uma das APIs do Stripe usando o ID de um 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.$": "$.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 a APIs privadas](https://docs.aws.amazon.com/eventbridge/latest/userguide/connection-private.html) no *Guia do EventBridge 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 APIs privadas, a conexão também define uma conectividade segura de rede ponto a ponto. 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 EventBridge conexão e dados de definição de tarefas 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.$": "$.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
+ Content-MD5
+ Data
+ Expect
+ Encaminhado
+ De
+ Host
+ HTTP2-Settings
+ 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 URL-encodes consulta parâmetros automaticamente 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.$": "$.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 EventBridge conexão e dados de definição de tarefas 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 seu provedor de API aceitar corpos de `form-urlencoded` solicitação, use o `Transform` campo URL-encoding para especificar os corpos de solicitação. Você também deve especificar o `content-type` cabeçalho como`application/x-www-form-urlencoded`. Step Functionsem seguida, automaticamente URL-encodes o corpo da sua solicitação.
`RequestBodyEncoding`
Especifica o corpo URL-encoding da sua solicitação. É 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 URL-encoded formulário do `RequestBody` campo.
`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 [URL-encoding Formulário de inscrição mediante 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 URL-encoding os 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 que você deseja chamar exigir corpos de `form-urlencoded` solicitação, você deverá especificar URL-encoding os dados do corpo da solicitação. Para obter mais informações, consulte [URL-encoding Formulário de inscrição mediante solicitação](#url-encode-request-body).
## Mesclar EventBridge conexão e dados de definição de tarefas 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"}
```
## URL-encoding Formulário de inscrição mediante solicitação
Por padrão, o Step Functions envia o corpo da solicitação como dados JSON a um endpoint da API. Se seu provedor de API HTTPS exigir corpos de `form-urlencoded` solicitação, você deverá especificar URL-encoding os corpos da solicitação. Step Functionsem seguida, automaticamente URL-encodes o corpo da solicitação com base na URL-encoding opção selecionada.
Você especifica URL-encoding usando o `Transform` campo. Esse campo contém o `RequestBodyEncoding` campo que especifica se você deseja ou não se inscrever URL-encoding para seus corpos de 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 as APIs que aceitam URL-encoded dados esperam o `content-type` cabeçalho.
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 ao perfil da máquina de estado para chamar APIs do 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/*"
}
]
}
```
**Importante**
Você pode definir o escopo das `states:InvokeHTTPEndpoint` permissões para uma máquina de estado específica especificando o ARN da máquina de estado no campo `Resource` da declaração de política, mas não há suporte para definir o escopo adicional das permissões usando [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourcetag](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourcetag)uma chave de condição no momento.
## 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 Stripe,https://api.stripe.com/v1/invoices, para gerar uma fatura. A tarefa HTTP também especifica o URL-encoding corpo da solicitação usando a opção de `INDICES` codificação.
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.
**Teste um estado de tarefa HTTP em Step Functions console**
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 API-specific detalhes.
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.
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`