本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 API Gateway 创建 Step Functions API
<a name="tutorial-api-gateway"></a>

您可以使用 Amazon API Gateway 将您AWS Step FunctionsAPIs 与 API Gateway API 中的方法关联起来。在 HTTPS 请求发送到 API 方法后，API Gateway 将会调用您的 Step Functions API 操作。

本教程说明如何创建 API 来使用一个资源和 `POST` 方法与 `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API 操作进行通信。您将使用 AWS Identity and Access Management (IAM) 控制台为 API Gateway 创建角色。然后，您将使用 API Gateway 控制台创建 API Gateway API，创建资源和方法，并将方法映射到 `StartExecution` API 操作。最后，您将部署和测试您的 API。

**注意**  
虽然 Amazon API Gateway 可以通过调用 `StartExecution` 启动 Step Functions 执行，但您必须调用 `[DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html)` 才能获得结果。

## 第 1 步：为 API Gateway 创建 IAM 角色
<a name="api-gateway-step-1"></a>

在创建您的 API Gateway API 之前，您需要向 API Gateway 授予调用 Step Functions API 操作的权限。<a name="api-gateway-procedure-create-iam-role"></a>

**为 API Gateway 设置权限**

1. 登录到 [IAM 控制台](https://console.aws.amazon.com/iam/home)，然后依次选择**角色**、**创建角色**。

1. 在**选择受信任的实体**页面上，请执行以下操作：

   1. 对于**可信实体类型**，保留 **AWS 服务**的默认选择。

   1. 对于**使用案例**，从下拉菜单中选择 **API Gateway**。

1. 选择 **API Gateway**，然后选择**下一步**。

1. 在**添加权限**页面上，选择**下一步**。

1. （可选）在**名称、查看和创建**页面上，输入角色名称等详细信息。例如，输入 **APIGatewayToStepFunctions**。

1. 选择**创建角色**。

   IAM 角色显示在角色列表中。

1. 选择角色的名称并记下**角色 ARN**，如以下示例所示。

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

**将策略附加到 IAM 角色**

1. 在**角色**页面上，搜索您的角色 (`APIGatewayToStepFunctions`)，然后选择该角色。

1. 在**权限**选项卡上，选择**添加权限**，然后选择**附加策略**。

1. 在**附加策略**页面上，搜索 `AWSStepFunctionsFullAccess`，选择该策略，然后选择**添加权限**。

## 第 2 步：创建 API Gateway API
<a name="api-gateway-step-2"></a>

在创建 IAM 角色后，您可以创建自定义 API Gateway API。

**创建 API**

1. 打开 [Amazon API Gateway 控制台](https://console.aws.amazon.com/apigateway/)，然后选择**创建 API**。

1. 在**选择 API 类型**页面上的 **REST API** 窗格中，选择**构建**。

1. 在 “**创建 REST API**” 页面上，选择 “**新建 API**”，然后输入 ***StartExecutionAPI*** **API 名称**。

1. 将 **API 端点类型**保留为**区域性**，然后选择**创建 API**。<a name="api-gateway-create-resource"></a>

**创建资源**

1. 在的**资源**页面上***StartExecutionAPI***，选择**创建资源**。

1. 在**创建资源**页面上，输入 **execution** 作为**资源名称**，然后选择**创建资源**。<a name="api-gateway-create-method"></a>

**创建 POST 方法**

1. 选择 **/execution** 资源，然后选择**创建方法**。

1. 对于**方法类型**，选择 `POST`。

1. 对于**集成类型**，选择 **AWS 服务**。

1. 对于 **AWS 区域**，从列表中选择一个区域。

1. 对于 **AWS 服务**，从列表中选择 **Step Functions**。

1. 将 **AWS 子域**保留为空白。

1. 对于 **HTTP 方法**，从列表中选择 **POST**。
**注意**  
所有 Step Functions API 操作都使用 HTTP `POST` 方法。

1. 对于**操作类型**，选择**使用操作名称**。

1. 对于**操作名称**，输入 **StartExecution**。

1. 对于**执行角色**，输入[您之前创建的 IAM 角色的角色 ARN](#api-gateway-procedure-create-iam-role)，如以下示例所示。

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

1. 对于**凭证缓存**和**默认超时**，保留默认选项，然后选择**保存**。

API Gateway 与 Step Functions 之间的可视映射显示在 **/execution - POST - 方法执行**页面上。

## 第 3 步：测试和部署 API Gateway API
<a name="api-gateway-step-3"></a>

创建 API 后，您可以测试和部署它。<a name="api-gateway-test-api"></a>

**测试 API Gateway 和 Step Functions 之间的通信**

1. 在 **/execution - POST - 方法执行**页面上，选择**测试**选项卡。您可能需要选择右箭头按钮，以显示该选项卡。

1. 在 **/execution - POST - 方法测试**选项卡上，使用现有状态机的 ARN 将以下请求参数复制到**请求正文**部分（或者[创建使用 Lambda 函数的新状态机](tutorial-creating-lambda-state-machine.md)），然后选择**测试**。

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

   有关更多信息，请参阅**《AWS Step Functions API 参考》中的 `StartExecution` [请求语法](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html#API_StartExecution_RequestSyntax)。
**注意**  
如果您不希望在 API Gateway 调用正文中包含状态机的 ARN，可以在**集成请求**选项卡中配置映射模板，如以下示例所示。  

   ```
   {
       "input": "$util.escapeJavaScript($input.json('$'))",
       "stateMachineArn": "$util.escapeJavaScript($stageVariables.arn)"
   }
   ```
使用这种方法，您可以根据自己的开发阶段指定 ARNs 不同的状态机（例如`dev``test`、和`prod`）。有关在映射模板中指定阶段变量的更多信息，请参阅**《API Gateway 开发者指南》中的 [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)。

1. 执行将会启动，并且执行 ARN 及其纪元日期显示在**响应正文**下。

   ```
   {
      "executionArn": "arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution",
      "startDate": 1486768956.878
   }
   ```
**注意**  
可以通过在 [AWS Step Functions 控制台](https://console.aws.amazon.com/states/)上选择您的状态机来查看执行。

**部署 API**

1. 在的**资源**页面上***StartExecutionAPI***，选择**部署 API**。

1. 对于**阶段**，选择**新建阶段**。

1. 对于**阶段名称**，输入 **alpha**。

1. （可选）对于**描述**，输入描述。

1. 选择**部署**。

**测试部署**

1. 在 “**阶段**” 页面上***StartExecutionAPI***，展开 **alpha**、**/**、**/exec** ution、**POST**，然后选择 **POST** 方法。

1. 在**方法覆盖**下，选择复制图标以复制您 API 的调用 URL。完整 URL 应类似于以下示例。

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

1. 在命令行中，使用您状态机的 ARN 运行 `curl` 命令，然后调用您的部署的 URL，如以下示例所示。

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

   将返回执行 ARN 及其纪元日期，如以下示例所示。

   ```
   {"executionArn":"arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution","startDate":1.486772644911E9}
   ```
**注意**  
如果您收到“缺少身份验证令牌”错误，请确保调用 URL 以 **/execution** 结尾。