翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Task ワークフロー状態
**ステートの管理とデータの変換**
[変数を使用したステート間のデータ受け渡し](workflow-variables.md)と [JSONata を使用したデータ変換](transforming-data.md)について説明します。
`Task` 状態 (`"Type": "Task"`) は、ステートマシンによって実行される単一の作業単位を表します。タスクは、アクティビティまたは AWS Lambda 関数を使用するか、[サポートされている AWS のサービス](supported-services-awssdk.md#supported-services-awssdk-list)他の と統合するか、Stripe などの HTTPS API を呼び出して作業を実行します。
[Amazon States Language](concepts-amazon-states-language.md) は、ステートのタイプを `Task` に設定し、タスクにアクティビティ、Lambda 関数、または HTTPS API エンドポイントの Amazon リソースネーム (ARN) を指定することによりタスクを表します。
**JSONata の Arguments を使用して関数を呼び出す**
次の Task ステート定義 (JSONata) は、`priceWatcher` という名前の Lambda 関数を呼び出します。
Arguments で使用する入力データや、assign フィールドで使用するタスクの結果を取得するために、JSONata 式を使用している点に注目してください。
```
"Get Current Price": {
"Type": "Task",
"QueryLanguage" : "JSONata",
"Resource": "arn:aws:states:::lambda:invoke",
"Next": "Check Price",
"Arguments": {
"Payload": {
"product": "{% $states.context.Execution.Input.product %}"
},
"FunctionName": "arn:aws:lambda::account-id:function:priceWatcher:$LATEST"
},
"Assign": {
"currentPrice": "{% $states.result.Payload.current_price %}"
}
}
```
**JSONPath パラメータを使用して関数を呼び出す**
次の Task ステート定義 (JSONPath) は、`HelloFunction` という名前の Lambda 関数を呼び出します。
```
"Lambda Invoke": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:region:account-id:function:HelloFunction:$LATEST"
},
"End": true
}
```
## タスクタイプ
Step Functions では、Task 状態定義内で指定できる次のタスクタイプをサポートしています。
+ [アクティビティ](#state-task-activity)
+ [Lambda 関数](#state-task-lambda)
+ [サポートされる AWS のサービス](#state-task-connector)
+ [HTTP タスク](call-https-apis.md)
タスクタイプを指定するには、タスク状態定義の `Resource` フィールドに ARN を指定します。次の例は、`Resource` フィールドの構文を示しています。HTTPS API を呼び出すタスクタイプを除くすべてのタスクタイプは、次の構文を使用します。HTTP 構文の詳細については、「[Step Functions ワークフローで HTTPS API を呼び出す](call-https-apis.md)」を参照してください。
タスク状態定義で、次の構文の斜体のテキストを AWS リソース固有の情報に置き換えます。
```
arn:partition:service:region:account:task_type:name
```
次のリストでは、この構文の個々のコンポーネントについて説明します。
+ `partition` は使用する AWS Step Functions パーティションで、最も一般的には です`aws`。
+ `service` はタスクの実行 AWS のサービス に使用される を示し、次のいずれかの値を指定できます。
+ `states`アクティビティ[に](#state-task-activity)。
+ [Lambda 関数](#state-task-lambda) (`lambda`) を実行します。Amazon SNS や Amazon DynamoDB AWS のサービスなどの他の と統合する場合は、 `sns`または を使用します`dynamodb`。
+ `region` は、Step Functions アクティビティまたはステートマシンタイプ、Lambda 関数、またはその他の AWS リソースが作成された[AWS リージョンコード](https://docs.aws.amazon.com/general/latest/gr/rande.html)です。
+ `account` は、リソースを定義した AWS アカウント ID です。
+ `task_type` は実行するタスクのタイプです。これには、次のいずれかの値を指定できます。
+ `activity` – [アクティビティ](#state-task-activity)。
+ `function` - [Lambda 関数](#state-task-lambda)。
+ `servicename` - サポートされた接続サービスの名前 ([サービスと Step Functions の統合](integrate-optimized.md) を参照)。
+ `name` はメンバーリソース名 (アクティビティ名、 Lambda 関数名、またはサービス API アクション) です。
**注記**
Step Functions は、パーティションまたはリージョン間の ARN の参照をサポートしていません。例えば、`aws-cn` は `aws` パーティション内のタスクを呼び出すことはできません。その逆も同様です。
次のセクションでは、各タスクタイプの詳細を示します。
### アクティビティ
アクティビティは、お客様によって実装およびホストされ、特定のタスクを実行するワーカー (プロセスまたはスレッド) を示します。標準ワークフローでのみサポートされ、Express ワークフローではサポートされません。
アクティビティ `Resource` ARN は以下の構文を使用します。
```
arn:partition:states:region:account:activity:name
```
**注記**
アクティビティは、最初に使用する前に Step Functions ([CreateActivity](https://docs.aws.amazon.com/step-functions/latest/apireference/API_CreateActivity.html)、API アクション、または [Step Functions コンソール](https://console.aws.amazon.com/states/home?region=us-east-1#/)を使用) で作成しておく必要があります。
アクティビティの作成とワーカーの実装の詳細については、[アクティビティ](concepts-activities.md)を参照してください。
### Lambda 関数
Lambda タスクは、 を使用して関数を実行します AWS Lambda。Lambda 関数を指定するには、`Resource` フィールドの Lambda 関数の ARN を使用します。
Lambda 関数の `Resource` フィールドの形式は統合のタイプによって異なります。
Lambda 関数との標準 AWS SDK 統合の場合、 `Resource`フィールドには次の値が含まれます。
```
"arn:aws:states:::aws-sdk:lambda:invoke"
```
Lambda 関数には最適化統合を使用することを**お勧め**します。`Resource` フィールドには次の値を指定します。
```
"arn:aws:states:::lambda:invoke"
```
次の `Task` ステート定義は、`HelloWorld` という名前の Lambda 関数との JSONata を使用した最適化統合の例です。
```
"Optimized call to Lambda function (JSONata)": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Output": "{% $states.result.Payload %}",
"Arguments": {
"FunctionName": "arn:aws:lambda:region:account-id:function:HelloWorld:$LATEST",
"Payload": {
"key": "{% $states.input.myKey %}"
}
},
"Next": "NextState"
}
```
### サポートされる AWS のサービス
接続されたリソースをリファレンスすると、Step Functions によって、サポートされたサービスの API アクションが直接呼び出されます。`Resource` フィールドでサービスとアクションを指定します。
接続されたサービス `Resource` ARN では以下の構文を使用します。
```
arn:partition:states:region:account-id:servicename:APIname
```
**注記**
接続されたリソースへの同期接続を作成するには、`.sync` を ARN の *APIname* エントリに付加します。詳細については、「[ サービスとの統合](integrate-services.md)」を参照してください。
例えば、次のようになります。
```
{
"StartAt": "BATCH_JOB",
"States": {
"BATCH_JOB": {
"Type": "Task",
"Resource": "arn:aws:states:::batch:submitJob.sync",
"Parameters": {
"JobDefinition": "preprocessing",
"JobName": "PreprocessingBatchJob",
"JobQueue": "SecondaryQueue",
"Parameters.$": "$.batchjob.parameters",
"RetryStrategy": {
"attempts": 5
}
},
"End": true
}
}
}
```
## タスク状態フィールド
[[common state fields]](statemachine-structure.md#amazon-states-language-common-fields) (共通状態フィールド) に加えて、`Task` 状態には次のフィールドがあります。
** `Resource` (必須)**
URI (特に、実行する特定のタスクを一意に識別する ARN)。
**`Arguments` (オプション、JSONata のみ)**
接続されたリソースの API アクションに情報を渡すのに使用します。値には JSONata 式を含めることができます。詳細については、「[Step Functions での JSONata を使用したデータ変換](transforming-data.md)」を参照してください。
**`Output` (オプション、JSONata のみ)**
ステートからの出力を指定して変換するために使用します。指定すると、ステートのデフォルト出力がオーバーライドされます。
Output フィールドは、あらゆる型の JSON 値 (オブジェクト、配列、文字列、数値、boolean、null) を受け入れます。すべての文字列値は、オブジェクトや配列内の値を含め、\$1% %\$1 文字で囲まれていれば、JSONata として評価されます。
Output は JSONata 式を直接受け入れることもできます。例: "Output": "\$1% jsonata expression %\$1"
詳細については、[入力および出力処理](concepts-input-output-filtering.md)を参照してください。
**`Parameters` (オプション、JSONPath のみ)**
接続されたリソースの API アクションに情報を渡すのに使用します。パラメータには静的な JSON と [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) を組み合わせて使用できます。詳細については、「[Step Functions でサービス API にパラメータを渡す](connect-parameters.md)」を参照してください。
**`Credentials` (オプション)**
指定した `Resource` を呼び出す前にステートマシンの実行ロールが継承する必要があるターゲットロールを指定します。または、実行入力に基づいて実行時に IAM ロール ARN を解決する JSONPath 値または[組み込み関数](intrinsic-functions.md)を指定することもできます。JSONPath 値を指定する場合は、`$.` 表記をプレフィックスとして付ける必要があります。
このフィールドを `Task` 状態で使用した例については、「[タスク状態の認証情報フィールドの例](#task-state-example-credentials)」を参照してください。このフィールドを使用してステートマシンからクロスアカウント AWS リソースにアクセスする例については、「」を参照してください[Step Functions でのクロスアカウント AWS リソースへのアクセス](tutorial-access-cross-acct-resources.md)。
このフィールドは、[Lambda 関数](#state-task-lambda)とサポートされているサービス[タスクタイプ](#task-types)を使用する でサポートされています。 [AWS](integrate-services.md)
** `ResultPath` (オプション、JSONPath のみ)**
`Resource` で指定されたタスクを実行した結果を配置する場所 (入力内) を指定します。その後、入力は `OutputPath` フィールド (ある場合) に従ってフィルタリングされてから状態の出力に使用されます。詳細については、[入力および出力処理](concepts-input-output-filtering.md)を参照してください。
** `ResultSelector` (オプション、JSONPath のみ)**
値が静的であるか、結果から選択されたキーバリューのペアの集合を渡します。詳細については、「[ResultSelector](input-output-inputpath-params.md#input-output-resultselector)」を参照してください。
** `Retry` (オプション)**
Retrier と呼ばれるオブジェクトの配列。状態でランタイムエラーが発生した場合の再試行ポリシーを定義します。詳細については、「[Retry と Catch を使用するステートマシンの例](concepts-error-handling.md#error-handling-examples)」を参照してください。
** `Catch` (オプション)**
Catcher と呼ばれるオブジェクトの配列で、フォールバック状態を定義します。この状態は、状態にランタイムエラーが発生し、その再試行ポリシーが使い果たされたか定義されていない場合に実行されます。詳細については、「[フォールバック状態](concepts-error-handling.md#error-handling-fallback-states)」を参照してください。
** `TimeoutSeconds` (オプション)**
アクティビティまたはタスクが [States.Timeout](concepts-error-handling.md#statestimeout) エラーでタイムアウトして失敗するまでに実行できる最大時間を指定します。タイムアウトの値はゼロ以外の正の整数にする必要があります。デフォルト値は `99999999` です。
タイムアウトのカウントは、`TaskStarted`、`ActivityStarted`、または `LambdaFunctionStarted` イベントが実行イベント履歴に記録されたときなど、開始イベントが実行されたときに開始されます。アクティビティにおいては、`GetActivityTask` がトークンを受信し、`ActivityStarted` が実行イベント履歴にログインされると、カウントが開始します。
タスクが開始されると、Step Functions は指定された `TimeoutSeconds` 期間内にタスクまたはアクティビティワーカーからの成功または失敗の応答を待ちます。タスクまたはアクティビティのワーカーがこの時間内の応答に失敗した場合、Step Functions はワークフロー実行を失敗としてマークします。
HTTP タスクタイムアウトは、`TimeoutSeconds` がその制限を超えた場合でも、最大 60 秒です。「[HTTP タスクに関連するクォータ](service-quotas.md#service-limits-http-task)」を参照してください。
** `TimeoutSecondsPath` (オプション、JSONPath のみ)**
リファレンスパスを使用して状態の入力からタイムアウト値を動的に指定したい場合は、`TimeoutSecondsPath` を使用してください。解決されると、リファレンスパスは、値が正の整数のフィールドを選択する必要があります。
`Task` 状態には `TimeoutSeconds` と `TimeoutSecondsPath` の両方を含めることはできません。HTTP タスクタイムアウトは、`TimeoutSecondsPath` 値がその制限を超えた場合でも、最大 60 秒です。
** `HeartbeatSeconds` (オプション)**
タスクの実行中にアクティビティワーカーが送信するハートビートシグナルの頻度を決定します。ハートビートは、タスクがまだ実行中で、完了するまでにさらに時間がかかることを示します。ハートビートは、アクティビティやタスクが `TimeoutSeconds` 期間内にタイムアウトするのを防ぎます。
`HeartbeatSeconds` は `TimeoutSeconds` フィールド値より小さい 0 以外の正の整数値でなければなりません。デフォルト値は `99999999` です。タスクからのハートビートの間隔が指定された秒数よりも長くなる場合、タスク状態は [States.Timeout](concepts-error-handling.md#statestimeout) エラーで失敗します。
アクティビティにおいては、`GetActivityTask` がトークンを受信し、`ActivityStarted` が実行イベント履歴にログインされると、カウントが開始します。
** `HeartbeatSecondsPath` (オプション、JSONPath のみ)**
リファレンスパスを使用して状態の入力からハートビート値を動的に指定したい場合は、`HeartbeatSecondsPath` を使用します。解決されると、リファレンスパスは、値が正の整数のフィールドを選択する必要があります。
`Task` 状態には `HeartbeatSeconds` と `HeartbeatSecondsPath` の両方を含めることはできません。
`Task` 状態は、その状態で実行が終了する場合は `End` フィールドが `true` に設定されている必要があります。または、`Next` フィールドに、`Task` 状態が完了した際に実行される状態を指定する必要があります。
## タスク状態定義の例
次の例は、要件に基づいてタスク状態定義を指定する方法を示しています。
+ [タスク状態のタイムアウトとハートビート間隔](#task-state-example-timeouts)
+ [静的タイムアウトとハートビート通知の例](#task-state-example-static)
+ [動的タスクタイムアウトとハートビート通知の例](#task-state-example-dynamic)
+ [認証情報フィールドの使用](#task-state-example-credentials)
+ [ハードコーディングされた IAM ロール ARN の指定](#example-credentials-specify-role-arn)
+ [IAM ロール ARN として JSONPath を指定](#example-credentials-specify-dynamic-jsonpath)
+ [組み込み関数を IAM ロール ARN として指定する](#example-credentials-specify-dynamic-intrinsic-function)
### タスク状態のタイムアウトとハートビート間隔
長時間実行されるアクティビティでは、タイムアウト値とハートビート間隔を設定することをお勧めします。これは、タイムアウトとハートビート値を指定するか、動的に設定することによって実行できます。
#### 静的タイムアウトとハートビート通知の例
`HelloWorld` が完了すると、次の状態 (ここでは `NextState` と呼ばれます) が実行されます。
このタスクが 300 秒以内に完了しなかった場合、または 60 秒間隔のハートビート通知を送信しなかった場合、タスクは `failed` とマークされます。
```
"ActivityState": {
"Type": "Task",
"Resource": "arn:aws:states:region:123456789012:activity:HelloWorld",
"TimeoutSeconds": 300,
"HeartbeatSeconds": 60,
"Next": "NextState"
}
```
#### 動的タスクタイムアウトとハートビート通知の例
この例では、 AWS Glue ジョブが完了すると、次の状態が実行されます。
このタスクが、 AWS Glue ジョブによって動的に設定された間隔内に完了しなかった場合、タスクは `failed` としてマークされます。
```
"GlueJobTask": {
"Type": "Task",
"Resource": "arn:aws:states:::glue:startJobRun.sync",
"Parameters": {
"JobName": "myGlueJob"
},
"TimeoutSecondsPath": "$.params.maxTime",
"Next": "NextState"
}
```
### タスク状態の認証情報フィールドの例
#### ハードコーディングされた IAM ロール ARN の指定
次の例では、ステートマシンの実行ロールが `Echo` という名前のクロスアカウント Lambda 関数にアクセスするために継承する必要がある、ターゲット IAM ロールを指定します。この例では、ターゲットロールの ARN はハードコードされた値として指定されています。
```
{
"StartAt": "Cross-account call",
"States": {
"Cross-account call": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn": "arn:aws:iam::111122223333:role/LambdaRole"
},
"Parameters": {
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:Echo"
},
"End": true
}
}
}
```
#### IAM ロール ARN として JSONPath を指定
次の例では、実行時に IAM ロール ARN を解決する JSONPath 値を指定します。
```
{
"StartAt": "Lambda",
"States": {
"Lambda": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn.$": "$.roleArn"
},
...
}
}
}
```
#### 組み込み関数を IAM ロール ARN として指定する
次の例では、実行時に IAM ロール ARN を解決する、[`States.Format`](intrinsic-functions.md#asl-intrsc-func-generic) 組み込み関数を使用しています。
```
{
"StartAt": "Lambda",
"States": {
"Lambda": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn.$": "States.Format('arn:aws:iam::{}:role/ROLENAME', $.accountId)"
},
...
}
}
}
```