構築する内容ステップ 1 – ステートマシンを作成するステップ 2 – ステートマシンを開始するステップ 3 – 外部入力を処理するステップ 4 – サービスを統合するリソースをクリーンアップする

Step Functions の使用を開始する方法について

Step Functions サービスを使用すると、複雑なアプリケーションワークフローをオーケストレーションできます。まず、Workflow Studio を使用して、組み込みの Hello World ワークフローを作成して実行します。自動生成された Amazon States Language (ASL) 定義をコードで確認します。最後に、サービス統合をドラッグアンドドロップして、感情分析を行います。

このチュートリアルを完了すると、Workflow Studio で [デザイン] モードと [コード] モードの両方を使用して、ワークフローを作成、設定、実行、更新する方法を習得できます。

所要時間の目安: 20〜30 分

構築する内容

最初のステートマシンは Flow ステートから始まります。Flow ステートは、ワークフローの指示と制御に使用します。ワークフローの実行方法を理解できたら、アクションを追加して、Amazon Comprehend サービスを Task ステートと統合します。

次の図では、完成したステートマシンの全体像を示しています。Hello World ステートマシンを初めて作成するときは、実行に追加のリソースは必要ありません。Step Functions コンソールで、すべてのステートと IAM ロールがワンクリックで作成されます。後でサービス統合を追加するときに、カスタムアクセス許可ポリシーを関連付けたロールを作成する必要があります。

ステップ 1 – ステートマシンを作成する

Step Functions では、ワークフローのことをステートマシンと呼びます。ここでは両方の用語を同じ意味で使用します。ワークフローには、ステートマシンでアクションを実行したりフローを制御したりするステートが含まれます。

Step Functions コンソールに移動します。
Step Functions コンソールで、左上のナビゲーションまたはパンくずリストから [Step Functions] を選択したら、[開始方法] を選択します。
オプションから [Hello World を実行] を選択します。

ヒント

コンソール内の短いウォークスルーを一通り実行して、UI に慣れておくことをお勧めします。

Workflow Studio の概要

Step Functions の Workflow Studio を使用すると、ステートをキャンバスにドラッグアンドドロップしてワークフローを視覚的に構築できます。

ステートの追加と編集、ステップの設定、結果の変換、エラー処理の設定が可能です。次のスクリーンショットは、ステートマシンを構築するために使用するインターフェイスの 4 つの重要な領域を示しています。

Workflow Studio インターフェイスの 4 つの重要な領域のスクリーンショット

モード – Workflow Studio には 3 つのオペレーションモードがあり、デフォルトはビジュアルデザインモードです。

デザイン – ワークフローにステートをドラッグアンドドロップできる、ビジュアル編集モードです。
コード – Amazon States Language (ASL) コードの編集に特化したモードです。ASL コードを直接編集し、ビジュアルデザインに反映された変更を確認できます。
設定 – ステートマシンの名前とタイプ (Standard または Express)、ワークフロー実行時に割り当てられるロール、ログ記録、トレース、バージョニング、暗号化、タグなどの設定オプションです。

ステートブラウザには、次の 3 つのタブがあります。

アクション - ワークフローにdrag-and-dropできる AWS APIs のリスト。各アクションは Task ワークフローステートを表します。
フロー – ワークフローのステップの順序を制御する Flow ステートです。
パターン – Amazon S3 バケット内のデータを繰り返し処理するなど、すぐに使える再利用可能な構成要素です。

キャンバスとワークフローグラフは、ステートをドラッグアンドドロップしたり、ステートの順序を変更したり、構成・テストするステートを選択したりする場所です。

Inspector パネルは、キャンバスで選択したステートのプロパティを表示・編集する場所です。[定義] トグルをオンにすると、現在選択されているステートのコードを表示できます。

ステートマシンの概要

Hello World ワークフローは、処理を実行せずに入力をそのまま出力に渡す Pass ステートから始まります。Pass ステートは、静的な JSON を出力したり、次のステートに渡す前に JSON 入力を変換したりするのに使用できます。Pass ステートは、ステートマシンの構築時やデバッグ時に便利です。

次の Choice ステートは、IsHelloWorldExample のデータに基づいてワークフローの次のブランチを選択します。最初のルールに一致すると、ワークフローは Wait ステートで一時停止し、次に Parallel ステートで 2 つのタスクを実行したら、チェックポイントを経てワークフローの正常終了に進みます。一致しない場合、ワークフローはデフォルトで Fail ステートに進み、ステートマシンを停止します。

Wait ステートは、次の処理までに遅延を挟みたいときに便利です。例えば、注文入力後にワークフローを 30 秒間待機させることで、顧客が配送先住所の誤りに気付き修正する時間を確保できます。

Parallel ステートでは、データに対して複数のプロセスを同時に実行できます。例えば、注文伝票の印刷、在庫の更新、日次売上レポートの更新を同時に行うことができます。

ワークフローコード (ASL) を表示する

最初のステートマシンは実際には非常に詳細です。コードを確認してさらに理解を深めましょう。

ステートマシンは、JSON ベースで宣言的に記述するオープンソース仕様である Amazon States Language (ASL) を使用して定義されます。

ステートマシン定義全体を表示するには

[{ } コード] ボタンを選択して、ASL コードを表示します。
左側にコード、右側にステートマシングラフを表示して比較します。
キャンバスでステートをいくつか選択して確認します。例えば、Choice ステートを選択します。

ステートの定義がコードビューで強調表示されているのがわかります。

Inspector でコードを表示するには

[デザイン] モードに戻ります。
右側の Inspector パネルを展開します。
キャンバス上のワークフローグラフから Choice ステート を選択します。
Inspector パネルで、[定義] トグルを選択します。

他のステートも選択してみます。選択した各ステートの ASL コードがスクロールされ、強調表示されるのがわかります。

ステートマシンを (実際に) 作成する

警告: 今すぐステートマシンに名前を付けてください。

ステートマシンは作成後に名前を変更することはできません。ステートマシンを保存する前に名前を選択してください。

ここまでは、ステートマシンのドラフトで作業してきました。リソースはまだ作成されていません。

ステートマシンを名前変更して作成するには

[設定モード] を選択します。
ステートマシン名として、「MyFirstStateMachine」と入力します。
アクセス許可として、デフォルトの [新規ロールの作成] を受け入れます。
[作成] ボタンを選択して、ステートマシンを実際に作成します。

ステートマシンと新しい IAM ロールが作成されたという通知が表示されます。

ステートマシンを開始するオプションが自動的に表示されます。これは次のステップで行います。

ワークフローの作成が完了しました。

Step Functions によってワークフローと IAM ロールが作成されました。これで、ステートマシンを開始する準備ができました。

ステップ 2 – ステートマシンを開始する

ステートマシンを作成したら、ワークフローの実行を開始できます。

ワークフローでは、入力をオプションとして指定でき、ステート内で使用したり、統合サービスに送信したり、次のステートに渡したりできます。

Hello World ステートマシンは自己完結型であり、入力は必要ありません。

ステートマシンを開始するには

実行の名前として「hello001」と入力します。
入力フィールドは空白のままにします。
[実行を開始] ボタンを選択します。

実行の詳細を確認する

開始直後に、最初の 2 つのステートが成功したのがわかります。

しばらくすると、残りのステート遷移が実行されて、ワークフローが完了します。

Choice ステート (Is Hello World Example?) がどのようにして Wait for X Seconds ステートに分岐したか確認してみましょう。

ヒント: ステートマシンの最初のステップに、分岐の判断に必要なデータが含まれています。
グラフビューでは、実行中の進行状況を確認し、各ステートの詳細を確認できます。
最初の Pass ステート (Set Variables and State Output) を選択し、[入力/出力] タブを確認します。

ステートの入力は空白ですが、ステートの出力には、IsHelloWorldExample の値を true に設定する JSON が含まれているのがわかります。

グラフビューからテーブルビューに切り替えて、名前、タイプ、ステータス別のステートのリストを表示します。

ヒント

前のスクリーンショットの [所要時間] と [タイムライン] のフィールドに注目してください。どのステートに時間がかかっているかが一目でわかります。

この実行の詳細ページには、さらに 2 つのビュー (イベントビューとステートビュー) があります。

イベントビューは、ステート間のフローを詳細に確認できるビューです。

[イベントビュー] テーブル内の最初の PassStateEntered イベントと PassStateExited イベントを展開すると、ステートが入力を取らず、CheckpointCount という変数に 0 を割り当て、先ほどの出力を生成しているのがわかります。

最後に、ステートビューがあります。これはテーブルビューに似ています。[ステートビュー] テーブルでは、各ステートを個別に展開して、その入力と出力だけを確認できます。

お疲れ様でした。これで、初めての Step Functions ステートマシンを実行できました。

Pass ステートを使用して静的データをワークフローに追加するのは、特にトラブルシューティングでよく使用されるパターンです。

次のステップでは、ステートマシンの入力を動的に設定できるようにワークフローを更新します。

ステップ 3 – 外部入力を処理する

ワークフロー内で IsHelloWorldExample の値を定数値に設定するのは現実的ではありません。ステートマシンは、変化する入力データに応答することが想定されます。

このステップでは、外部 JSON データをワークフローへの入力として使用する方法を示します。

ハードコーディングされた入力を削除する

まず、最初の Pass ステートの出力にあるハードコーディングされた値を置き換えます。

ページ右上の [ステートマシンの編集] ボタンを選択して、Hello World ステートマシンを編集します。
[Start] の直後にある最初の Pass ステート (Set Variables and State Output) を選択したら、[出力] タブを開きます。

出力を次の JSON に置き換えます。


{
  "IsHelloWorldExample": "{% $states.input.hello_world %}",
  "ExecutionWaitTimeInSeconds":  "{% $states.input.wait %}"
}

ステートマシンを保存します。

更新されたステートの出力は、JSONata 式を使用して、予約済みの $states 変数から入力データをプルします。これらの値は出力として次のステートに渡され、そのまま次のステートの入力になります。

入力データを使用して更新されたワークフローを実行する

次に、ワークフローを実行し、外部入力データを JSON として指定します。

[実行] ボタンを選択してワークフローを実行します。
[名前] には、ランダムに生成された ID を使用します。
入力フィールドには、次の JSON を使用します。
```
{
    "wait" : 20,
    "hello_world": true
}
```
[実行を開始] ボタンを選択します。

ステートマシンの実行ははるかに長く (20 秒間) 待機しますが、最終的に指定した入力を使用して成功します。

グラフビューで、最初の Pass ステートの [入力/出力] を確認します。指定した入力がどのように出力に変換されたかに注目してください。また、実行の詳細ページの上部にある [実行の入力と出力] も確認します。どちらの場所にも、実行の開始に使用した入力が表示されます。

ヒント

hello_world を false に設定して新しい実行を開始したら、どうなるでしょう。試してみましょう !

ワークフロー実行を確認する

ワークフローを複数回実行したので、それぞれの実行の詳細を確認してみましょう。

実行の詳細を確認するには

ナビゲーションパンくずリストまたは左側のメニューから [ステートマシン] を選択します。
ステートマシンを選択します。

[実行] タブに、次のスクリーンショットのような実行のリストが表示されます。

最後に一点: ワークフロー実行の名前は一意である必要があり、再利用することはできません。このチュートリアルでは短い名前 (hello001) を提案しましたが、本番ワークロードでは常に一意になるような命名規則を使用することをお勧めします。

ヒント

おめでとうございます。ワークフローを更新して、実行ごとに変化する外部入力を処理できるようになりました。

ステップ 4 – サービスを統合する

Step Functions ステートマシンは、AWS SDK integrations を使用して 220 を超える AWS サービスを呼び出すことができます。 AWS サービスは、ステートマシンに 10,000 を超える潜在的な API アクションを提供します。

このステップでは、感情分析用に Amazon Comprehend タスクを統合して、ステートマシンの入力を処理します。

重要

このチュートリアルで使用される Amazon Comprehend DetectSentiment API は、すべてので利用できるわけではありません AWS リージョン。このチュートリアルを完了するには、米国東部 (バージニア北部) など、Amazon Comprehend が利用可能なリージョンを使用しますus-east-1。サポートされているリージョンの完全なリストについては、のAmazon Comprehend エンドポイントとクォータ」を参照してください。

サービス統合では、3 つのサービス統合パターンのいずれかを使用します。

リクエストレスポンス (デフォルト) – HTTP レスポンスを待ってから、直ちに次のステートに進みます。
ジョブを実行 (.sync) – ジョブの完了を待ってから、次のステップに進みます。
コールバックを待機 (.waitForTaskToken) – 外部プロセスからタスクトークンが返されるまで、ワークフローを一時停止します。

最初の統合では、リクエストレスポンス (デフォルト) 統合パターンを使用します。

統合の仕組み

Task ステートは、ステートマシンが実行する 1 単位の処理を表します。ステートマシンのすべての作業は、タスクにより処理されます。

タスクは通常、入力を他のサービスの API アクションに渡して、それぞれの処理を実行させます。タスクの実行方法は、Credentials、Retry、Catch、TimeoutSeconds など複数のフィールドで指定できます。「Task ワークフロー状態」で、タスクの詳細を確認できます。

AWS SDK 統合を使用するには、呼び出すサービス名と API を指定します。一部の統合にはパラメータも必要です。

Amazon States Language を使用して、タスク状態のリソースフィールドに AWS API アクションを指定できます。オプションで、サービス名にサービス統合タイプを追加することもできます。

API アクションを指定するには、次のリソース名テンプレートを使用します。


arn:aws:states:::aws-sdk:serviceName:apiAction.[serviceIntegrationPattern]

パラメータ名の大文字と小文字の区別

API アクションは camelCase (先頭が小文字) になりますが、ParameterNames は Pascal case (先頭が大文字) になることに注意してください。

リソース名の例

arn:aws:states:::aws-sdk:ec2:describeInstances は Amazon EC2 describeInstances API の呼び出し結果を返します。
arn:aws:states:::aws-sdk:s3:listBuckets は Amazon S3 listBuckets API の呼び出し結果を返します。
arn:aws:states:::aws-sdk:sfn:startExecution はネストされた Step Functions ステートマシンの実行を開始し、そのワークフローの結果を返します。

Step Functions が Task ステートを使用して別のサービスを呼び出す場合、デフォルトのパターンはリクエストレスポンスです。リクエストレスポンス統合パターンでは、Step Functions はサービスを呼び出し、レスポンスを受け取ると、直ちに次のステートに進みます。

ステップ 4.1 – 感情分析ステートを追加する

MyFirstStateMachine ステートマシンを編集します。
ステートブラウザの [アクション] パネルから DetectSentiment を検索します。
Comprehend DetectSentiment を Choice ステートのデフォルトブランチにドラッグアンドドロップします。
Fail ステートを選択して削除します。
ステートブラウザの [フロー] タブから、DetectSentiment の後に Success ステートをドラッグします。

ステップ 4.2 – Sentiment Analysis ステートを設定する

Comprehend ステップを選択して、Inspector パネルで設定します。
[Arguments と Output] タブを選択し、Arguments を次の JSON に置き換えます。
```
{
   "LanguageCode": "en",
   "Text": "{% %}"
}
```
パーセント記号の間 {% %} にカーソルを置き、「$」と入力します。
エディタのオートコンプリートを使用して、states を選択します。

次に「.」と入力し、[context] を選択します。

次に「.」と入力し、[Execution] を選択します。

次に「.」と入力し、[Input] を選択します。

最後に「.feedback_comment」と入力し、Context オブジェクトから初期入力を取得します。

これらのオートコンプリートオプションを選択すると、ステートの Arguments は次のような JSON になります。


{
    "LanguageCode": "en",
    "Text": "{% $states.context.Execution.Input.feedback_comment %}"
}

エディタのオートコンプリートの使用

エディタのオートコンプリートを使用すると、オプションを調べることができます。

オートコンプリートでは、変数、Context オブジェクトを含む予約済みの $states 変数、使用可能な関数とその定義が一覧表示されます。

ステップ 4.3 – アイデンティティポリシーを設定する

ワークフローを実行する前に、ステートマシンから外部サービスへの API コールを許可するためのロールとポリシーを作成する必要があります。

Step Functions 用の IAM ロールを作成するには

新しいタブで IAM コンソールに移動し、[ロール] を選択します。
[Create a new role (新規ロールの作成)] を選択します。
[信頼されたエンティティタイプ] で、[AWS サービス] を選択します。
[ユースケース] で [Step Functions] を選択します。
[アクセス許可の追加] で [次へ] を選択し、デフォルトのポリシーを受け入れます。ロールの作成後に Comprehend に関するポリシーを追加します。
[名前] に「HelloWorldWorkflowRole」と入力します。
[ロールの作成] を選択してください。

Amazon Comprehend に関するポリシーを HelloWorldWorkflowRole に追加するには

HelloWorldWorkflowRole ロールを選択して編集します。
[アクセス許可の追加] を選択してから、[インラインポリシーの作成] を選択します。
サービスとして [Comprehend] を選択します。
[読み取り] で [DetectSentiment] を選択してから、[次へ] を選択します。
[ポリシー名] に「DetectSentimentPolicy」と入力し、[ポリシーを作成] を選択します。

ポリシーを確認すると、すべてのリソースでアクション "comprehend:DetectSentiment" の実行が許可されているのがわかります。

IAM ロールを Step Functions ステートマシンにアタッチするには

ステートマシンの編集に戻り、[設定] タブを選択します。
[実行ロール] ドロップダウンから [HelloWorldWorkflowRole] を選択します。
ステートマシンを保存します。

ステップ 4.4 – ステートマシンを実行する

次の JSON を入力として、ステートマシンの実行を開始します。


{
    "hello_world": false,
    "wait": 42,
    "feedback_comment" : "This getting started with Step Functions workshop is a challenge!"
}

正しいポリシーがない場合、次のようなアクセス許可エラーが表示されます。


User: arn:aws:sts::account-id:assumed-role/StepFunctions-MyStateMachine-role is not authorized
to perform: comprehend:DetectSentiment because no identity-based policy allows the comprehend:DetectSentiment
action (Service: Comprehend, Status Code: 400, Request ID: a1b2c3d4-5678-90ab-cdef-EXAMPLE11111)

前のエラーメッセージは、ステートマシンが外部サービスの使用を認可されていないことを示しています。1 つ前のステップに戻り、アイデンティティポリシーが設定されていることを確認します。

復習

より複雑なワークフローに進む前に、これまで理解したことを次のタスクで復習しましょう。

DetectSentiment ステップを確認します。さまざまなビューで入力/出力を確認し、感情分析の結果を表示します。
テーブルビューで DetectSentiment ステートの [所要時間] を見つけます。
[JSON 入力] のコメントを変更し、ステートマシンを再実行します。

感情分析結果の詳細については、「Amazon Comprehend – 感情」を参照してください。

リクエストレスポンス統合では、レスポンスがリクエストの受信確認を示すだけと考えることができます。ただし、感情分析など一部の統合では、その受信確認がタスクの完了を表します。

重要なのは、Task ステートがリクエストレスポンス統合で基盤となるジョブを待機しないという点です。レスポンスを待機するには、[ジョブを実行 (.sync)] サービス統合パターンを調べる必要があります。

お疲れ様でした。

最初のステートマシンを作成し、リクエストレスポンスパターンを使用して感情分析タスクを統合しました。

フィードバックをお待ちしております。

この入門チュートリアルの役立った点や改善すべき点がございましたら、このページのフィードバックオプションを使用してお知らせください。

リソースをクリーンアップする

以下の手順に従って、作成したリソースをクリーンアップします。

AWS コンソールの Step Functions ページに移動します。
左側のナビゲーションペインから [ステートマシン] を選択します。
MyFirstStateMachine を選択します。
IAM ロールを削除するには

1 – IAM ロールのリンクをたどり、新しいタブで IAM ロールのページに移動します。関連するカスタムロールを削除します。

2 – IAM ロールで、MyFirstStateMachine を含む自動生成されたロールを検索します。自動生成されたロールを削除します。
Step Functions コンソールのタブに戻り、[アクション] ドロップダウンを選択してから、[削除] を選択してステートマシンを削除します。

これで、ステートマシンと関連ロールが正常に削除されました。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ユースケース

ステートマシン