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

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

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

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

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

統合パターンのサポート

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

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

AWS Step Functions での SDK 統合

Step Functions での統合最適化

レスポンスのリクエスト

タスク状態の "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 がタスクをキャンセルできない可能性があります。考えられる理由を次に示します (ただし、これらに限定されるものではありません)。

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

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

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

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

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

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

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

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

タスクトークンの例

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

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) を使用して、タスクトークンにアクセスすることができます。最初の は、パスが Context オブジェクトにアクセスすること$$.を指定し、実行中の現在のタスクのタスクトークンを取得します。

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

Context オブジェクトからトークンを取得する

Context オブジェクトは、実行に関する情報を含む内部 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 がパスを予期するように指示します。最初のケースでは、"$" は入力全体を含むパスです。2 番目のケースでは、 はパスが Context オブジェクトにアクセスするように$$.指定し、実行中の Context オブジェクトのタスクトークンの値に パラメータ$$.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 オブジェクトの詳細については、このガイドStep Functions の 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 を使ってコールバックパターンの例を作成する を参照してください。