Step Functions入門｜ASLの書き方とLambda連携・Retry

AWS Step Functions は、Lambda や AWS のサービスを「手順の流れ」としてつなぐサービスです。 流れ（ステートマシン）は、ASL（Amazon States Language）という JSON で書きます。StartAt で最初の状態を決め、States の中に状態を並べて、Next でつなぎます。

{
  "Comment": "最小のステートマシン",
  "StartAt": "Hello",
  "States": {
    "Hello": { "Type": "Pass", "Result": { "message": "hello" }, "Next": "Done" },
    "Done":  { "Type": "Succeed" }
  }
}

状態（State）は8種類です。

確認環境：Python 3.11（Linux）・boto3 1.43.111・moto 5.2.4。AWS には接続していません。moto の Step Functions モックの「定義を実際に実行する」設定（execute_state_machine）で、JSONPath のステートマシンを作成・実行し、出力と実行履歴を取りました。JSONata の式は jsonata-python 0.7.1 で値を確かめました。Lambda の例外の形は、AWS 公開のランタイムクライアント awslambdaric 4.2.0 で確かめました。各項目の意味・既定値は、AWS の公式ドキュメントで確かめました（確認日 2026年10月12日）。

Step Functions の基本

Standard と Express の違い

ステートマシンを作るときに、種類を選びます。作ったあとで種類は変えられません（ドキュメントの記載）。

人の承認を待つ、長いバッチを待つといった流れは Standard です。短い処理を大量に流すなら Express が候補になります。

ASL の書き方：共通の項目

ドキュメントでは、Succeed と Fail 以外の状態は Next が要り、代わりに End: true で終わらせることもできます。Choice は、Choices の中の条件ごとに Next を書きます。

8種類の状態を全部使った例（JSONPath）

注文を受けて、金額で分け、明細ごとに処理し、2つの仕事を同時に動かす例です。moto で作成・実行しました。

{
  "Comment": "注文の流れ（JSONPath）",
  "StartAt": "Init",
  "States": {
    "Init": {
      "Type": "Pass",
      "Result": { "tax": 0.1 },
      "ResultPath": "$.config",
      "Next": "CheckAmount"
    },
    "CheckAmount": {
      "Type": "Choice",
      "Choices": [
        { "Variable": "$.amount", "NumericGreaterThanEquals": 10000, "Next": "BigOrder" },
        { "Variable": "$.amount", "NumericLessThan": 0, "Next": "Invalid" }
      ],
      "Default": "Items"
    },
    "BigOrder": { "Type": "Wait", "Seconds": 1, "Next": "Items" },
    "Items": {
      "Type": "Map",
      "ItemsPath": "$.items",
      "ResultPath": "$.lines",
      "ItemProcessor": {
        "ProcessorConfig": { "Mode": "INLINE" },
        "StartAt": "Line",
        "States": {
          "Line": { "Type": "Pass", "Parameters": { "sku.$": "$.sku", "qty.$": "$.qty" }, "End": true }
        }
      },
      "Next": "Both"
    },
    "Both": {
      "Type": "Parallel",
      "ResultPath": "$.parallel",
      "Branches": [
        { "StartAt": "A", "States": { "A": { "Type": "Pass", "Result": "mail sent", "End": true } } },
        { "StartAt": "B", "States": { "B": { "Type": "Pass", "Result": "stock reserved", "End": true } } }
      ],
      "Next": "Done"
    },
    "Done": { "Type": "Succeed" },
    "Invalid": { "Type": "Fail", "Error": "InvalidAmount", "Cause": "amount must be >= 0" }
  }
}

入力 {"orderId": "o-1", "amount": 12000, "items": [{"sku": "A1", "qty": 2}, {"sku": "B2", "qty": 1}]} で実行した結果です。

status: SUCCEEDED
output: {"orderId": "o-1", "amount": 12000, "items": [...], "config": {"tax": 0.1},
         "lines": [{"sku": "A1", "qty": 2}, {"sku": "B2", "qty": 1}],
         "parallel": ["mail sent", "stock reserved"]}

実行履歴（get_execution_history）は30件でした。主な流れは次のとおりです。

 1 ExecutionStarted
 2 PassStateEntered Init
 4 ChoiceStateEntered CheckAmount
 6 WaitStateEntered BigOrder          ← 12000 >= 10000 なので Wait へ
 8 MapStateEntered Items
10 MapIterationStarted Items          ← 明細2件で2回
18 MapStateSucceeded
20 ParallelStateEntered Both
26 ParallelStateSucceeded
28 SucceedStateEntered Done
30 ExecutionSucceeded

amount を -5 にすると、Fail で止まりました。

status: FAILED
error: InvalidAmount
cause: amount must be >= 0
 4 ChoiceStateEntered CheckAmount
 6 FailStateEntered Invalid
 7 ExecutionFailed InvalidAmount

Wait の Timestamp は 2026-10-12T09:00:00Z の形（大文字の T と Z）です。Map の Inline モードは、ドキュメントでは同時に最大40回の反復までです。

Lambda をつなぐ

Lambda を呼ぶ Task は、Resource に arn:aws:states:::lambda:invoke を書きます。 関数名と、関数に渡すデータ（Payload）を指定します。ドキュメントのチュートリアルは JSONata で書かれています。

{
  "QueryLanguage": "JSONata",
  "StartAt": "CalcTotal",
  "States": {
    "CalcTotal": {
      "Type": "Task",
      "Resource": "arn:aws:states:::lambda:invoke",
      "Arguments": {
        "FunctionName": "arn:aws:lambda:ap-northeast-1:123456789012:function:calc-total:$LATEST",
        "Payload": "{% $states.input %}"
      },
      "Output": "{% $states.result.Payload %}",
      "End": true
    }
  }
}

同じことを JSONPath で書くと、こうなります。

{
  "StartAt": "CalcTotal",
  "States": {
    "CalcTotal": {
      "Type": "Task",
      "Resource": "arn:aws:states:::lambda:invoke",
      "Parameters": {
        "FunctionName": "arn:aws:lambda:ap-northeast-1:123456789012:function:calc-total:$LATEST",
        "Payload.$": "$"
      },
      "ResultSelector": { "body.$": "$.Payload" },
      "ResultPath": "$.calc",
      "End": true
    }
  }
}

呼ばれる Lambda（Python）の例です。

class OrderNotFound(Exception):
    pass

def lambda_handler(event, context):
    if event.get("orderId") == "none":
        raise OrderNotFound(f"order {event['orderId']} not found")
    return {"orderId": event["orderId"],
            "total": sum(i["price"] * i["qty"] for i in event["items"])}

awslambdaric で動かすと、成功時は {"orderId": "o-1", "total": 11000} を返しました。例外のときは、次の本文になりました。errorType に例外のクラス名が入ります。 Step Functions では、これがエラー名として ErrorEquals で使えます（ドキュメントのチュートリアルでは CustomError）。

{"errorMessage": "order none not found", "errorType": "OrderNotFound", "requestId": "req-1", "stackTrace": ["..."]}

結果は Payload に包まれる

lambda:invoke の結果は、関数の戻り値がそのまま出てくるのではなく、Payload の中に入ります。 ドキュメントの例は次の形です。

{
  "ExecutedVersion": "$LATEST",
  "Payload": "FUNCTION OUTPUT",
  "SdkHttpMetadata": { "HttpHeaders": { "...": "..." }, "HttpStatusCode": 200 },
  "SdkResponseMetadata": { "RequestId": "6b3bebdb-..." },
  "StatusCode": 200
}

そのため、JSONata では $states.result.Payload、JSONPath では ResultSelector の $.Payload で取り出します。moto（Lambda のコードは動かさず、入力をそのまま返す設定）で試すと、包み方の違いが出力に表れました。

ステートマシンの IAM ロール

ステートマシンには実行ロールを付けます。Lambda を呼ぶなら lambda:InvokeFunction です。ドキュメントでは、FunctionName に :$LATEST やエイリアスを付けるなら、Resource の ARN の末尾に :* を付けるよう書かれています。付けないと Access Denied になります。

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "lambda:InvokeFunction",
    "Resource": [
      "arn:aws:lambda:ap-northeast-1:123456789012:function:calc-total",
      "arn:aws:lambda:ap-northeast-1:123456789012:function:calc-total:*"
    ]
  }]
}

IAM ポリシーの読み方は、関連記事「IAMポリシーの書き方｜JSONの読み方と最小権限の作り方【例文つき】」で扱っています。

JSONata と JSONPath の違い

QueryLanguage で、データの取り出し方・作り方を選びます。 省略すると JSONPath です。状態ごとに変えることもできます。

ドキュメントでは、Arguments・Output は JSONata 専用、Parameters などのパス系の項目は JSONPath 専用で、混ぜると定義として無効です。{% %} は、前後に空白を入れずに書きます。

同じ処理を JSONata で書く

{
  "QueryLanguage": "JSONata",
  "StartAt": "Calc",
  "States": {
    "Calc": {
      "Type": "Pass",
      "Output": {
        "orderId": "{% $states.input.orderId %}",
        "total": "{% $sum($states.input.items.(price * qty)) %}",
        "skus": "{% $states.input.items.sku %}"
      },
      "Assign": { "customer": "{% $states.input.customer %}" },
      "Next": "Check"
    },
    "Check": {
      "Type": "Choice",
      "Choices": [{ "Condition": "{% $states.input.total >= 10000 %}", "Next": "Big" }],
      "Default": "Small"
    },
    "Big":   { "Type": "Pass", "Output": { "result": "{% 'big order for ' & $customer %}" }, "End": true },
    "Small": { "Type": "Pass", "Output": { "result": "small" }, "End": true }
  }
}

Assign は変数（$customer）を作る項目で、あとの状態から参照できます。式の値を、入力 {"orderId": "o-1", "customer": "山田", "items": [{"sku": "A1", "price": 4000, "qty": 2}, {"sku": "B2", "price": 3000, "qty": 1}]} で確かめました。

JSONata は、結果が1件だけだと配列ではなく値そのものを返します。 次の Map の Items に渡すときなど、配列が要る場面では末尾に [] を付けます。

moto 5.2.4 では、JSONata のステートマシンは作成できましたが、実行は JSONata の評価で States.Runtime になりました（moto は JSONata の評価に Java の実行環境を使うため）。上の JSONata の値は、jsonata-python で式だけを評価したものです。

Retry と Catch の書き方

Retry は「同じ状態をもう一度」、Catch は「あきらめて別の状態へ」です。 両方あるときは、Retry を使い切ってから Catch に進みます。Task・Parallel・Map に書けます。

"GetOrder": {
  "Type": "Task",
  "Resource": "arn:aws:states:::dynamodb:getItem",
  "Parameters": { "TableName": "Orders", "Key": { "orderId": { "S.$": "$.orderId" } } },
  "ResultPath": "$.item",
  "Retry": [
    { "ErrorEquals": ["DynamoDB.ProvisionedThroughputExceededException"], "IntervalSeconds": 1, "MaxAttempts": 3 },
    { "ErrorEquals": ["States.ALL"], "IntervalSeconds": 1, "MaxAttempts": 2, "BackoffRate": 2.0 }
  ],
  "Catch": [
    { "ErrorEquals": ["States.ALL"], "ResultPath": "$.error", "Next": "Notify" }
  ],
  "Next": "Done"
}

存在しないテーブルを読ませて、moto で実行した履歴です。最初の1回＋再試行2回で、計3回失敗してから Catch に進みました。 実行全体は約4.3秒で、待ち時間 1秒 → 2秒（BackoffRate 2.0）が入っています。

 2 TaskStateEntered GetOrder
 5 TaskFailed DynamoDB.ResourceNotFoundException
 8 TaskFailed DynamoDB.ResourceNotFoundException
11 TaskFailed DynamoDB.ResourceNotFoundException
12 TaskStateExited GetOrder
13 PassStateEntered Notify
15 ExecutionSucceeded

Catch の ResultPath: "$.error" により、元の入力にエラーの情報が足されて次の状態に渡りました。

{"orderId": "o-1",
 "error": {"Error": "DynamoDB.ResourceNotFoundException",
           "Cause": "Requested resource not found (Service: AmazonDynamoDBv2; Status Code: 400; ...)"}}

存在しない Lambda を lambda:invoke で呼んだときは、Lambda.ResourceNotFoundException で Catch に進みました。

Retry の項目と既定値

IntervalSeconds: 3、BackoffRate: 2、MaxAttempts: 3 なら、待ち時間は 3秒・6秒・12秒の計算です。待ち時間とジッターの考え方は、関連記事「指数バックオフとは？リトライ間隔の決め方とジッターの実装」で扱っています。

Catch の項目

ResultPath を省略すると元の注文データが消えるので、"$.error" のように場所を決めておくと、後の状態で元のデータとエラーの両方を使えます。

よく使うエラー名

ドキュメントのベストプラクティスでは、Lambda の一時的なエラーを次の形で再試行する例が載っています。

"Retry": [{
  "ErrorEquals": ["Lambda.ClientExecutionTimeoutException", "Lambda.ServiceException",
                  "Lambda.AWSLambdaException", "Lambda.SdkClientException"],
  "IntervalSeconds": 2,
  "MaxAttempts": 6,
  "BackoffRate": 2
}]

TimeoutSeconds を付ける

Task の TimeoutSeconds の既定値は 99,999,999 秒です。ドキュメントのベストプラクティスでは、タイムアウトを付けないと、応答が来ない Task で実行が止まったままになるとして、TimeoutSeconds を付けるよう勧めています。超えると States.Timeout になり、Retry・Catch で扱えます。

作成と実行（AWS CLI・boto3）

AWS CLI では、定義を file:// で渡します。

aws stepfunctions create-state-machine \
  --name order-flow \
  --definition file://order-flow.asl.json \
  --role-arn arn:aws:iam::123456789012:role/sfn-order-flow

aws stepfunctions start-execution \
  --state-machine-arn arn:aws:states:ap-northeast-1:123456789012:stateMachine:order-flow \
  --input '{"orderId":"o-1","amount":12000,"items":[{"sku":"A1","qty":2}]}'

aws stepfunctions describe-execution --execution-arn <start-executionの返したARN>
aws stepfunctions get-execution-history --execution-arn <同上>

moto で試したときの boto3 のコードです。テストでも同じ形で使えます。

import json, time, boto3
from moto import mock_aws

definition = {"StartAt": "Hello", "States": {"Hello": {"Type": "Pass", "End": True}}}

with mock_aws(config={"stepfunctions": {"execute_state_machine": True}}):
    sfn = boto3.client("stepfunctions", region_name="ap-northeast-1")
    arn = sfn.create_state_machine(
        name="demo", definition=json.dumps(definition),
        roleArn="arn:aws:iam::123456789012:role/sfn-role",
    )["stateMachineArn"]
    ex = sfn.start_execution(stateMachineArn=arn, input=json.dumps({"a": 1}))["executionArn"]
    while (d := sfn.describe_execution(executionArn=ex))["status"] == "RUNNING":
        time.sleep(0.1)
    print(d["status"], d.get("output"))
    for e in sfn.get_execution_history(executionArn=ex)["events"]:
        print(e["id"], e["type"])

moto は定義の検査がゆるい点に注意します。 次の定義は、moto 5.2.4 ではどれも作成できました。

AWS 上では、ValidateStateMachineDefinition API（CLI は aws stepfunctions validate-state-machine-definition）で、作る前に定義を検査できます。CI で定義ファイルを検査すると、間違いに早く気づけます。

よくある質問

Q. ASL は YAML で書けますか。 A. API に渡す定義は JSON です。AWS SAM や CDK を使うと、テンプレートの中で書いて JSON に変換できます。SAM は関連記事「AWS SAM入門｜template.yamlの書き方とbuild・deploy」、CDK は関連記事「AWS CDK入門｜TypeScriptでS3とLambdaを作りsynthまで」で扱っています。

Q. JSONPath と JSONata、どちらで書き始めますか。 A. ドキュメントの Lambda 連携のページや、エラー処理のチュートリアルの例は JSONata で書かれています。項目が Arguments と Output の2つに減り、計算や絞り込みも式で書けます。既存の JSONPath の定義は、状態ごとに QueryLanguage を変えて少しずつ移せます。

Q. Lambda の中でリトライするのと、Retry で再実行するのはどう違いますか。 A. Retry は状態ごと呼び直すので、Lambda の処理が途中まで進んでいても、もう一度最初から動きます。同じ注文を二重に登録しないよう、処理を冪等（何回やっても結果が同じ）にしておきます。考え方は関連記事「冪等性とは？API設計での意味と冪等キーの実装方法」で扱っています。

Q. Lambda の書き方から知りたいです。 A. ハンドラの書き方とローカルでの確かめ方は、関連記事「AWS Lambda Python入門｜3.14対応handler例とローカルテスト」で扱っています。

まとめ

• ASL は StartAt・States・各状態の Type と Next/End が骨格
• 状態は Task・Choice・Parallel・Map・Wait・Pass・Succeed・Fail の8種類
• Lambda は arn:aws:states:::lambda:invoke。結果は Payload に包まれる
• JSONata は Arguments・Output・{% %}、JSONPath は Parameters・ResultPath・.$。混ぜられない
• Retry の既定は 間隔1秒・3回・2倍。moto では最初の1回＋再試行2回のあと Catch に進んだ
• Catch の ResultPath を省略すると入力が消える。"$.error" などに置く
• States.ALL は 単独で最後に。moto は検査がゆるいので、AWS の検証 API でも確かめる

参考・出典

確認日はいずれも 2026年10月12日です。

• AWS Step Functions デベロッパーガイド「Discovering workflow states to use in Step Functions」：https://docs.aws.amazon.com/step-functions/latest/dg/workflow-states.html
• AWS Step Functions デベロッパーガイド「Handling errors in Step Functions workflows」：https://docs.aws.amazon.com/step-functions/latest/dg/concepts-error-handling.html
• AWS Step Functions デベロッパーガイド「Transforming data with JSONata in Step Functions」：https://docs.aws.amazon.com/step-functions/latest/dg/transforming-data.html
• AWS Step Functions デベロッパーガイド「Invoke an AWS Lambda function with Step Functions」：https://docs.aws.amazon.com/step-functions/latest/dg/connect-lambda.html
• AWS Step Functions デベロッパーガイド「Task workflow state」：https://docs.aws.amazon.com/step-functions/latest/dg/state-task.html
• AWS Step Functions デベロッパーガイド「Wait workflow state」：https://docs.aws.amazon.com/step-functions/latest/dg/state-wait.html
• AWS Step Functions デベロッパーガイド「Map state in Inline mode」：https://docs.aws.amazon.com/step-functions/latest/dg/state-map-inline.html
• AWS Step Functions デベロッパーガイド「Choosing workflow type in Step Functions」：https://docs.aws.amazon.com/step-functions/latest/dg/choosing-workflow-type.html
• AWS Step Functions デベロッパーガイド「Best practices for Step Functions」：https://docs.aws.amazon.com/step-functions/latest/dg/sfn-best-practices.html
• AWS Step Functions デベロッパーガイド「Handling error conditions using a Step Functions state machine」：https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-handling-error-conditions.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。