統合パターンのサポートレスポンスのリクエストジョブの実行 (.sync)コールバックを待つ

Step Functions でサービス統合パターンを検出する

AWS Step Functions は、Amazon States Language のサービスと直接統合します。これらを制御できます。 AWS 3 つのサービス統合パターンを使用するのサービス：

サービスを呼び出し、HTTPレスポンスを受け取った直後に Step Functions を次の状態に移行させます。
サービスを呼び出し、ジョブが完了するまで Step Functions が待機するようにします。
タスクトークンでサービスを呼び出し、トークンがペイロードとともに返されるまで Step Functions が待機するようにします。

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

の設定の詳細については、 AWS Identity and Access Management （IAM) 統合サービスについては、「」を参照してくださいStep Functions が統合サービスのIAMポリシーを生成する方法。

統合パターンのサポート

標準ワークフローと Express ワークフローは、同じ統合をサポートしますが、同じ統合パターン はサポートしません。

標準ワークフローは、リクエストレスポンスの統合をサポートします。特定のサービスは、ジョブの実行 (.sync) またはコールバックの待機 (.waitForTaskToken) をサポートし、場合によっては両方をサポートします。詳細については、次の最適化された統合の表を参照してください。
Express ワークフローは、リクエストレスポンス統合のみをサポートします。

2 つのタイプ間の決定については、「」を参照してくださいStep Functions でのワークフロータイプの選択。

AWS SDK Step Functions での統合

統合されたサービス	レスポンスのリクエスト	ジョブの実行 - .sync	コールバックを待つ - .waitForTaskToken
200 を超えるサービス	Standard と Express	サポートされません	標準

Step Functions での統合の最適化

統合されたサービス	レスポンスのリクエスト	ジョブの実行 - .sync	コールバックを待つ - .waitForTaskToken
Amazon API Gateway	Standard と Express	サポートされません	標準
Amazon Athena	Standard と Express	標準	サポートされません
AWS Batch	Standard と Express	標準	サポートされません
Amazon Bedrock	Standard と Express	標準	標準
AWS CodeBuild	Standard と Express	標準	サポートされません
Amazon DynamoDB	Standard と Express	サポートされません	サポートされません
Amazon ECS/Fargate	Standard と Express	標準	標準
Amazon EKS	Standard と Express	標準	標準
Amazon EMR	Standard と Express	標準	サポートされません
Amazon EMR on EKS	Standard と Express	標準	サポートされません
Amazon EMR Serverless	Standard と Express	標準	サポートされません
Amazon EventBridge	Standard と Express	サポートされません	標準
AWS Glue	Standard と Express	標準	サポートされません
AWS Glue DataBrew	Standard と Express	標準	サポートされません
AWS Lambda	Standard と Express	サポートされません	標準
AWS Elemental MediaConvert	Standard と Express	標準	サポートされません
Amazon SageMaker	Standard と Express	標準	サポートされません
Amazon SNS	Standard と Express	サポートされません	標準
Amazon SQS	Standard と Express	サポートされません	標準
AWS Step Functions	Standard と Express	標準	標準

レスポンスのリクエスト

タスク状態の"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 APIの公開」を参照していますSNS。ワークフローは、 Publish を呼び出した後、次の状態に進みますAPI。

ヒント

リクエストレスポンスサービス統合パターンを使用するサンプルワークフローをにデプロイするには AWS アカウント、「モジュール 2 - のリクエストレスポンス」を参照してください。 AWS Step Functions ワークショップ 。

ジョブの実行 (.sync)

などの統合サービスの場合 AWS Batch および Amazon ではECS、Step Functions はリクエストが完了するのを待ってから次の状態に進むことができます。Step Functions を待機させるには、タスク状態定義の "Resource"フィールドを、リソース .sync の後にサフィックスを付けて指定しますURI。

例えば、 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 StopExecutionAPIアクションを呼び出します。ただし、Step Functions がタスクをキャンセルできない可能性があります。考えられる理由を次に示します (ただし、これらに限定されるものではありません)。

IAM 実行ロールには、対応するAPI呼び出しを行うアクセス許可がありません。
一時的なサービス停止が発生しました。

.sync サービス統合パターンを使用すると、Step Functions は割り当てられたクォータとイベントを消費するポーリングを使用してジョブのステータスをモニタリングします。同じアカウント内の呼び出し.syncの場合、Step Functions は EventBridge イベントを使用し、 Task状態で指定した APIs をポーリングします。クロスアカウント .sync 呼び出しの場合、Step Functions はポーリングのみを使用します。例えば、の場合states:StartExecution.sync、Step Functions はでポーリングを実行しDescribeExecutionAPI、割り当てられたクォータを使用します。

ヒント

Run a Job (.sync) サービス統合パターンを使用するサンプルワークフローをにデプロイするには AWS アカウント、「」の「モジュール 3 - ジョブを実行する (.sync)」を参照してください。 AWS Step Functions ワークショップ 。

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

注記

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

場合によっては、ジョブが完全に完了する前に Step Functions でワークフローを続行させたい場合もあります。これは、タスクトークンによるコールバックを待つサービス統合パターンを使用する場合と同じ方法で実現できます。これを行うには、タスクトークンをジョブに渡し、 SendTaskSuccessまたは SendTaskFailureAPI呼び出しを使用して返します。Step Functions は、その呼び出しで指定したデータを使用してタスクを完了し、ジョブのモニタリングを停止し、ワークフローを続行します。

タスクトークンによるコールバックを待つ

コールバックタスクは、タスクトークンが返されるまでワークフローを待機させる方法を提供します。タスクには、人間による承認、サードパーティーとの統合、あるいはレガシーシステムの呼び出しまで待機することが必要になる場合があります。このようなタスクでは、ワークフローの実行が 1 年間のサービスクォータに達するまで Step Functions を一時停止して (状態のスロットリングに関連するクォータを参照)、外部のプロセスあるいはワークフローが完了するまで待機させることができますこのような状況では、Step Functions によりタスクトークンをに渡すことができます。 AWS SDK サービス統合、および一部の Optimized サービス統合。SendTaskSuccess あるいは SendTaskFailure 呼び出しでタスクがタスクトークンを受け取るまで、このタスクは停止します。

コールバックタスクトークンを使用する Task ステートがタイムアウトになると、新しいランダムトークンが生成されます。タスクトークンには、コンテキストオブジェクトからアクセスできます

注記

タスクトークンには少なくとも 1 文字が含まれている必要があり、1024 文字を超えることはできません。

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

注記

同じ内のプリンシパルからタスクトークンを渡す必要があります AWS アカウント。別ののプリンシパルからトークンを送信した場合、トークンは機能しません。 AWS アカウント。

ヒント

コールバックタスクトークンサービス統合パターンを使用するサンプルワークフローをにデプロイするには AWS アカウント、「モジュール 4 - のタスクトークンでコールバックを待つ」を参照してください。 AWS Step Functions ワークショップ 。

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

トピック

タスクトークンの例
コンテキストオブジェクトからトークンを取得する
待機中のタスクにハートビートタイムアウトを設定する

タスクトークンの例

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

Amazon を参照するタスク定義の "Resource"フィールドSQSには、末尾に .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でタスクトークンが返されるのを待つように 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"
                }

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

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

タスクトークンを待っているタスクは、実行が 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
                }
                }
                }

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

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

詳細については、コールバックタスクサンプルプロジェクト Amazon 、Amazon SQS、SNSおよび Lambda を使用してコールバックパターンの例を作成するを参照してください。

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

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

ドキュメントの表記規則

サービスとの統合

サードパーティーを呼び出す APIs