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á.
# Crie o API Gateway REST APIs com Step Functions
Aprenda a usar o Amazon API Gateway para criar, publicar, manter e monitorar HTTP e REST APIs com Step Functions. Para fazer a integração com o API Gateway, você define um estado `Task` no Step Functions que chama diretamente um endpoint de HTTP do API Gateway ou de REST do API Gateway, sem escrever código ou depender de outra infraestrutura. Uma definição de estado `Task` inclui todas as informações necessárias para a chamada da API. Também é possível selecionar métodos de autorização diferentes.
Para saber mais sobre a integração com AWS serviços no Step Functions, consulte [Integração de produtos da ](integrate-services.md) e. [Transmitir parâmetros a uma API de serviço no Step Functions](connect-parameters.md)
**Principais recursos da integração otimizada do API Gateway**
`apigateway:invoke:`não tem equivalente na integração de serviços do AWS SDK. Em vez disso, o serviço Optimized API Gateway chama o endpoint do API Gateway diretamente.
## Suporte ao recurso API Gateway
A integração do API Gateway do Step Functions é compatível com alguns, mas não todos os recursos do API Gateway. Para obter uma lista mais detalhada dos recursos compatíveis, consulte o seguinte:
+ Compatível com as integrações da API REST do API Gateway e do API HTTP do API Gateway do Step Functions:
+ **Autorizadores**: IAM (usando [Singature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)), No Auth, Lambda Authorizers (baseados em parâmetros de solicitação e baseados em tokens com cabeçalho personalizado)
+ **Tipos de API**: regional
+ **Gerenciamento de API**: nomes de domínio de API do API Gateway, estágio da API, caminho, parâmetros de consulta, corpo da solicitação
+ Compatível com a integração da API HTTP do API Gateway do Step Functions. A integração da API REST do Step Functions API Gateway que fornece a opção de otimização para borda não APIs é suportada.
+ Não compatível com a integração do API Gateway do Step Functions:
+ **Autorizadores**: Amazon Cognito, Native Open ID Connect OAuth /2.0, cabeçalho de autorização para autorizadores Lambda baseados em tokens
+ **Tipos de API**: privado
+ **Gerenciamento de API**: nomes de domínio personalizados
Para obter mais informações sobre o API Gateway e seu HTTP e REST APIs, consulte o seguinte.
+ A página [Conceitos do Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html).
+ [Escolha entre HTTP APIs e REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) no guia do desenvolvedor do API Gateway.
## Formato de solicitação
Quando você cria a definição de estado `Task`, o Step Functions valida os parâmetros, cria a URL necessária para realizar a chamada e, em seguida, chama a API. A resposta inclui o código de status HTTP, cabeçalhos e corpo da resposta. O formato da solicitação tem parâmetros obrigatórios e opcionais.
### Parâmetros de solicitação obrigatórios
+ `ApiEndpoint`
+ Tipo: `String`
+ O nome do host de um URL do API Gateway. O formato é `{{}}.execute-api.{{region}}.amazonaws.com`.
O ID da API só pode conter uma combinação dos seguintes caracteres alfanuméricos: `0123456789abcdefghijklmnopqrstuvwxyz`
+ `Method`
+ Tipo: `Enum`
+ O método HTTP, que deve ser um dos seguintes:
+ `GET`
+ `POST`
+ `PUT`
+ `DELETE`
+ `PATCH`
+ `HEAD`
+ `OPTIONS`
### Parâmetros de solicitação opcionais
+ `Headers`
+ Tipo: `JSON`
+ Os cabeçalhos HTTP permitem uma lista de valores associados à mesma chave.
+ `Stage`
+ Tipo: `String`
+ O nome do estágio em que a API é implantada no API Gateway. É opcional para qualquer API HTTP que use o estágio `$default`.
+ `Path`
+ Tipo: `String`
+ Parâmetros de caminho que são anexados após o endpoint da API.
+ `QueryParameters`
+ Tipo: `JSON`
+ As strings de consulta só permitem uma lista de valores associados à mesma chave.
+ `RequestBody`
+ Tipo: `JSON` ou `String`
+ O corpo da solicitação HTTP. O tipo pode ser um objeto `JSON` ou `String`. `RequestBody` só é compatível com os métodos de HTTP `PATCH`, `POST` e `PUT`.
+ `AllowNullValues`
+ Tipo: `BOOLEAN`: valor padrão: `false`
+ Com a configuração padrão, os valores **nulos** no estado de entrada da solicitação **não** serão enviados à API. No exemplo a seguir, o campo `category` **não** será incluído na solicitação, a menos que `AllowNullValues` esteja definido como `true` na definição da máquina de estado.
```
{
"NewPet": {
"type": "turtle",
"price": 123,
"category": null
}
}
```
**nota**
Por padrão, campos com valores **nulos** no estado de entrada da solicitação **não** serão enviados à API. É possível forçar o envio de valores nulos à API configurando `AllowNullValues` como `true` na definição da máquina de estado.
+ `AuthType`
+ Tipo: `JSON`
+ O método de autenticação. O método padrão é `NO_AUTH`. Os valores permitidos são:
+ `NO_AUTH`
+ `IAM_ROLE`
+ `RESOURCE_POLICY`
Consulte **Autenticação e autorização** para obter mais informações.
**nota**
Por questões de segurança, as seguintes chaves de cabeçalho HTTP não são permitidas atualmente:
Qualquer coisa prefixada com `X-Forwarded`, `X-Amz` ou `X-Amzn`.
`Authorization`
`Connection`
`Content-md5`
`Expect`
`Host`
`Max-Forwards`
`Proxy-Authenticate`
`Server`
`TE`
`Transfer-Encoding`
`Trailer`
`Upgrade`
`Via`
`Www-Authenticate`
O exemplo de código a seguir mostra como invocar o API Gateway usando o Step Functions.
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "GET",
"Headers": {
"key": ["value1", "value2"]
},
"Stage": "prod",
"Path": "bills",
"QueryParameters": {
"billId": ["123456"]
},
"RequestBody": {},
"AuthType": "NO_AUTH"
}
}
```
## Autenticação e autorização
Você pode usar os seguintes métodos de autenticação:
+ **Sem autorização**: chame a API diretamente sem nenhum método de autorização.
+ **Perfil do IAM**: com esse método, o Step Functions assume o papel da máquina de estado, assina a solicitação com [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (SigV4) e chama a API.
+ **Política de recursos**: o Step Functions autentica a solicitação e, em seguida, chama a API. Você deve anexar uma política de recursos à API que especifique o seguinte:
1. A máquina de estado que invocará o API Gateway.
**Importante**
Você deve especificar a máquina de estado para limitar o acesso a ela. Caso contrário, qualquer máquina de estado que autentique a solicitação do API Gateway com a autenticação **Política de recursos** na API receberá acesso.
1. Esse Step Functions é o serviço que chama o API Gateway: `"Service": "states.amazonaws.com"`.
1. O recurso que você deseja acessar, incluindo:
+ O {{region}}.
+ O {{account-id}} na região especificada.
+ O {{api-id}}.
+ O {{stage-name}}.
+ O {{HTTP-VERB}} (método).
+ O {{resource-path-specifier}}.
Para ver um exemplo de política de recursos, consulte [Políticas do IAM para Step Functions e API Gateway](#api-gateway-iam).
Para obter mais informações sobre o formato do recurso, consulte [Formato do recurso de permissões para executar a API no API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api) no Guia do desenvolvedor do API Gateway.
**nota**
As políticas de recursos são compatíveis somente com a API REST.
## Padrões de integração de serviço
A integração do API Gateway oferece suporte a dois padrões de integração de serviços:
+ [Resposta de solicitação](connect-to-resource.md#connect-default), que é o padrão de integração padrão. Ele permite que o Step Functions avance para a próxima etapa imediatamente após receber uma resposta HTTP.
+ [Aguardar um retorno de chamada com um token de tarefa](connect-to-resource.md#connect-wait-token) (`.waitForTaskToken`), que espera até que um token de tarefa seja retornado com uma carga útil. Para usar o `.waitForTaskToken` padrão, anexe. waitForTaskToken no final do campo **Recurso** da definição de sua tarefa, conforme mostrado no exemplo a seguir:
```
{
"Type": "Task",
"Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "POST",
"Headers": {
"TaskToken": "{% $states.context.Task.Token %}"
},
"Stage": "prod",
"Path": "bills/add",
"QueryParameters": {},
"RequestBody": {
"billId": "my-new-bill"
},
"AuthType": "IAM_ROLE"
}
}
```
## Formato de saída
Os seguintes parâmetros de saída são fornecidos:
| Nome | Tipo | Description |
| --- | --- | --- |
| ResponseBody | JSON ou String | O corpo da resposta da chamada de API. |
| Headers | JSON | Os cabeçalhos de resposta. |
| StatusCode | Integer | O código de status HTTP da resposta. |
| StatusText | String | O texto do status da resposta. |
Um exemplo de resposta:
```
{
"ResponseBody": {
"myBills": []
},
"Headers": {
"key": ["value1", "value2"]
},
"StatusCode": 200,
"StatusText": "OK"
}
```
## Tratamento de erros
Quando ocorre um erro, `error` e `cause` são retornados da seguinte forma:
+ Se o código de status HTTP estiver disponível, o erro será retornado no formato `ApiGateway.{{}}`.
+ Se o código de status HTTP estiver indisponível, o erro será retornado no formato `ApiGateway.{{}}`.
Em ambos os casos, `cause` é retornado como uma string.
O seguinte exemplo mostra uma resposta em que ocorreu um erro:
```
{
"error": "ApiGateway.403",
"cause": "{\"message\":\"Missing Authentication Token\"}"
}
```
**nota**
Um código de status `2XX` indica sucesso e nenhum erro será retornado. Todos os outros códigos de status ou exceções lançadas resultarão em um erro.
## Políticas do IAM para chamadas para o Amazon API Gateway
Os modelos de exemplo a seguir mostram como AWS Step Functions gera políticas do IAM com base nos recursos na definição da sua máquina de estado. Para obter mais informações, consulte [Como o Step Functions gera políticas do IAM para serviços integrados](service-integration-iam-templates.md) e [Descobrir padrões de integração de serviços no Step Functions](connect-to-resource.md).
*Recursos:*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/GET/pets",
"arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:ENDPOINT/STAGE/POST/pets"
],
"Effect": "Allow"
}
]
}
```
O exemplo de código a seguir mostra uma política de recursos para chamar o API Gateway.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "states.amazonaws.com"
},
"Action": "execute-api:Invoke",
"Resource": "arn:aws:execute-api:{{us-east-1}}:{{123456789012}}:myApi-id/{{stage-name}}/{{HTTP-VERB}}/{{resource-path-specifier}}",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
"{{}}"
]
}
}
}
]
}
```