本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 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 動作。

此教學課程說明如何使用一個資源和 `POST` 方法來建立 API，從而與 `[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 可以透過呼叫 來啟動 Step Functions 執行`StartExecution`，但您必須呼叫 `[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. 在 **Select trusted entity** (選取信任的實體) 頁面上，執行以下作業：

   1. 對於**信任的實體類型**，請保留 的預設選擇**AWS 服務**。

   1. 針對**使用案例**，從下拉式清單中選擇 **API Gateway**。

1. 選取 **API Gateway**，然後選擇**下一步**。

1. 在 **Add permissions** (新增許可) 頁面上，選擇 **Next** (下一步)。

1. （選用） 在**名稱、檢閱和建立**頁面上，輸入詳細資訊，例如角色名稱。例如，​輸入 **APIGatewayToStepFunctions**。

1. 選擇建**立角色**。

   IAM 角色會出現在角色清單中。

1. 選擇您角色的名稱，並記下 **Role ARN (角色 ARN)**，如以下範例所示。

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

**將政策連接至 IAM 角色**

1. 在 **Roles (角色)** 頁面上，搜尋您的角色 (`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**，然後輸入 **API 名稱**的 ***StartExecutionAPI***。

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 - Method execution** 頁面上。

## 步驟 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 - Method Execution** 頁面上，選擇**測試**索引標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

1. 在 **/execution - POST - Method Test** 索引標籤上，使用現有狀態機器的 ARN 將下列請求參數複製到**請求內文**區段 （或使用 [Lambda 函數建立新的狀態機器），](tutorial-creating-lambda-state-machine.md)然後選擇**測試**。

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

   如需詳細資訊，請參閱 *AWS Step FunctionsAPI 參考*中的`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 及其 epoch 日期會顯示在**回應內文**下方。

   ```
   {
      "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**、**/**、**/execution**、**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 及其 Epoch 日期，如以下範例所示。

   ```
   {"executionArn":"arn:aws:states:region:123456789012:execution:HelloWorld:MyExecution","startDate":1.486772644911E9}
   ```
**注意**  
如果您收到「缺少身分驗證字符」錯誤，請確定調用 URL 以 **/execution** 結尾。