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á.

# Criar uma API do Step Functions usando o API Gateway
<a name="tutorial-api-gateway"></a>

Você pode usar o Amazon API Gateway para associá-lo a AWS Step Functions APIs métodos em uma API do API Gateway. Quando uma solicitação HTTPS for enviada para um método de API, o API Gateway invoca as ações de sua API do Step Functions.

Este tutorial mostra como criar uma API que usa um único recurso e o método `POST` para se comunicar com a ação de API `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)`. Você usará o console AWS Identity and Access Management (IAM) para criar uma função para o API Gateway. Em seguida, você usará o console do API Gateway para criar uma API do API Gateway, criar um recurso e um método e mapear o método para a ação de API `StartExecution`. Ao final, você implantará e testará sua API.

**nota**  
Embora o Amazon API Gateway possa iniciar uma execução do Step Functions chamando `StartExecution`, você deve chamar `[DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html)` para obter o resultado.

## Etapa 1: Criar um perfil do IAM para o API Gateway
<a name="api-gateway-step-1"></a>

Antes de criar a API do API Gateway, você precisa permitir que o API Gateway chame ações de API do Step Functions.<a name="api-gateway-procedure-create-iam-role"></a>

**Para configurar permissões para o API Gateway**

1. Faça login no [console do IAM](https://console.aws.amazon.com/iam/home) e escolha **Perfis**, **Criar perfil**.

1. Na página **Selecionar entidade confiável**, faça o seguinte:

   1. Para o **Tipo de entidade confiável**, retenha a seleção-padrão de **AWS service (Serviço da AWS)**.

   1. Em **Caso de uso**, escolha **API Gateway** na lista suspensa.

1. Selecione **API Gateway** e escolha **Próximo**.

1. Na página **Adicionar permissões**, escolha **Próximo**.

1. (Opcional) Na página **Nomear, revisar e criar**, insira detalhes, como o nome da função. Por exemplo, digite **APIGatewayToStepFunctions**.

1. Selecione **Criar perfil**.

   O perfil do IAM é exibido na lista de perfis.

1. Escolha o nome da sua função e anote o **Role ARN (ARN da função)**, conforme mostrado no exemplo a seguir.

   ```
   arn:aws:iam::123456789012:role/APIGatewayToStepFunctions
   ```<a name="api-gateway-attach-policy-to-role"></a>

**Para anexar uma política ao perfil do IAM**

1. Na página **Roles (Funções)**, procure sua função (`APIGatewayToStepFunctions`) e escolha-a.

1. Na guia **Permissões**, escolha **Adicionar permissões** e **Anexar políticas**.

1. Na página **Anexar política**, procure `AWSStepFunctionsFullAccess`, escolha a política e escolha **Adicionar permissões**.

## Etapa 2: Criar a API no API Gateway
<a name="api-gateway-step-2"></a>

Depois de criar o perfil do IAM, poderá criar uma API personalizada do API Gateway.

**Para criar a API**

1. Abra o [console do Amazon API Gateway](https://console.aws.amazon.com/apigateway/) e, depois, selecione **Criar API**.

1. Na página **Escolher um tipo de API**, no painel **API REST**, escolha **Criar**.

1. Na página **Criar API REST**, selecione **Nova API** e, em seguida, insira ***StartExecutionAPI*** o **nome da API**.

1. Mantenha o **Tipo de endpoint da API** como **Regional** e, depois, selecione **Criar API**.<a name="api-gateway-create-resource"></a>

**Para criar um recurso**

1. Na página **Recursos** do***StartExecutionAPI***, escolha **Criar recurso**.

1. Na página **Criar recurso**, insira **execution** para **Nome do recurso** e, depois, selecione **Criar recurso**.<a name="api-gateway-create-method"></a>

**Para criar um método POST**

1. Selecione o recurso **/execution** e, depois, **Criar método**.

1. Em **Tipo de método**, selecione `POST`.

1. Em **Tipo de integração**, selecione **Serviço da AWS **.

1. Em **Região da AWS**, selecione uma região na lista.

1. Em **AWS service (Serviço da AWS)**, selecione **Step Functions** na lista.

1. Mantenha o **subdomínio da AWS** em branco.

1. Em **Método HTTP**, selecione **POST** na lista.
**nota**  
Todas as ações da API do Step Functions usam o método HTTP `POST`.

1. Em **Tipo de ação**, selecione **Usar nome da ação**.

1. Em **Nome da ação**, insira **StartExecution**.

1. Em **Função de execução**, insira [o ARN do perfil do IAM criado antes](#api-gateway-procedure-create-iam-role), conforme mostrado no exemplo a seguir.

   ```
   arn:aws:iam::123456789012:role/APIGatewayToStepFunctions
   ```

1. Mantenha as opções padrão para **Cache de credenciais** e **Tempo limite padrão** e, depois, selecione **Salvar**.

O mapeamento visual entre o API Gateway e o Step Functions é exibido na página **/execução – POST – Método de execução**.

## Etapa 3: Testar e implantar a API do API Gateway
<a name="api-gateway-step-3"></a>

Assim que você tiver criado a API, teste-a e implante-a. <a name="api-gateway-test-api"></a>

**Para testar a comunicação entre o API Gateway e o Step Functions**

1. Na página **/execution - POST - Execução do método**, selecione **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

1. Na guia **/execution – POST – Teste de método**, copie os parâmetros da solicitação a seguir na seção **Corpo da solicitação** usando o ARN de uma máquina de estado existente (ou [criar uma máquina de estado que use uma função do Lambda](tutorial-creating-lambda-state-machine.md)) e, depois, selecione **Testar**.

   ```
   {
      "input": "{}",
      "name": "MyExecution",
      "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:HelloWorld"
   }
   ```

   Para obter mais informações, consulte [Request Syntax](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html#API_StartExecution_RequestSyntax) (Sintaxe da solicitação) `StartExecution` na *Referência da API AWS Step Functions*.
**nota**  
Se não quiser incluir o ARN da máquina de estado no corpo da chamada do API Gateway, será possível configurar um modelo de mapeamento na guia **Solicitação de integração**, conforme mostrado no exemplo a seguir.  

   ```
   {
       "input": "$util.escapeJavaScript($input.json('$'))",
       "stateMachineArn": "$util.escapeJavaScript($stageVariables.arn)"
   }
   ```
Com essa abordagem, você pode especificar máquinas ARNs de estado diferentes com base em seu estágio de desenvolvimento (por exemplo`dev`,`test`, e`prod`). Para obter mais informações sobre como especificar variáveis de estágio em um modelo de mapeamento, consulte [https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#stagevariables-template-reference](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html#stagevariables-template-reference) no *Guia do desenvolvedor do API Gateway*.

1. A execução começa e o ARN da execução e a respectiva data de referência de época são exibidos em **Corpo da resposta**.

   ```
   {
      "executionArn": "arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution",
      "startDate": 1486768956.878
   }
   ```
**nota**  
Você pode visualizar a execução escolhendo sua máquina de estado no [console do AWS Step Functions](https://console.aws.amazon.com/states/).

**Para implantar sua API**

1. Na página **Recursos** de***StartExecutionAPI***, escolha **Deploy API**.

1. Em **Estágio**, selecione **Novo estágio**.

1. Em **Stage name (Nome do estágio)**, insira **alpha**.

1. (Opcional) Em **Description (Descrição)**, insira uma descrição.

1. Escolha **Implantar**.

**Para testar sua implantação**

1. Na página **Estágios** de***StartExecutionAPI***, expanda **alpha**,**/**, **/execution**, **POST** e escolha o método **POST**.

1. Em **Substituições de método**, selecione o ícone de cópia para copiar o URL de invocação da API. O URL completo deve ser semelhante ao exemplo a seguir.

   ```
   https://a1b2c3d4e5.execute-api.region.amazonaws.com/alpha/execution
   ```

1. Na linha de comando, execute o comando `curl` usando o ARN de sua máquina de estado e chame o URL de sua implantação, conforme mostrado no exemplo a seguir.

   ```
   curl -X POST -d '{"input": "{}","name": "MyExecution","stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:HelloWorld"}' https://a1b2c3d4e5.execute-api.region.amazonaws.com/alpha/execution
   ```

   O ARN de execução e sua data de epoch são retornados, conforme mostrado no exemplo a seguir.

   ```
   {"executionArn":"arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution","startDate":1.486772644911E9}
   ```
**nota**  
Se você receber um erro “Token de autenticação ausente”, verifique se o URL de invocação termina com **/execution**.