AWSハンズオン - Step Functions + Lambda で受注処理ワークフローをSAMで構築しよう【コンソール版との比較付き】

はじめに

「複数のLambda関数をオーケストレーションするワークフローを、コードで管理したい」という要件に、AWS SAM（Serverless Application Model） は最適な選択肢のひとつです。

この記事では、AWS SAM を使って、受注処理ワークフロー（注文検証 → 在庫確認・支払い並列処理 → 注文確定）をゼロから構築するハンズオンを紹介します。

入力: {"order_id": "ORD-001", "item_id": "item-001", "quantity": 2}
  ↓
[ValidateOrder] 注文検証（Retry + Catch）
  ↓ 成功
[ProcessInParallel] 並列処理（Catch）
  ├─ [CheckInventory] 在庫確認
  └─ [ProcessPayment] 支払い処理
  ↓ 成功（結果リスト: [inventory_result, payment_result]）
[ConfirmOrder] 注文確定
  ↓
終了（成功）

[HandleError] エラー処理（Catch 先）
  ↓
終了（エラー通知済み）

このハンズオンで体験できること：

• AWS::Serverless::StateMachine を使った Step Functions の SAM 定義
• DefinitionSubstitutions で ASL 内の Lambda ARN を 自動差し込みする仕組み
• LambdaInvokePolicy による1行での権限付与（コンソール版ではIAMロールを自動生成）
• CLI でのテスト実行 + コンソールの実行グラフで視覚的に確認

このハンズオンの特徴：

• sam build + sam deploy の 2コマンドで全リソースをデプロイ
• Step Functions（ステートマシン）+ Lambda × 5 + IAM ロール × 6 を template.yaml 1ファイルで管理
• sam delete で全リソースを一括削除（コンソール版では5つのLambda・ステートマシン・IAMロールを個別に削除）

Amazon検索[本 AWS 開発]

SAM vs コンソール：どれだけ違うか

キーワード解説

前提条件

aws sts get-caller-identity

アカウントIDが表示されれば認証設定済みです。

使用するAWSサービス

Step 1: プロジェクトフォルダを開く

cd C:\my-aws\aws-learning-projects\step-functions-lambda

フォルダ構造

step-functions-lambda/
├── template.yaml           # SAMテンプレート（Step Functions + Lambda 定義）
├── samconfig.toml          # デプロイ設定（gitignore 対象・毎回手動作成が必要）
├── docs/
│   ├── 1_console.md        # AWSコンソール版手順
│   └── 2_sam.md            # SAM版手順
└── src/
    ├── validate.py         # 注文検証 Lambda
    ├── inventory.py        # 在庫確認 Lambda
    ├── payment.py          # 支払い処理 Lambda
    ├── confirm.py          # 注文確定 Lambda
    └── error_handler.py    # エラー処理 Lambda

Step 2: SAMテンプレートの確認（template.yaml）

template.yaml は全 AWSリソースの設計図です。ポイントを確認しておきます。

Lambda 関数の定義

Globals:
  Function:
    Runtime: python3.12
    Timeout: 10
    MemorySize: 128

Resources:
  ValidateFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/           # src/ 配下の全 .py を1つのパッケージとしてデプロイ
      Handler: validate.lambda_handler

  InventoryFunction:          # 在庫確認（Parallel ブランチ 1）
  PaymentFunction:            # 支払い処理（Parallel ブランチ 2）
  ConfirmFunction:            # 注文確定
  ErrorHandlerFunction:       # エラー処理（Catch 先）

ポイント: 5つの Lambda 関数が全て CodeUri: src/ を共有しています。SAM は src/ フォルダを1つの ZIP パッケージとして S3 にアップロードし、各関数は Handler でどのファイル・関数を使うかを指定します。

ステートマシンの定義

  OrderWorkflow:
    Type: AWS::Serverless::StateMachine
    Properties:
      Type: STANDARD
      Definition:
        StartAt: ValidateOrder
        States:
          ValidateOrder:
            Type: Task
            Resource: "${ValidateFunctionArn}"   # DefinitionSubstitutions で実際の ARN に置換
            Next: ProcessInParallel
            Retry:
              - ErrorEquals: [States.ALL]
                IntervalSeconds: 2
                MaxAttempts: 1
                BackoffRate: 2.0
            Catch:
              - ErrorEquals: [States.ALL]
                Next: HandleError
                ResultPath: "$.error"

          ProcessInParallel:
            Type: Parallel
            Branches:
              - StartAt: CheckInventory
                States:
                  CheckInventory:
                    Type: Task
                    Resource: "${InventoryFunctionArn}"
                    End: true
              - StartAt: ProcessPayment
                States:
                  ProcessPayment:
                    Type: Task
                    Resource: "${PaymentFunctionArn}"
                    End: true
            Next: ConfirmOrder
            Catch:
              - ErrorEquals: [States.ALL]
                Next: HandleError
                ResultPath: "$.error"

          ConfirmOrder:
            Type: Task
            Resource: "${ConfirmFunctionArn}"
            End: true

          HandleError:
            Type: Task
            Resource: "${ErrorHandlerFunctionArn}"
            End: true

      DefinitionSubstitutions:           # ${変数名} を実際の ARN に自動置換
        ValidateFunctionArn: !GetAtt ValidateFunction.Arn
        InventoryFunctionArn: !GetAtt InventoryFunction.Arn
        PaymentFunctionArn: !GetAtt PaymentFunction.Arn
        ConfirmFunctionArn: !GetAtt ConfirmFunction.Arn
        ErrorHandlerFunctionArn: !GetAtt ErrorHandlerFunction.Arn

      Policies:                          # ステートマシンが Lambda を呼び出す IAM 権限
        - LambdaInvokePolicy:
            FunctionName: !Ref ValidateFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref InventoryFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref PaymentFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref ConfirmFunction
        - LambdaInvokePolicy:
            FunctionName: !Ref ErrorHandlerFunction

template.yaml のポイント解説

Step 3: Lambda コードの確認（src/）

各ファイルの役割を確認しておきます。

各 Python コードの全文はコンソール版記事を参照してください。
SAM版・コンソール版で使用する Lambda コードは共通です。コンソール版では各関数ごとにコードを貼り付ける手順とあわせて全文を掲載しています。

→ AWSコンソールだけでStep Functions + Lambdaワークフローを構築する手順【SAM版との比較付き / 新UI対応】

confirm.py の event[0] / event[1] について：
Parallel ステートが成功すると、各ブランチの出力が**配列（リスト）**にまとめられて次のステートに渡されます。このため ConfirmFunction は event[0] で在庫確認結果、event[1] で支払い結果にアクセスしています。この仕様を知らないと list indices must be integers エラーで詰まります。

Step 4: samconfig.toml を作成する

samconfig.toml は .gitignore で管理外のため、毎回手動で作成する必要があります。

step-functions-lambda/samconfig.toml を新規作成して以下を貼り付けます。

version = 0.1

[default.deploy.parameters]
stack_name = "step-functions-lambda-stack"
resolve_s3 = true
s3_prefix = "step-functions-lambda-stack"
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_IAM"
disable_rollback = true
image_repositories = []

[default.global.parameters]
region = "ap-northeast-1"

samconfig.toml の置き場所：
step-functions-lambda/ フォルダの直下に置く必要があります。

Step 5: sam build（ビルド）

cd C:\my-aws\aws-learning-projects\step-functions-lambda
sam build

成功すると以下のように表示されます。

Build Succeeded

Built Artifacts  : .aws-sam/build
Built Template   : .aws-sam/build/template.yaml

sam build が行っていること：

• src/ フォルダを ZIP パッケージ化して .aws-sam/build/ に配置
• template.yaml を .aws-sam/build/template.yaml にコピー
• Lambda デプロイの準備を整える

Step 6: sam deploy（デプロイ）

sam deploy

変更内容が表示されて確認を求められます。

Deploy this changeset? [y/N]: y

y を入力して進めます。数分でデプロイが完了します。

デプロイ完了の確認

ターミナルに Outputs が表示されます。

Outputs
----------------------------------------------------------------------
Key    OrderWorkflowArn
Value  arn:aws:states:ap-northeast-1:123456789012:stateMachine:step-functions-lambda-stack-order-workflow

Key    OrderWorkflowName
Value  step-functions-lambda-stack-order-workflow
----------------------------------------------------------------------

OrderWorkflowArn を控えておきます。（テスト実行コマンドで使用）

デプロイされるリソース一覧

Step Functions ステートマシン × 1  : step-functions-lambda-stack-order-workflow
Lambda 関数 × 5                    : step-functions-lambda-stack-ValidateFunction-XXXX 他
IAM ロール × 6                     : ステートマシン用 × 1 / Lambda 用 × 5
S3                                 : SAM デプロイパッケージ
CloudWatch Logs                    : Lambda 自動生成ログ × 5

Step 7: 動作テスト

事前準備: ARN を変数に設定する

set SM_ARN=arn:aws:states:ap-northeast-1:123456789012:stateMachine:step-functions-lambda-stack-order-workflow

123456789012 を自分のアカウントIDに置き換えてください（Outputs の値をそのままコピーすればよいです）。

テスト1: 正常処理

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-normal-1" ^
  --input "{\"order_id\": \"ORD-001\", \"item_id\": \"item-001\", \"quantity\": 2}" ^
  --region ap-northeast-1

レスポンス例:

{
    "executionArn": "arn:aws:states:ap-northeast-1:123456789012:execution:...:test-normal-1",
    "startDate": "2026-03-01T10:00:00.000000+09:00"
}

実行結果を確認（数秒後）:

aws stepfunctions describe-execution ^
  --execution-arn "上記の executionArn" ^
  --region ap-northeast-1

"status": "SUCCEEDED" と以下のような出力が表示されます。

{
  "order_id": "ORD-001",
  "item_id": "item-001",
  "quantity": 2,
  "amount": 2000,
  "confirmed_at": "2026-03-01T01:00:00.000000+00:00",
  "status": "confirmed"
}

AWSコンソールで実行グラフを確認（任意）:

Step Functions → ステートマシン → step-functions-lambda-stack-order-workflow → 実行一覧 → test-normal-1 をクリックすると、全ステートが緑色になり ProcessInParallel の2ブランチが同時に実行されたことを視覚的に確認できます。

テスト2: 在庫切れエラー（ProcessInParallel Catch の確認）

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-inventory-error" ^
  --input "{\"order_id\": \"ORD-002\", \"item_id\": \"item-999\", \"quantity\": 1}" ^
  --region ap-northeast-1

期待する動作:

1. ValidateOrder → 成功
2. ProcessInParallel → CheckInventory が ValueError（在庫切れ）を発生させる
3. ProcessInParallel の Catch が動作 → HandleError へ遷移
4. 実行ステータス: SUCCEEDED（HandleError が正常完了）

出力例:

{
  "status": "error",
  "error_type": "ValueError",
  "error_cause": "在庫不足: item_id=item-999",
  "original_input": {
    "order_id": "ORD-002",
    "item_id": "item-999",
    "quantity": 1,
    "validated": true
  }
}

実行ステータスが SUCCEEDED になる理由：
HandleError 関数が正常終了（return result）しているため、ステートマシン全体としては「成功」扱いになります。エラーが「処理されずに残った」場合は FAILED になります。

テスト3: 支払い失敗エラー（ProcessInParallel Catch の確認）

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-payment-error" ^
  --input "{\"order_id\": \"ORD-003\", \"item_id\": \"item-001\", \"quantity\": 2, \"fail_payment\": true}" ^
  --region ap-northeast-1

ProcessPayment が RuntimeError を発生させ、同様に HandleError へ遷移します。

テスト4: 検証エラー（ValidateOrder Retry + Catch の確認）

aws stepfunctions start-execution ^
  --state-machine-arn %SM_ARN% ^
  --name "test-validate-error" ^
  --input "{\"item_id\": \"item-001\", \"quantity\": 2}" ^
  --region ap-northeast-1

order_id を省略しているため ValidateOrder が ValueError を発生させます。

Retry の確認（AWSコンソール）:

Step Functions コンソールの実行グラフで ValidateOrder を選択 → 「イベント」タブ で以下の順序を確認します：

TaskStateEntered → TaskScheduled → TaskStarted → TaskFailed
  → TaskScheduled（リトライ1回目）→ TaskStarted → TaskFailed
  → TaskStateExited（Catch 発動）→ HandleError へ

ValidateFunction が合計2回呼ばれてから HandleError へ遷移することが分かります。

Step 8: AWSコンソールで確認（任意）

SAMでデプロイしたリソースはコンソールで確認できます。

• Step Functions: ステートマシン一覧 → step-functions-lambda-stack-order-workflow → 各実行のグラフを確認
• Lambda: Lambda → 関数 → step-functions-lambda-stack-ValidateFunction-XXXX → 「モニタリング」→ 呼び出し回数を確認
• CloudWatch Logs: Lambda → 対象関数 → 「モニタリング」タブ → 「CloudWatch Logs を表示」

Step 9: リソースの削除

課金を止めるために、ハンズオン完了後は必ずリソースを削除してください。

sam delete --stack-name step-functions-lambda-stack --region ap-northeast-1

対話式で確認が入ります。両方 y で進めます。

Are you sure you want to delete the stack step-functions-lambda-stack? [y/N]: y
Are you sure you want to delete the folder step-functions-lambda-stack in S3? [y/N]: y

削除完了の確認

aws cloudformation describe-stacks --stack-name step-functions-lambda-stack --region ap-northeast-1

An error occurred (ValidationError): Stack with id step-functions-lambda-stack does not exist

このメッセージが表示されれば削除完了です。

sam delete で削除されるリソース一覧

コンソール版との大きな違い（SAMのメリット）：
コンソール版では Lambda × 5 / ステートマシン / IAM ロール × 6 / ロググループを個別に削除する必要があります。
SAMでは sam delete 1コマンドで全リソースを一括削除できます。

トラブルシューティング

まとめ

今回のハンズオンで実現したこと：

SAMのメリットを実感できたポイント

• DefinitionSubstitutions により Lambda ARN のコピー貼り付けが不要
• LambdaInvokePolicy × 5 で IAM 権限設定が1行ずつで完結
• sam delete でステートマシン・Lambda 5つ・IAM ロール 6つを一括削除

コンソール版と比較してみる

SAMが裏で何をやっているか、同じ構成をAWSコンソールのみで構築する手順をまとめました。Workflow Studioの新UI（3択モーダル・「{ } コード」タブ）での操作方法や、コンソール版ならではのつまずきポイントを解説しています。

関連記事

Amazon検索[本 AWS 開発]