翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Step Functions でサービス統合パターンを検出する サービス統合では、ステートマシンが統合 AWS サービスとどのようにやり取りするかを制御するために、さまざまな統合パターンを指定できます。 + [レスポンスのリクエスト](#connect-default) – サービスを呼び出し、Step Functions が HTTP レスポンスを受信するとすぐに次のステートに進むようにします。 + [ジョブの実行 (.sync)](#connect-sync) – サービスを呼び出し、ジョブが完了するまで Step Functions が待機するようにします。 + [タスクトークンのコールバックまで待機する](#connect-wait-token) – タスクトークンでサービスを呼び出し、トークンがペイロードとともに返されるまで Step Functions が待機するようにします。 これらの各サービス統合パターンは、[[task definition]](state-task.md) (タスク定義) の `"Resource"` フィールドで URI を作成する方法によって制御されます。 Step Functions での ASL Resource 値は一意の名前 (URI) であり、[ARN 形式](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html#arns-syntax)に準拠していますが、通常はアカウント内の実際の*リソース*を識別するものではありません。プレフィックス「`arn:aws:states:`」は、Step Functions が統合に使用する名前空間を定義します。この値の `:::` 部分は、`region` および `account-id` フィールドが空であることを示しており、これらは両方ともワークフローの実行リージョンやアカウントから推定されるため不要です。 へのレガシー統合 AWS Lambda は、リソース値が実際の Lambda 関数リソースを指定する 1 つの例外です。Step Functions コンソールではこれらのレガシーリソースが表示されますが、ASL コードを直接編集しない限り、現在のグラフィカル UI でそのようなリソースの作成や編集はできません。 ## 統合パターンのサポート Standard ワークフローと Express ワークフローは、同じ**統合**をサポートしますが、同じ**統合パターン**はサポートしていません。 + **Standard ワークフロー**は、*リクエストのレスポンス*の統合をサポートします。特定のサービスでは、*ジョブの実行 (.sync)* または*コールバックの待機 (.waitForTaskToken)*、および場合によってはその両方をサポートしています。詳細については、次の最適化された統合テーブルを参照してください。 + **Express ワークフロー**は、*リクエストのレスポンス*の統合のみをサポートします。 2 つのタイプ間の決定については、「[Step Functions でワークフロータイプを選択する](choosing-workflow-type.md)」を参照してください。 **AWS Step Functions での SDK 統合** | 統合された サービス | レスポンスのリクエスト | ジョブの実行 - *.sync* | コールバックの待機 - *.waitForTaskToken* | | --- | --- | --- | --- | | [200 を超えるサービス](supported-services-awssdk.md#supported-services-awssdk-list) | Standard と Express | サポートされません | 標準 | **Step Functions での統合最適化** | 統合された サービス | レスポンスのリクエスト | ジョブの実行 - *.sync* | コールバックの待機 - *.waitForTaskToken* | | --- | --- | --- | --- | | [Amazon API Gateway](connect-api-gateway.md) | Standard と Express | サポートされません | 標準 | | [Amazon Athena](connect-athena.md) | Standard と Express | 標準 | サポートされません | | [AWS Batch](connect-batch.md) | Standard と Express | 標準 | サポートされません | | [Amazon Bedrock](connect-bedrock.md) | Standard と Express | Standard | 標準 | | [AWS CodeBuild](connect-codebuild.md) | Standard と Express | 標準 | サポートされません | | [Amazon DynamoDB](connect-ddb.md) | Standard と Express | サポートされません | サポートされません | | [Amazon ECS/Fargate](connect-ecs.md) | Standard と Express | Standard | 標準 | | [Amazon EKS](connect-eks.md) | Standard と Express | Standard | 標準 | | [Amazon EMR](connect-emr.md) | Standard と Express | 標準 | サポートされません | | [Amazon EMR on EKS](connect-emr-eks.md) | Standard と Express | 標準 | サポートされません | | [Amazon EMR Serverless](connect-emr-serverless.md) | Standard と Express | 標準 | サポートされません | | [Amazon EventBridge](connect-eventbridge.md) | Standard と Express | サポートされません | 標準 | | [AWS Glue](connect-glue.md) | Standard と Express | 標準 | サポートされません | | [AWS Glue DataBrew](connect-databrew.md) | Standard と Express | 標準 | サポートされません | | [AWS Lambda](connect-lambda.md) | Standard と Express | サポートされません | 標準 | | [AWS Elemental MediaConvert](connect-mediaconvert.md) | Standard と Express | 標準 | サポートされません | | [Amazon SageMaker AI](connect-sagemaker.md) | Standard と Express | 標準 | サポートされません | | [Amazon SNS](connect-sns.md) | Standard と Express | サポートされません | 標準 | | [Amazon SQS](connect-sqs.md) | Standard と Express | サポートされません | 標準 | | [AWS Step Functions](connect-stepfunctions.md) | Standard と Express | Standard | 標準 | ## レスポンスのリクエスト タスク状態の `"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:region:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" } ``` この例では、Amazon SNS の [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) API を参照しています。`Publish` API の呼び出し後、ワークフローは次の状態に進みます。 **ヒント** リクエストレスポンスサービス統合パターンを使用するサンプルワークフローをデプロイするには、このガイドの入門チュートリアルの[「サービスの統合](getting-started.md#step-4-integrate-a-service)」または* AWS Step Functions 「ワークショップ*」の[「リクエストレスポンスモジュール](https://catalog.workshops.aws/stepfunctions/integrating-services/1-request-response)」を参照してください。 ## ジョブの実行 (.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 を使用したバッチジョブの管理](batch-job-notification.md)。 この (`.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 イベントを使用して `Task` ステートで指定した API をポーリングします。[クロスアカウント](concepts-access-cross-acct-resources.md) `.sync` 呼び出しの場合、Step Functions はポーリングのみを使用します。例えば、`states:StartExecution.sync` の場合、Step Functions は [DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) API に対してポーリングを実行し、割り当てられたクォータを使用します。 **ヒント** .sync 統合パターンを使用するワークフローの例をデプロイするには、*「 AWS Step Functions ワークショップ*[」の「ジョブの実行 (.sync)](https://catalog.workshops.aws/stepfunctions/integrating-services/2-sync-job)」を参照してください。 どの統合されたサービスでジョブの完了の待機 (`.sync`) がサポートされているかのリストについては、[サービスと Step Functions の統合](integrate-optimized.md) を参照してください。 **注記** `.sync` または `.waitForTaskToken` を使用するサービス統合には追加の IAM アクセス許可が必要です。詳細については、「[Step Functions が統合サービスの IAM ポリシーを生成する方法](service-integration-iam-templates.md)」を参照してください。 場合によっては、ジョブが完全に完了する前に Step Functions でワークフローを続行させたい場合もあります。これは、[タスクトークンのコールバックまで待機する](#connect-wait-token) サービス統合パターンを使用する場合と同じ方法で実現できます。そのためには、タスクトークンをジョブに渡し、[https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) または [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) API 呼び出しを使用してそれを返します。Step Functions は、その呼び出しで指定したデータを使用してタスクを完了し、ジョブのモニタリングを停止し、ワークフローを続行します。 ## タスクトークンのコールバックまで待機する コールバックタスクは、タスクトークンが返されるまでワークフローを待機させる方法を提供します。タスクには、人間による承認、サードパーティーとの統合、あるいはレガシーシステムの呼び出しまで待機することが必要になる場合があります。このようなタスクでは、ワークフローの実行が 1 年間のサービスクォータに達するまで Step Functions を一時停止して ([状態のスロットリングに関連するクォータ](service-quotas.md#service-limits-api-state-throttling) を参照)、外部のプロセスあるいはワークフローが完了するまで待機させることができます このような状況では、Step Functions を使用すると、タスクトークンを AWS SDK サービス統合、および一部の最適化されたサービス統合に渡すことができます。[https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) あるいは [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) 呼び出しでタスクがタスクトークンを受け取るまで、このタスクは停止します。 コールバックタスクトークンを使用する `Task` ステートがタイムアウトになると、新しいランダムトークンが生成されます。タスクトークンには [Context オブジェクト](input-output-contextobject.md#contextobject-access)からアクセスできます。 **注記** タスクトークンには少なくとも 1 文字が含まれている必要があり、1024 文字を超えることはできません。 AWS SDK 統合`.waitForTaskToken`で を使用するには、使用する API にタスクトークンを配置するパラメータフィールドが必要です。 **注記** タスクトークンは、同じ AWS アカウント内のプリンシパルから渡す必要があります。別の AWS アカウントのプリンシパルからトークンを送信した場合、トークンは機能しません。 **ヒント** コールバックタスクトークン統合パターンを使用するワークフローの例をデプロイするには、*「 AWS Step Functions ワークショップ*」の[「タスクトークンを使用したコールバック](https://catalog.workshops.aws/stepfunctions/integrating-services/3-callback-token)」を参照してください。 どの統合されたサービスでタスクトークンの待機 (`.waitForTaskToken`) がサポートされているかのリストについては、[サービスと Step Functions の統合](integrate-optimized.md) を参照してください。 **Topics** + [タスクトークンの例](#connect-wait-example) + [Context オブジェクトからトークンを取得する](#wait-token-contextobject) + [待機中のタスクにハートビートタイムアウトを設定する](#wait-token-hearbeat) ### タスクトークンの例 この例では、承認ワークフローの一部としてクレジットチェックを実行するために、外部のマイクロサービスを Step Functions ワークフローに統合する必要があります。Step Functions は、タスクトークンを含む Amazon SQS メッセージをメッセージの一部として公開します。1 つの外部システムが Amazon SQS に統合され、キューからメッセージを引き出します。これが完了すると、結果および元のタスクトークンが返されます。それから、Step Functions は ワークフローを続けます。 ![\[タスクトークンが返されるまで待機する SQS タスク\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/wait-for-task-token.png) 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 オブジェクト](#wait-token-contextobject)を指定し、現在実行中のタスクのタスクトークンを取得します。 完了すると、外部サービスは `taskToken` を含めて [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) または [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) を呼び出します。この時点でのみ、ワークフローが次の状態へと続行します。 **注記** プロセスが `SendTaskSuccess` または `SendTaskFailure` とともにタスクトークンを送信することに失敗した場合に無期限に待機することを回避するには、[待機中のタスクにハートビートタイムアウトを設定する](#wait-token-hearbeat) を参照してください。 ### Context オブジェクトからトークンを取得する Context オブジェクトは、実行に関する情報が含まれた内部の JSON オブジェクトです。状態の入力と同様に、実行中に `"Parameters"` フィールドからパスを使用してこれにアクセスできます。タスクの定義内からアクセスすると、これにはタスクトークンを含めた特定の実行に関する情報が含まれます。 ``` { "Execution": { "Id": "arn:aws:states:region:account-id:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::account-id: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:region:account-id:stateMachine:stateMachineName", "Name": "name" }, "Task": { "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W" } } ``` タスク定義の `"Parameters"` フィールド内から特別なパスを使用して、タスクトークンにアクセスできます。入力あるいは Context オブジェクトにアクセスするには、`.$` をパラメータ名に追加してパラメータがパスになるようにまず指定します。以下では、`"Parameters"` 仕様内で入力および Context オブジェクトからのノードを指定します。 ``` "Parameters": { "Input.$": "$", "TaskToken.$": "$$.Task.Token" }, ``` いずれの場合でも、`.$` をパラメータ名に追加することで、Step Functions がパスを予期するように指示します。最初のケースでは、`"$"` は入力全体を含むパスです。後者のケースでは、`$$.` はパスが Context オブジェクトにアクセスすることを指定し、また、`$$.Task.Token` は稼働している実行の Context オブジェクト内のタスクトークンの値に対してパラメータを設定します。 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 オブジェクトの詳細については、このガイドの [入力および出力処理](concepts-input-output-filtering.md) セクションの [Step Functions の Context オブジェクトから実行データにアクセスする](input-output-contextobject.md) を参照してください。 ### 待機中のタスクにハートビートタイムアウトを設定する タスクトークンを待っているタスクは、実行が 1 年間のサービスクォータに達するまで待機します ([状態のスロットリングに関連するクォータ](service-quotas.md#service-limits-api-state-throttling) を参照)。実行のスタックを回避するには、ステートマシン定義でハートビートタイムアウト間隔を設定できます。[`HeartbeatSeconds`](state-task.md) フィールドを使用して、タイムアウト間隔を指定します。 ``` { "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 アクションとともに返されるまで待機します。 + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html) 待機しているタスクが 10 分以内に有効なタスクトークンを受信しない場合、タスクは `States.Timeout` エラー名で失敗します。 詳細については、コールバックタスクサンプルプロジェクト [Amazon SQS、Amazon SNS、Lambda を使ってコールバックパターンの例を作成する](callback-task-sample-sqs.md) を参照してください。