使用同步快速狀態機器建立 API Gateway REST API AWS CDK - AWS Step Functions

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

使用同步快速狀態機器建立 API Gateway REST API AWS CDK

本教學課程說明如何建立具有同步快速狀態機的 API Gateway REST API,做為使用 AWS Cloud Development Kit (AWS CDK). 本教程將使用該StepFunctionsRestApi構造將狀態機連接到 API Gateway。該StepFunctionsRestApi構造將設置一個默認的輸入/輸出映射和 API Gateway REST API,具有所需的權限和 HTTP「任何」方法。這 AWS CDK 是一個基礎設施即代碼(IAC)框架,可以讓你使用一個完整的編程語言定義 AWS 基礎設施。您可以使用 CDK 支持的語言之一編寫應用程序,包含一個或多個堆棧,然後將其合成到 AWS CloudFormation 模板並將其部署到您 AWS 的帳戶中。我們將使用它來定義 API Gateway REST API,該 API 與同步快速狀態機整合為後端,然後使用 AWS Management Console 來啟動執行。

在開始學習本教學課程之前,請 AWS CDK 依照入門使用 AWS CDK -先決條件中所述設定您的開 AWS CDK發環境,然後發出以下指令來安裝:

npm install -g aws-cdk

步驟 1:設定您的 AWS CDK 專案

首先,為您的新 AWS CDK 應用程序創建一個目錄並初始化項目。

TypeScript
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language typescript
JavaScript
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language javascript
Python
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language python

專案初始化後,啟動專案的虛擬環境並安裝 AWS CDK的基準相依性。

source .venv/bin/activate python -m pip install -r requirements.txt
Java
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language java
C#
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language csharp
Go
mkdir stepfunctions-rest-api cd stepfunctions-rest-api cdk init --language go
注意

請務必命名目錄stepfunctions-rest-api。 AWS CDK 應用程式範本會使用目錄名稱來產生來源檔案和類別的名稱。若使用不同名稱,您的應用程式將與本教學課程不相符。

現在安裝構造庫模塊 AWS Step Functions 和 Amazon API Gateway。

TypeScript
npm install @aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
JavaScript
npm install @aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
Python
python -m pip install aws-cdk.aws-stepfunctions python -m pip install aws-cdk.aws-apigateway
Java

編輯專案的 pom.xml,在現有的 <dependencies> 容器內新增下列相依性。

<dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>stepfunctions</artifactId> <version>${cdk.version}</version> </dependency> <dependency> <groupId>software.amazon.awscdk</groupId> <artifactId>apigateway</artifactId> <version>${cdk.version}</version> </dependency>

Maven 會在您下次建立應用程式時自動安裝這些相依性。若要建置,發行 mvn compile 或使用您的 Java IDE 的 Build 命令。

C#
dotnet add src/StepfunctionsRestApi package Amazon.CDK.AWS.Stepfunctions dotnet add src/StepfunctionsRestApi package Amazon.CDK.AWS.APIGateway

您也可以使用 Visual Studio NuGet GUI 安裝指定的套件,可透過 [工具] > [Package 件管理] > NuGet [管理解決方案的 NuGet 套件] 取得。

安裝完模塊後,您可以通過導入以下軟件包在 AWS CDK 應用程序中使用它們。

TypeScript
@aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
JavaScript
@aws-cdk/aws-stepfunctions @aws-cdk/aws-apigateway
Python
aws_cdk.aws_stepfunctions aws_cdk.aws_apigateway
Java
software.amazon.awscdk.services.apigateway.StepFunctionsRestApi software.amazon.awscdk.services.stepfunctions.Pass software.amazon.awscdk.services.stepfunctions.StateMachine software.amazon.awscdk.services.stepfunctions.StateMachineType
C#
Amazon.CDK.AWS.StepFunctions Amazon.CDK.AWS.APIGateway
Go

將以下內容添加到import內部stepfunctions-rest-api.go

"github.com/aws/aws-cdk-go/awscdk/awsapigateway" "github.com/aws/aws-cdk-go/awscdk/awsstepfunctions"

步驟 2:使用建立具有同步快速狀態機後端整合的 API Gateway REST API AWS CDK

首先,我們將介紹定義同步快速狀態機器和 API Gateway REST API 的個別程式碼片段,然後說明如何將它們放在您的 AWS CDK 應用程式中。然後,您將看到如何合成和部署這些資源。

注意

我們將在這裡展示的狀態機將是一個簡單的狀態機Pass狀態。

建立快速狀態機

這是定義具有狀態的簡單狀態機的 AWS CDK Pass代碼。

TypeScript
const machineDefinition = new stepfunctions.Pass(this, 'PassState', { result: {value:"Hello!"}, }) const stateMachine = new stepfunctions.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, });
JavaScript
const machineDefinition = new sfn.Pass(this, 'PassState', { result: {value:"Hello!"}, }) const stateMachine = new sfn.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, });
Python
machine_definition = sfn.Pass(self,"PassState", result = sfn.Result("Hello")) state_machine = sfn.StateMachine(self, 'MyStateMachine', definition = machine_definition, state_machine_type = sfn.StateMachineType.EXPRESS)
Java
Pass machineDefinition = Pass.Builder.create(this, "PassState") .result(Result.fromString("Hello")) .build(); StateMachine stateMachine = StateMachine.Builder.create(this, "MyStateMachine") .definition(machineDefinition) .stateMachineType(StateMachineType.EXPRESS) .build();
C#
var machineDefinition = new Pass(this, "PassState", new PassProps { Result = Result.FromString("Hello") }); var stateMachine = new StateMachine(this, "MyStateMachine", new StateMachineProps { Definition = machineDefinition, StateMachineType = StateMachineType.EXPRESS });
Go
var machineDefinition = awsstepfunctions.NewPass(stack, jsii.String("PassState"), &awsstepfunctions.PassProps { Result: awsstepfunctions.NewResult(jsii.String("Hello")), }) var stateMachine = awsstepfunctions.NewStateMachine(stack, jsii.String("StateMachine"), &awsstepfunctions.StateMachineProps { Definition: machineDefinition, StateMachineType: awsstepfunctions.StateMachineType_EXPRESS, })

您可以在此簡短的程式碼片段中看到:

  • 名為的機器定義PassState,這是一個Pass狀態。

  • 狀態機的邏輯名稱,MyStateMachine.

  • 機器定義用作狀態機定義。

  • 狀態機器類型設定為,EXPRESSStepFunctionsRestApi為只允許同步快速狀態機。

若要使用建StepFunctionsRestApi構建立 API Gateway REST API

我們將使用StepFunctionsRestApi構造來創建具有所需權限和默認輸入/輸出映射的 API Gateway REST API。

TypeScript
const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine });
JavaScript
const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine });
Python
api = apigw.StepFunctionsRestApi(self, "StepFunctionsRestApi", state_machine = state_machine)
Java
StepFunctionsRestApi api = StepFunctionsRestApi.Builder.create(this, "StepFunctionsRestApi") .stateMachine(stateMachine) .build();
C#
var api = new StepFunctionsRestApi(this, "StepFunctionsRestApi", new StepFunctionsRestApiProps { StateMachine = stateMachine });
Go
awsapigateway.NewStepFunctionsRestApi(stack, jsii.String("StepFunctionsRestApi"), &awsapigateway.StepFunctionsRestApiProps { StateMachine = stateMachine, })

若要建置和部署 AWS CDK 應用程式

在您建立的 AWS CDK 專案中,編輯包含堆疊定義的檔案,使其看起來像下面的程式碼一樣。您將從上面識別 Step Functions 狀態機和 API Gateway 的定義。

TypeScript

更新 lib/stepfunctions-rest-api-stack.ts,讀取如下。

import * as cdk from 'aws-cdk-lib'; import * as stepfunctions from 'aws-cdk-lib/aws-stepfunctions' import * as apigateway from 'aws-cdk-lib/aws-apigateway'; export class StepfunctionsRestApiStack extends cdk.Stack { constructor(scope: cdk.App, id: string, props?: cdk.StackProps) { super(scope, id, props); const machineDefinition = new stepfunctions.Pass(this, 'PassState', { result: {value:"Hello!"}, }); const stateMachine = new stepfunctions.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, }); const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine });
JavaScript

更新 lib/stepfunctions-rest-api-stack.js,讀取如下。

const cdk = require('@aws-cdk/core'); const stepfunctions = require('@aws-cdk/aws-stepfunctions'); const apigateway = require('@aws-cdk/aws-apigateway'); class StepfunctionsRestApiStack extends cdk.Stack { constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) { super(scope, id, props); const machineDefinition = new stepfunctions.Pass(this, "PassState", { result: {value:"Hello!"}, }) const stateMachine = new sfn.StateMachine(this, 'MyStateMachine', { definition: machineDefinition, stateMachineType: stepfunctions.StateMachineType.EXPRESS, }); const api = new apigateway.StepFunctionsRestApi(this, 'StepFunctionsRestApi', { stateMachine: stateMachine }); } } module.exports = { StepStack }
Python

更新 stepfunctions_rest_api/stepfunctions_rest_api_stack.py,讀取如下。

from aws_cdk import App, Stack from constructs import Construct from aws_cdk import aws_stepfunctions as sfn from aws_cdk import aws_apigateway as apigw class StepfunctionsRestApiStack(Stack): def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None: super().__init__(scope, construct_id, **kwargs) machine_definition = sfn.Pass(self,"PassState", result = sfn.Result("Hello")) state_machine = sfn.StateMachine(self, 'MyStateMachine', definition = machine_definition, state_machine_type = sfn.StateMachineType.EXPRESS) api = apigw.StepFunctionsRestApi(self, "StepFunctionsRestApi", state_machine = state_machine)
Java

更新 src/main/java/com.myorg/StepfunctionsRestApiStack.java,讀取如下。

package com.myorg; import software.amazon.awscdk.core.Construct; import software.amazon.awscdk.core.Stack; import software.amazon.awscdk.core.StackProps; import software.amazon.awscdk.services.stepfunctions.Pass; import software.amazon.awscdk.services.stepfunctions.StateMachine; import software.amazon.awscdk.services.stepfunctions.StateMachineType; import software.amazon.awscdk.services.apigateway.StepFunctionsRestApi; public class StepfunctionsRestApiStack extends Stack { public StepfunctionsRestApiStack(final Construct scope, final String id) { this(scope, id, null); } public StepfunctionsRestApiStack(final Construct scope, final String id, final StackProps props) { super(scope, id, props); Pass machineDefinition = Pass.Builder.create(this, "PassState") .result(Result.fromString("Hello")) .build(); StateMachine stateMachine = StateMachine.Builder.create(this, "MyStateMachine") .definition(machineDefinition) .stateMachineType(StateMachineType.EXPRESS) .build(); StepFunctionsRestApi api = StepFunctionsRestApi.Builder.create(this, "StepFunctionsRestApi") .stateMachine(stateMachine) .build(); } }
C#

更新 src/StepfunctionsRestApi/StepfunctionsRestApiStack.cs,讀取如下。

using Amazon.CDK; using Amazon.CDK.AWS.StepFunctions; using Amazon.CDK.AWS.APIGateway; namespace StepfunctionsRestApi { public class StepfunctionsRestApiStack : Stack { internal StepfunctionsRestApi(Construct scope, string id, IStackProps props = null) : base(scope, id, props) { var machineDefinition = new Pass(this, "PassState", new PassProps { Result = Result.FromString("Hello") }); var stateMachine = new StateMachine(this, "MyStateMachine", new StateMachineProps { Definition = machineDefinition, StateMachineType = StateMachineType.EXPRESS }); var api = new StepFunctionsRestApi(this, "StepFunctionsRestApi", new StepFunctionsRestApiProps { StateMachine = stateMachine }); } } }
Go

更新 stepfunctions-rest-api.go,讀取如下。

package main import ( "github.com/aws/aws-cdk-go/awscdk" "github.com/aws/aws-cdk-go/awscdk/awsapigateway" "github.com/aws/aws-cdk-go/awscdk/awsstepfunctions" "github.com/aws/constructs-go/constructs/v3" "github.com/aws/jsii-runtime-go" ) type StepfunctionsRestApiGoStackProps struct { awscdk.StackProps } func NewStepfunctionsRestApiGoStack(scope constructs.Construct, id string, props *StepfunctionsRestApiGoStackProps) awscdk.Stack { var sprops awscdk.StackProps if props != nil { sprops = props.StackProps } stack := awscdk.NewStack(scope, &id, &sprops) // The code that defines your stack goes here var machineDefinition = awsstepfunctions.NewPass(stack, jsii.String("PassState"), &awsstepfunctions.PassProps { Result: awsstepfunctions.NewResult(jsii.String("Hello")), }) var stateMachine = awsstepfunctions.NewStateMachine(stack, jsii.String("StateMachine"), &awsstepfunctions.StateMachineProps{ Definition: machineDefinition, StateMachineType: awsstepfunctions.StateMachineType_EXPRESS, }); awsapigateway.NewStepFunctionsRestApi(stack, jsii.String("StepFunctionsRestApi"), &awsapigateway.StepFunctionsRestApiProps{ StateMachine = stateMachine, }) return stack } func main() { app := awscdk.NewApp(nil) NewStepfunctionsRestApiGoStack(app, "StepfunctionsRestApiGoStack", &StepfunctionsRestApiGoStackProps{ awscdk.StackProps{ Env: env(), }, }) app.Synth(nil) } // env determines the AWS environment (account+region) in which our stack is to // be deployed. For more information see: https://docs.aws.amazon.com/cdk/latest/guide/environments.html func env() *awscdk.Environment { // If unspecified, this stack will be "environment-agnostic". // Account/Region-dependent features and context lookups will not work, but a // single synthesized template can be deployed anywhere. //--------------------------------------------------------------------------- return nil // Uncomment if you know exactly what account and region you want to deploy // the stack to. This is the recommendation for production stacks. //--------------------------------------------------------------------------- // return &awscdk.Environment{ // Account: jsii.String("123456789012"), // Region: jsii.String("us-east-1"), // } // Uncomment to specialize this stack for the AWS Account and Region that are // implied by the current CLI configuration. This is recommended for dev // stacks. //--------------------------------------------------------------------------- // return &awscdk.Environment{ // Account: jsii.String(os.Getenv("CDK_DEFAULT_ACCOUNT")), // Region: jsii.String(os.Getenv("CDK_DEFAULT_REGION")), // } }

保存來源檔案,然後在應用程式的主目錄中發行 cdk synth。 AWS CDK 運行應用程序並從中合成 AWS CloudFormation 模板,然後顯示模板。

若要將 Amazon API Gateway 和 AWS Step Functions 狀態機器實際部署到您的 AWS 帳戶,請發出問題cdk deploy。系統會要求您核准 AWS CDK 已產生的 IAM 政策。正在建立的政策看起來會像這樣:

步驟 3:測試 API Gateway

使用同步快速狀態機做為後端整合建立 API Gateway REST API 之後,您可以測試 API Gateway。

使用 API Gateway 主控台測試已部署的 API Gateway

  1. 開啟 Amazon API Gateway 主控台並登入。

  2. 選擇名為的其他 API StepFunctionsRestApi

  3. 在「資」窗格中,選擇ANY方法。

  4. 選擇測試標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

  5. 針對 Method (方法) 選擇 POST

  6. 針對要求主體,複製下列要求參數。

    { "key": "Hello" }
  7. 選擇 Test (測試)。下列資訊會隨即顯示:

    • Request (請求) 是針對方法所呼叫的資源路徑。

    • Status (狀態) 是回應的 HTTP 狀態碼。

    • Latency (延遲) 是從發起人收到請求到傳回回應之間的時間。

    • 回應內文是 HTTP 回應內文。

    • 回應標頭是 HTTP 回應標頭。

    • CloudWatch 日顯示如果在 API Gateway 主控台外呼叫此方法,則會寫入的模擬 Amazon 日誌項目。

      注意

      雖然 CloudWatch 日誌條目是模擬的,但方法調用的結果是真實的。

響應正文輸出應該是這樣的:

"Hello"
提示

嘗試使用不同的方法和無效的輸入來查看錯誤輸出的 API Gateway。您可能需要更改狀態機以查找特定密鑰,並在測試期間提供錯誤的密鑰以使狀態機執行失敗,並在響應體輸出中生成錯誤消息。

使用 cURL 測試已部署的 API

  1. 開啟終端機視窗。

  2. 複製以下 cURL 命令,並將它貼到終端機視窗,同時將 <api-id> 取代為您 API 的 API ID,以及將 <region> 取代為 API 的部署區域。

    curl -X POST\ 'https://<api-id>.execute-api.<region>.amazonaws.com/prod' \ -d '{"key":"Hello"}' \ -H 'Content-Type: application/json'

響應體輸出應該是這樣的:

"Hello"
提示

嘗試使用不同的方法和無效的輸入來查看錯誤輸出的 API Gateway。您可能需要更改狀態機以查找特定密鑰,並在測試期間提供錯誤的密鑰以使狀態機執行失敗,並在響應主體輸出中生成錯誤消息。

步驟 4:清除

嘗試完 API Gateway 後,您可以使用 AWS CDK 拆除狀態機器和 API Gateway。在您的應用程式的主目錄中發行 cdk destroy