レスポンスのリクエストジョブの実行 (.sync)タスクトークンのコールバックまで待機する

サービス統合パターン

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

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

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

統合サービスの設定 AWS Identity and Access Management (IAM) については、を参照してください。統合サービスの IAM ポリシー

レスポンスのリクエスト

タスク状態の "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 の呼び出し後、ワークフローは次の状態に進みます。

ヒント

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

ジョブの実行 (.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同じアカウント内での呼び出しの場合、Step Functions EventBridge はイベントを使用して、ステートで指定した API をポーリングします。Taskクロスアカウント .sync 呼び出しの場合、Step Functions はポーリングのみを使用します。たとえば、の場合states:StartExecution.sync、Step Functions は DescribeExecutionAPI に対してポーリングを実行し、割り当てられたクォータを使用します。

ヒント

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

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

注記

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

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

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

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

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

注記

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

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

注記

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

ヒント

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

どの統合されたサービスでタスクトークンの待機 (.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) を使用して、タスクトークンにアクセスすることができます。最初の $$. は、そのパスアクセスにコンテキストオブジェクトを指定し、現在実行中のタスクのタスクトークンを取得します。

完了すると、外部サービスが 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"
}

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

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

タスクトークンを待っているタスクは、実行が 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) を参照してください。

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

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

ドキュメントの表記規則

サードパーティーの API を呼び出す

サービス API にパラメータを渡す