step-functions

AWS Step Functions

AWS Step Functions は、ステートマシンを使用してワークフローを構築、実行できるサーバーレスオーケストレーションサービスです。複数の AWS サービスを連携させ、ビジネスに不可欠なアプリケーションを構築できます。

目次

• コアコンセプト
• 一般的なパターン
• CLI リファレンス
• ベストプラクティス
• トラブルシューティング
• 参考資料

コアコンセプト

ワークフローの種類

種類	説明	料金
Standard	長時間実行可能で耐久性があり、厳密に1回だけ実行	状態遷移ごと
Express	高ボリューム、短時間	実行ごと（時間＋メモリ）

状態の種類

状態	説明
Task	処理を実行します（Lambda、API 呼び出し）
Choice	条件分岐
Parallel	分岐を同時に実行します
Map	配列を反復処理します
Wait	実行を遅延させます
Pass	入力を出力に渡します
Succeed	正常に終了します
Fail	失敗して終了します

Amazon States Language（ASL）

ステートマシンを定義するための JSON ベースの言語です。

一般的なパターン

シンプルな Lambda ワークフロー

{
  "Comment": "Process order workflow",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:ValidateOrder",
      "Next": "ProcessPayment"
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:ProcessPayment",
      "Next": "FulfillOrder"
    },
    "FulfillOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:FulfillOrder",
      "End": true
    }
  }
}

ステートマシンの作成

AWS CLI：

aws stepfunctions create-state-machine \
  --name OrderWorkflow \
  --definition file://workflow.json \
  --role-arn arn:aws:iam::123456789012:role/StepFunctionsRole \
  --type STANDARD

boto3：

import boto3
import json

sfn = boto3.client('stepfunctions')

definition = {
    "Comment": "Order workflow",
    "StartAt": "ProcessOrder",
    "States": {
        "ProcessOrder": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:...",
            "End": True
        }
    }
}

response = sfn.create_state_machine(
    name='OrderWorkflow',
    definition=json.dumps(definition),
    roleArn='arn:aws:iam::123456789012:role/StepFunctionsRole',
    type='STANDARD'
)

実行の開始

import boto3
import json

sfn = boto3.client('stepfunctions')

response = sfn.start_execution(
    stateMachineArn='arn:aws:states:us-east-1:123456789012:stateMachine:OrderWorkflow',
    name='order-12345',
    input=json.dumps({
        'order_id': '12345',
        'customer_id': 'cust-789',
        'items': [{'product_id': 'prod-1', 'quantity': 2}]
    })
)

execution_arn = response['executionArn']

Choice 状態（条件ロジック）

{
  "StartAt": "CheckOrderValue",
  "States": {
    "CheckOrderValue": {
      "Type": "Choice",
      "Choices": [
        {
          "Variable": "$.total",
          "NumericGreaterThan": 1000,
          "Next": "HighValueOrder"
        },
        {
          "Variable": "$.priority",
          "StringEquals": "rush",
          "Next": "RushOrder"
        }
      ],
      "Default": "StandardOrder"
    },
    "HighValueOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessHighValue",
      "End": true
    },
    "RushOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessRush",
      "End": true
    },
    "StandardOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:ProcessStandard",
      "End": true
    }
  }
}

並列実行

{
  "StartAt": "ProcessInParallel",
  "States": {
    "ProcessInParallel": {
      "Type": "Parallel",
      "Branches": [
        {
          "StartAt": "UpdateInventory",
          "States": {
            "UpdateInventory": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:UpdateInventory",
              "End": true
            }
          }
        },
        {
          "StartAt": "SendNotification",
          "States": {
            "SendNotification": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:SendNotification",
              "End": true
            }
          }
        },
        {
          "StartAt": "UpdateAnalytics",
          "States": {
            "UpdateAnalytics": {
              "Type": "Task",
              "Resource": "arn:aws:lambda:...:function:UpdateAnalytics",
              "End": true
            }
          }
        }
      ],
      "Next": "Complete"
    },
    "Complete": {
      "Type": "Succeed"
    }
  }
}

Map 状態（反復処理）

{
  "StartAt": "ProcessItems",
  "States": {
    "ProcessItems": {
      "Type": "Map",
      "ItemsPath": "$.items",
      "MaxConcurrency": 10,
      "Iterator": {
        "StartAt": "ProcessItem",
        "States": {
          "ProcessItem": {
            "Type": "Task",
            "Resource": "arn:aws:lambda:...:function:ProcessItem",
            "End": true
          }
        }
      },
      "ResultPath": "$.processedItems",
      "End": true
    }
  }
}

エラー処理

{
  "StartAt": "ProcessWithRetry",
  "States": {
    "ProcessWithRetry": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:Process",
      "Retry": [
        {
          "ErrorEquals": ["Lambda.ServiceException", "Lambda.TooManyRequestsException"],
          "IntervalSeconds": 2,
          "MaxAttempts": 6,
          "BackoffRate": 2
        },
        {
          "ErrorEquals": ["States.Timeout"],
          "IntervalSeconds": 5,
          "MaxAttempts": 3,
          "BackoffRate": 1.5
        }
      ],
      "Catch": [
        {
          "ErrorEquals": ["CustomError"],
          "ResultPath": "$.error",
          "Next": "HandleCustomError"
        },
        {
          "ErrorEquals": ["States.ALL"],
          "ResultPath": "$.error",
          "Next": "HandleAllErrors"
        }
      ],
      "End": true
    },
    "HandleCustomError": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:...:function:HandleCustom",
      "End": true
    },
    "HandleAllErrors": {
      "Type": "Fail",
      "Error": "ProcessingFailed",
      "Cause": "An error occurred during processing"
    }
  }
}

CLI リファレンス

ステートマシンの管理

コマンド	説明
aws stepfunctions create-state-machine	ステートマシンを作成します
aws stepfunctions update-state-machine	定義を更新します
aws stepfunctions delete-state-machine	ステートマシンを削除します
aws stepfunctions list-state-machines	ステートマシンの一覧を表示します
aws stepfunctions describe-state-machine	詳細を取得します

実行

コマンド	説明
aws stepfunctions start-execution	実行を開始します
aws stepfunctions stop-execution	実行を停止します
aws stepfunctions describe-execution	実行の詳細を取得します
aws stepfunctions list-executions	実行の一覧を表示します
aws stepfunctions get-execution-history	実行履歴を取得します

ベストプラクティス

設計

• 状態の役割を絞ります — 1つの状態につき1つの目的にします
• 意味のある状態名を使用します
• 包括的なエラー処理を実装します
• 独立したタスクには Parallel を使用します
• バッチ処理には Map を使用します

パフォーマンス

• 高ボリュームで短時間のタスクには Express ワークフローを使用します
• 適切なタイムアウトを設定します
• スロットリングを避けるため、Map の同時実行数を制限します
• 可能な場合は SDK 統合を使用します（Lambda によるラッパーを避けます）

信頼性

• 一時的なエラーを再試行します
• 特定のエラーを捕捉して処理します
• 冪等性のある操作を使用します
• X-Ray トレースを有効にします

コストの最適化

• 短時間のワークフロー（< 5 minutes）には Express を使用します
• 遷移回数を減らすため、関連する操作をまとめます
• Lambda による遅延処理の代わりに Wait 状態を使用します

トラブルシューティング

実行の失敗

# Get execution history
aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:us-east-1:123456789012:execution:MyWorkflow:exec-123 \
  --query 'events[?type==`TaskFailed` || type==`ExecutionFailed`]'

Lambda のタイムアウト

原因：

• Lambda の実行時間が長すぎます
• タスクのタイムアウトが短すぎます

修正方法：

{
  "Type": "Task",
  "Resource": "arn:aws:lambda:...",
  "TimeoutSeconds": 300,
  "HeartbeatSeconds": 60
}

状態が停止したままになる

確認項目：

• コールバック待ちの Task 状態
• Wait 状態の待機時間がまだ経過していない
• アクティビティワーカーが応答していない

無効なステートマシン

# Validate definition
aws stepfunctions validate-state-machine-definition \
  --definition file://workflow.json

参考資料

• Step Functions 開発者ガイド
• Step Functions API リファレンス
• Step Functions CLI リファレンス
• Amazon States Language