サービス統合パターン - AWS Step Functions

「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」

サービス統合パターン

AWS Step Functions は Amazon ステートメント言語 内で直接サービスを統合します。3 つの異なるサービス統合パターンを使用して、これらの AWS のサービスを制御できます。

  • サービスを呼び出し、Step Functions が HTTP レスポンスを取得した直後に次のステップに進むことができるようにします。

  • サービスを呼び出し、ジョブが完了するまで Step Functions が待機するようにします。

  • タスクトークンでサービスを呼び出し、トークンがペイロードとともに返されるまで Step Functions が待機するようにします。

このようなサービス統合パターンは、"Resource"タスク定義 フィールドで URI を作成する方法に応じてそれぞれ制御されます。

統合されたサービス用に AWS Identity and Access Management (IAM) を設定する方法については、「統合サービスの IAM ポリシー」を参照してください。

注記

Lambda 呼び出しは、.sync サービス統合パターンを指定しなかった場合でも、それを使用します。を非同期的に呼び出す場合は、Lambda パラメータを使用できます。InvocationType詳細については、「Step Functions で Lambda を呼び出す」を参照してください。

リクエストレスポンス

タスクの状態の "Resource" 文字列でサービスを指定する場合にリソースのみを指定すると、Step Functions は HTTP レスポンスがあるまで待機してから次の状態に進みます。Step Functions はジョブの完了まで待機しません。

次の例は Amazon SNS トピックを発行する方法を示しています。

"Send message to SNS":{ "Type":"Task", "Resource":"arn:aws:states:::sns:publish", "Parameters":{ "TopicArn":"arn:aws:sns:us-east-1:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" }

この例では、PublishAmazon SNS API を参照します。Publish API の呼び出し後、ワークフローは次の状態に進みます。

ジョブを実行する

AWS Batch や Amazon ECS などの統合されたサービスの場合、Step Functions は次の状態に進む前にリクエストの完了まで待機します。Step Functions を待機させるには、タスクの状態の "Resource" フィールドでリソース URI の後に .sync サフィックスを追加します。

たとえば、AWS Batch ジョブを送信する場合は、この例に示すように、ステートマシン定義の "Resource" フィールドを使用します。

"Manage Batch task": { "Type": "Task", "Resource": "arn:aws:states:::batch:submitJob.sync", "Parameters": { "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition", "JobName": "testJob", "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue" }, "Next": "NEXT_STATE" }

部分をリソースの Amazon リソースネーム (ARN) に追加すると、.sync はジョブが完了するまで待機します。Step FunctionsAWS Batch submitJob の呼び出し後、ワークフローは停止します。ジョブが完了すると、Step Functions は次の状態に進みます。詳細については、「バッチジョブの管理 (AWS Batch、Amazon SNS)」の AWS Batch サンプルプロジェクトを参照してください。

この (.sync) サービス統合パターンを使用するタスクが中止され、Step Functions がタスクをキャンセルできない場合、統合サービスから追加料金が発生する可能性があります。以下の場合は、タスクを中止できます。

  • ステートマシンの実行が停止されました。

  • Parallel 状態の別のブランチがキャッチされないエラーで失敗します。

  • Map 状態の反復処理は、キャッチされないエラーで失敗します。

Step Functions はベストエフォートでタスクをキャンセルしようとします。たとえば、Step Functions states:startExecution.sync タスクが中止されると、Step Functions StopExecution API アクションが呼び出されます。ただし、Step Functions はタスクをキャンセルできない可能性があります。その理由には次のものが含まれますが、これらに限定されません。

  • 実行ロールに、対応する API コールを実行するアクセス許可がありません。IAM

  • 一時的なサービス停止が発生しました。

どの統合されたサービスでジョブの完了の待機 (.sync) がサポートされているかのリストについては、「Step Functions でサポートされる AWS サービス統合」を参照してください。

注記

.sync または .waitForTaskToken パターンを使用するサービス統合では、IAM のアクセス許可が別途必要です。詳細については、「統合サービスの IAM ポリシー」を参照してください。

タスクトークンのコールバックまで待機する

コールバックタスクは、タスクトークンが返されるまでワークフローを待機させる方法を提供します。タスクには、人間による承認、サードパーティとの統合、あるいはレガシーシステムの呼び出しまで待機することが必要になる場合があります。このようなタスクでは、Step Functions を無期限に停止して、外部のプロセスあるいはワークフローが完了するまで待機させることができます。このような状況において Step Functions では、タスクトークンをいくつかの統合されたサービスに渡すことができます。SendTaskSuccess あるいは SendTaskFailure 呼び出しでタスクがタスクトークンを受け取るまで、このタスクは停止します。

どの統合されたサービスでタスクトークンの待機 (.waitForTaskToken) がサポートされているかのリストについては、「Step Functions でサポートされる AWS サービス統合」を参照してください。

注記

.sync または .waitForTaskToken パターンを使用するサービス統合では、IAM のアクセス許可が別途必要です。詳細については、「統合サービスの IAM ポリシー」を参照してください。

タスクトークンの例

この例では、承認ワークフローの一部としてクレジットチェックを実行するために、外部のマイクロサービスを Step Functions ワークフローに統合する必要があります。Step Functions は、メッセージの一部にタスクトークンが含まれる Amazon SQS メッセージを発行します。1 つの外部システムが Amazon SQS に統合され、キューからメッセージを引き出します。これが完了すると、結果および元のタスクトークンが返されます。その後、Step Functions はワークフローを続行します。


                        タスクトークンが返されるまで待機する SQS タスク

Amazon SQS を参照するタスク定義の "Resource" フィールドには、末尾に追加された .waitForTaskToken が含まれています。

"Send message to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue", "MessageBody": { "Message": "Hello from Step Functions!", "TaskToken.$": "$$.Task.Token" } }, "Next": "NEXT_STATE" }

これにより、Step Functions に停止してタスクトークンを待つように指示されます。.waitForTaskToken を使用してリソースを指定する場合、状態定義の "Parameters" フィールドで特別なパス指定 ($$.Task.Token) を使用して、タスクトークンにアクセスすることができます。最初の $$. は、そのパスアクセスにコンテキストオブジェクトを指定し、現在実行中のタスクのタスクトークンを取得します。

これが完了すると、外部サービスによって が含まれた SendTaskSuccess または SendTaskFailure が呼び出されます。taskTokenこの時点でのみ、ワークフローが次の状態へと続行します。

注記

プロセスが SendTaskSuccess または SendTaskFailure とともにタスクトークンを送信することに失敗した場合に無期限に待機することを回避するには、「待機中のタスクにハートビートタイムアウトを設定する」を参照してください。

コンテキストオブジェクトからトークンを取得する

コンテキストオブジェクトは、実行に関する情報が含まれた内部の JSON オブジェクトです。状態の入力と同様に、実行中に "Parameters" フィールドからパスを使用してこれにアクセスできます。タスクの定義内からアクセスすると、これにはタスクトークンを含めた特定の実行に関する情報が含まれます。

{ "Execution": { "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::123456789012:role...", "StartTime": "2019-03-26T20:14:13.192Z" }, "State": { "EnteredTime": "2019-03-26T20:14:13.192Z", "Name": "Test", "RetryCount": 3 }, "StateMachine": { "Id": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName", "Name": "name" }, "Task": { "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W" } }

タスク定義の "Parameters" フィールド内から特別なパスを使用して、タスクトークンにアクセスできます。入力あるいはコンテキストオブジェクトにアクセスするには、.$ をパラメータ名に追加してパラメータがパスになるようにまず指定します。以下では、"Parameters" 仕様内で入力およびコンテキストオブジェクトからのノードを指定します。

"Parameters": { "Input.$": "$", "TaskToken.$": "$$.Task.Token" },

いずれの場合でも、.$ をパラメータ名に追加することで、Step Functions がパスを予期するように指示します。最初のケースでは、"$" は入力全体を含むパスです。後者のケースでは、$$. はパスがコンテキストオブジェクトにアクセスすることを指定し、また、$$.Task.Token は稼働している実行のコンテキストオブジェクト内のタスクトークンの値に対してパラメータを設定します。

Amazon SQS 例では、"Resource" フィールド内の .waitForTaskToken によって、タスクトークンが返されるまで待機するように Step Functions に指示されます。"TaskToken.$": "$$.Task.Token" パラメータは、このトークンを Amazon SQS メッセージの一部として渡します。

"Send message to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue", "MessageBody": { "Message": "Hello from Step Functions!", "TaskToken.$": "$$.Task.Token" } }, "Next": "NEXT_STATE" }

コンテキストオブジェクトの詳細については、このガイドの「入力および出力処理」セクションの「Context オブジェクト」を参照してください。

待機中のタスクにハートビートタイムアウトを設定する

タスクトークンを待っているタスクは、実行が 1 年間のサービスクォータに達するまで待機します (状態のスロットリングに関連するクォータ を参照)。実行のスタックを回避するには、ステートマシン定義でハートビートタイムアウト間隔を設定できます。HeartbeatSeconds フィールドを使用して、タイムアウト間隔を指定します。

{ "StartAt": "Push based to SQS", "States": { "Push to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "HeartbeatSeconds": 600, "Parameters": { "MessageBody": { "myTaskToken.$": "$$.Task.Token" }, "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue" }, "ResultPath": "$.SQS", "End": true } } }

このステートマシン定義では、1 つのタスクがメッセージを Amazon SQS にプッシュし、外部プロセスが指定したタスクトークンとともにコールバックするまで待機します。"HeartbeatSeconds": 600 フィールドは、ハートビートタイムアウト間隔を 10 分に設定しています。タスクは、タスクトークンが次のいずれかの API アクションとともに返されるまで待機します。

待機しているタスクが 10 分以内に有効なタスクトークンを受信しない場合、タスクは States.Timeout エラー名で失敗します。

詳細については、コールバックタスクサンプルプロジェクト (コールバックパターンの例 (Amazon SQS、Amazon SNS、Lambda) ) を参照してください。