aws-step-functions

AWS Step Functions

概要

AWS Step Functions は Amazon States Language（ASL）を使用して、ステートマシンを JSON で定義します。AWS Step Functions では、ステートマシンとも呼ばれるワークフローを作成して、分散アプリケーションの構築、プロセスの自動化、マイクロサービスのオーケストレーション、データおよび機械学習のパイプラインの作成を行えます。

このスキルでは、ASL でステートマシンを記述するための包括的なガイダンスを提供し、次の項目を取り上げます。

• ASL の構造と JSONata 式の構文
• 利用可能な 8 種類のワークフロー状態の詳細
• 予約変数 $states
• Assign を使用したワークフロー変数
• エラー処理
• AWS サービス統合パターン
• データ変換とアーキテクチャのコード例
• ステートマシンの検証とテスト
• JSONPath から JSONata への移行方法

このスキルに従う場合、サンドボックスでの実行と監査ログ記録には AWS MCP サーバーの使用を推奨します。ただし、すべての手順で AWS CLI の構文を使用しているため、AWS MCP サーバーがなくても実行できます。

参照ファイルを読み込むタイミング

ユーザーが作業している内容に応じて、適切な参照ファイルを読み込んでください。

• ASL の構造、状態の種類、Task、Pass、Choice、Wait、Succeed、Fail、Parallel、Map → references/asl-state-types.md を参照
• エラー処理、トラブルシューティング、Retry、Catch、フォールバック、エラーコード、States.Timeout、States.ALL → references/error-handling.md を参照
• サービス統合、Lambda invoke、DynamoDB、SNS、SQS、SDK 統合、Resource ARN、同期、非同期 → references/service-integrations.md を参照
• JSONPath から JSONata への移行、移行、JSONPath から JSONata への変換、InputPath、Parameters、ResultSelector、ResultPath、OutputPath、組み込み関数、Iterator、ペイロードテンプレート → references/migrating-from-jsonpath-to-jsonata.md を参照
• 検証、リンティング、テスト、TestState、テスト状態、モック、モック化、単体テスト、検査レベル、DEBUG、TRACE、状態の検証、単独でのテスト → references/validation-and-testing.md を参照
• アーキテクチャパターン、例、ポーリング、サガ、補償、散布・収集、セマフォ、ロック、human-in-the-loop、エスカレーション、Express から Standard への移行 → references/architecture-patterns.md を参照
• データ変換、JSONata 式、フィルタリング、集約、文字列操作、$reduce、$lookup、$toMillis、$partition、$parse、$hash、$uuid → references/transforming-data.md を参照
• 状態の入力／出力、$states、Assign、Output、Arguments、変数のスコープ、変数の上限、評価順序、状態間でのデータの受け渡し → references/processing-state-inputs-and-outputs.md を参照

クイックリファレンス

Standard ワークフローと Express ワークフロー

	Standard	Express
最大実行時間	1 年	5 分
実行セマンティクス	exactly-once	at-least-once（非同期）／at-most-once（同期）
実行履歴	90 日間保持、API でクエリ可能	CloudWatch Logs のみ
最大スループット	2,000 exec/sec	100,000 exec/sec
料金モデル	状態遷移ごと	実行回数＋実行時間ごと
.sync／.waitForTaskToken	サポート	非サポート
最適な用途	監査可能で、冪等でない操作	大量の冪等なイベント処理

次の場合は Standard を選択します：決済処理、注文の履行、コンプライアンスワークフロー、二重実行が絶対に許されない処理。

次の場合は Express を選択します：IoT データの取り込み、ストリーミング変換、モバイルバックエンド、高スループットで短時間の処理。

Express を推奨する場合は、ファイア・アンド・フォーゲット／高スループットのパイプラインであっても、必ず 1 つの制限を明記してください。Express は .sync と .waitForTaskToken をサポートしません（コールバック、ネストされた .sync の待機、人による承認やジョブ完了の待機はできません）。また、最大実行時間は 5 分で、クエリ可能な実行履歴はなく（CloudWatch Logs のみ）、実行セマンティクスは at-least-once（非同期）／at-most-once（同期）です。そのため、冪等でない処理は 2 回実行される可能性があります。これらのいずれかが重要な場合は、Standard を選択してください（exactly-once、最大 1 年、完全な履歴）。

ステートマシンのクエリ言語の設定

ASL でデータを参照および変換する方法として、JSONata が推奨されています。JSONPath の 5 つの I/O フィールド（InputPath、Parameters、ResultSelector、ResultPath、OutputPath）を、Arguments（入力）と Output の 2 つに置き換えます。

トップレベルで有効にすると、すべてのステートに適用されます。

{ "QueryLanguage": "JSONata", "StartAt": "...", "States": {...} }

または、ステートごとに設定することで、JSONPath から段階的に移行できます。

{ "Type": "Task", "QueryLanguage": "JSONata", ... }

JSONPath はサポートされており、QueryLanguage を省略した場合のデフォルトです。既存のステートマシンを移行する必要はありません。

フィールドの対応関係（JSONPath → JSONata）：

JSONPath フィールド	JSONata の対応フィールド
Parameters（キーには key.$ を使用）	Arguments — .$ の接尾辞を削除し、各値を {% %} で囲みます
ResultSelector と OutputPath	Output（$states.result を使って未加工の結果を参照します）
ResultPath	Assign（推奨）または Output
InputPath	不要です。$states.input を直接参照します

各ステートで使用するクエリ言語は 1 つだけです。 同じステート内で、JSONPath フィールド（InputPath／Parameters／ResultSelector／ResultPath／OutputPath）と JSONata フィールド（Arguments／Output）を混在させないでください。これは移行時に最もよくあるエラーです。詳しくは references/migrating-from-jsonpath-to-jsonata.md を参照してください。

Assign と Output の評価方法（順次ではなく並列）

1 つのステート内では、Assign と Output は同時に、並列で評価され、同じデータ（ステートの入力とタスクの結果）を読み取ります。順番に評価されるわけではありません。同時に実行されるため、Assign で設定した変数は、そのステートの Output からは参照できません。Output が割り当て直後の値を確認できるような順序は存在しないためです。割り当てた値は、後続のステートでのみ使用可能になります。

そのため、Assign で変数を設定し、同じステートの Output で参照すると、古い値または未定義の値になります。これは Output が Assign より「先に」実行されるからではなく、両方が同じスナップショットから並行して評価されるためです。その値をすぐに使うには、次のステートで参照します（変数はステート間で保持されます）。タスクの結果から現在のステートの出力を構成するには、Output で $states.result を直接使用します。

TestState によるステートの単体テスト

ステートマシンをデプロイしたり、実際のサービスを呼び出したりせずに、TestState API（aws stepfunctions test-state）を --mock とともに使用して、単一のステートをテストできます。回答では次の 4 点をすべて扱います。

• サービスの応答を正確にモックします — --mock の result は、対象の AWS サービスの API 応答スキーマと完全に一致している必要があります（フィールド名は大文字と小文字が区別されます）。Lambda invoke Task の場合は StatusCode と Payload です：--mock '{"result":"{\"StatusCode\":200,\"Payload\":{...}}"}'。
• 3 つすべての検査レベル（--inspection-level）：INFO（デフォルト — output、status、nextState）、DEBUG（データフローの afterArguments、result、variables を追加 — JSONata／データフローのデバッグに使用）、TRACE（生の HTTP request／response を追加。HTTP Task 用）。
• .sync と .waitForTaskToken の統合にもモックが必要です — .sync ではポーリング API（初回の呼び出しではなく、たとえば DescribeExecution）をモックします。.waitForTaskToken では、--context '{"Task":{"Token":"..."}}' も渡します。
• デプロイも実際の呼び出しも必要ありません — ステートを分離してテストします。

サービスごとのモック構造、およびエラー／再試行／Map／Parallel のテストについては、references/validation-and-testing.md を参照してください。

ベストプラクティス

• ユーザーが JSONPath を使いたい場合を除き、新しいステートマシンではトップレベルに "QueryLanguage": "JSONata" を設定します。
• Output は最小限にし、直後のステートで必要なものだけを含めます。
• 後続のステートで必要な変数を Output に渡し続けるのではなく、Assign を使って保存します。
• 元のステート入力を参照するには $states.input を使用します。
• Assign と Output はステートへの入力データから並列に評価され、順次には評価されません。そのため、Assign で設定した変数は同じステートの Output からは参照できません（Output には Assign 前の値が見えます）。新しい値が有効になるのは次のステートからです。
• すべての JSONata 式は定義済みの値を生成する必要があります — $data.nonExistentField は States.QueryEvaluationError をスローします。
• 任意のステートから元のワークフロー入力にアクセスするには $states.context.Execution.Input を使用します。
• コンソール外で作業する場合、ステートマシン定義は .asl.json 拡張子で保存します。
• SDK 統合よりも、最適化された Lambda 統合（arn:aws:states:::lambda:invoke）を優先します。

トラブルシューティング

よくあるエラー

• States.QueryEvaluationError — JSONata 式の評価に失敗しました。型エラー、未定義のフィールド、範囲外の値がないか確認します。
• 同じステート内で JSONPath のフィールドと JSONata のフィールドを混在させている。
• JSONata 式のトップレベルで $ または $$ を使用している — 代わりに $states.input を使用します。
• JSONata 式を {% %} で囲んでいない — 文字列がリテラルとして扱われます。
• Assign で変数を割り当て、同じステートの Output で使おうとしている — 新しい値が有効になるのは次のステートからです。
• 詳細なトラブルシューティングについては、references/validation-and-testing.md と references/error-handling.md を参照してください。

セキュリティに関する考慮事項

• 最小権限の実行ロール。 ステートマシンの IAM ロールは、呼び出す特定のリソースとアクション（特定の Lambda／DynamoDB／SQS／SNS ARN）に限定してください。*FullAccess ポリシーや service:* ワイルドカードは避けてください。
• 暗号化。 ワークフローが扱うすべてのデータストアについて、保存時と転送時の暗号化を推奨します。KMS で暗号化した DynamoDB テーブル、SQS キューと SNS トピックでのサーバー側暗号化（KmsMasterKeyId）、HTTP タスクでの TLS を使用してください。
• タスクトークンとメッセージ本文は機密情報です。 .waitForTaskToken トークンは認証情報です。シークレットとして扱ってください。PII、金融データ、シークレットを SQS／SNS のメッセージ本文や通知に含めないでください。参照 ID を渡し、受信者が認可されたチャネルを通じて詳細を取得するようにしてください。
• 入力を検証し、速やかに失敗させます。 ワークフローの開始時に、$exists() と $type() を使用する Choice（または Pass）状態で必須フィールドを検証し、入力が無効な場合は Fail 状態に遷移させて、不正なデータが後続の状態に渡らないようにしてください。Map 状態で MaxConcurrency を設定し、上流でスロットリング（StartExecution のレート制限または EventBridge）を行って、後続サービスを急増から保護してください。
• クロスアカウントアクセス。 Credentials フィールドを使用して別のアカウントのロールを引き受ける場合は、意図しないロールの引き受けを防ぐため、対象ロールの信頼ポリシーに aws:SourceArn や aws:SourceAccount などの条件キーを含めてください。
• 外部シークレット。 サードパーティ API を呼び出す HTTP タスクでは、API キーとトークンを AWS Secrets Manager に保存し（EventBridge 接続を通じて参照）、ステートマシン定義に直接埋め込まないでください。
• 可観測性。 実行の CloudWatch Logs を有効にし（ログレベルは ALL または ERROR。実行履歴を照会できない Express ワークフローでは必須）、Step Functions API 呼び出しを監査するために CloudTrail を有効にし、実行の失敗に対する CloudWatch アラームを設定してください。ステートの入力／出力は通常、実行ログに記録されるため、実行ロググループは必ずカスタマーマネージド KMS キーで暗号化してください。

リソース

• ASL 仕様
• JSONata ドキュメント
• Step Functions 開発者ガイド
• Step Functions のセキュリティに関するベストプラクティス