Criando um Step Functions API usando o API Gateway

Você pode usar o Amazon API Gateway para associar seu AWS Step Functions APIscom métodos em um API GatewayAPI. Quando uma HTTPS solicitação é enviada para um API método, o API Gateway invoca suas ações do Step FunctionsAPI.

Este tutorial mostra como criar um API que usa um recurso e o POST método para se comunicar com a StartExecution API ação. Você usará o AWS Identity and Access Management (IAM) console para criar uma função para o API Gateway. Em seguida, você usará o console do API Gateway para criar um API GatewayAPI, criar um recurso e um método e mapear o método para a StartExecution API ação. Por fim, você implantará e testará seuAPI.

nota

Embora o Amazon API Gateway possa iniciar uma execução de Step Functions chamandoStartExecution, você deve ligar DescribeExecution para obter o resultado.

Etapa 1: Criar uma IAM função para o API Gateway

Antes de criar seu API GatewayAPI, você precisa dar permissão ao API Gateway para chamar API ações do Step Functions.

Para configurar permissões para o API Gateway

1. Entre no IAMconsole e escolha Funções, Criar função.

2. Na página Select trusted entity (Selecionar entidade confiável), faça o seguinte:

   1. Para o tipo de entidade confiável, mantenha a seleção padrão de AWS service (Serviço da AWS).

   2. Para Caso de uso, escolha APIGateway na lista suspensa.

3. Selecione APIGateway e escolha Avançar.

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

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

6. Selecione Criar função.

   A IAM função aparece na lista de funções.

7. Escolha o nome da sua função e anote a Função ARN, conforme mostrado no exemplo a seguir.

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

Para anexar uma política à IAM função

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

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

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

Etapa 2: Crie seu API gateway API

Depois de criar sua IAM função, você pode criar seu API Gateway personalizadoAPI.

Para criar o API

1. Abra o console do Amazon API Gateway e escolha Create API.

2. Na página Escolher um API tipo, no RESTAPIpainel, escolha Construir.

3. Na REST API página Criar, selecione Novo eAPI, em seguida, insira StartExecutionAPI para o APInome.

4. Mantenha o tipo de API endpoint como Regional e escolha Criar API.

Para criar um recurso

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

2. Na página Criar recurso, insira execution para Nome do recurso e, depois, selecione Criar recurso.

Como criar um método POST

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

2. Em Tipo de método, selecione POST.

3. Para Tipo de integração, escolha AWS serviço.

4. Para Região da AWS, escolha uma região na lista.

5. Para AWS service (Serviço da AWS), escolha Step Functions na lista.

6. Mantenha AWS subdomínio em branco.

7. Para HTTPmétodo, POSTescolha na lista.

   nota

   Todas as API ações do Step Functions usam o HTTP POST método.

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

9. Em Nome da ação, insira StartExecution.

10. Em Função de execução, insira a IAM função ARN da função que você criou anteriormente, conforme mostrado no exemplo a seguir.

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

11. 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 /execution - POST - Execução do método.

Etapa 3: testar e implantar o API gateway API

Depois de criar oAPI, teste e implante-o.

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

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

2. Na guia /execution - POST - Method Test, copie os seguintes parâmetros de solicitação na seção Corpo da solicitação usando o ARN de uma máquina de estado existente (ou crie uma nova máquina de estado que use uma função Lambda) e escolha Testar.

   {
      "input": "{}",
      "name": "MyExecution",
      "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:HelloWorld"
   }

   Para obter mais informações, consulte a Sintaxe da StartExecution Solicitação no AWS Step Functions APIReferência.

   nota

   Se você não quiser incluir a ARN da sua máquina de estado no corpo da chamada do API Gateway, você pode 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 exemplodev,test, eprod). Para obter mais informações sobre como especificar variáveis de estágio em um modelo de mapeamento, consulte $stageVariableso Guia do desenvolvedor do API Gateway.

3. A execução começa e a execução ARN e sua data de época são exibidas no corpo da resposta.

   {
      "executionArn": "arn:aws:states:us-east-1:123456789012:execution:HelloWorld:MyExecution",
      "startDate": 1486768956.878
   }

   nota

   Você pode ver a execução escolhendo sua máquina de estado na AWS Step Functions console.

Para implantar seu API

1. Na página de Recursos do StartExecutionAPI, escolha Implantar API.

2. Em Estágio, selecione Novo estágio.

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

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

5. Escolha Implantar.

Para testar sua implantação

1. Na página Stages do StartExecutionAPI, expanda alpha,/, /execution e POST, em seguida, escolha o POSTmétodo.

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

   https://a1b2c3d4e5.execute-api.us-east-1.amazonaws.com/alpha/execution

3. Na linha de comando, execute o curl comando usando o ARN da sua máquina de estado e, em seguida, invoque o URL da sua implantação, conforme mostrado no exemplo a seguir.

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

   A execução ARN e sua data de época são retornadas, conforme mostrado no exemplo a seguir.

   {"executionArn":"arn:aws:states:us-east-1:123456789012:execution:HelloWorld:MyExecution","startDate":1.486772644911E9}

   nota

   Se você receber um erro de “Token de autenticação ausente”, certifique-se de que a invocação URL termine com /execution.