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

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

サービス統合パターン

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

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

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

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

これらの各サービス統合パターンは、[task definition] (タスク定義) の "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" }

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

ジョブの実行 (.sync)

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 Functions が待機します。AWS Batch submitJob の呼び出し後、ワークフローは停止します。ジョブが完了すると、Step Functions は次の状態に進みます。詳細については、AWS Batch の バッチジョブ (AWS Batch、Amazon SNS) の管理 サンプルプロジェクトを参照してください。

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

  • ステートマシンの実行を停止するには

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

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

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

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

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

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

注記

.sync を使用するサービス統合には追加の IAM 許可が必要です。詳細については、「統合サービスの IAM ポリシー」を参照してください。

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

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

.waitForTaskToken を AWS SDK 統合と共に使用するため、使用する API には、タスクトークンを配置するパラメータフィールドが必要です。

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

タスクトークンの例

この例では、承認ワークフローの一部としてクレジットチェックを実行するために、外部のマイクロサービスを 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) を使用して、タスクトークンにアクセスすることができます。最初の $$. は、そのパスアクセスにコンテキストオブジェクトを指定し、現在実行中のタスクのタスクトークンを取得します。

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

注記

プロセスが 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 によって、タスクトークンが返されるまで待機するように指示されます。"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 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) を参照してください。