本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 任務工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](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 Resource Name (ARN)。
**使用 JSONata 引數調用函數**
下列任務狀態定義 (JSONata) 會叫用名為 的 Lambda 函數`priceWatcher`。
請注意，使用 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 參數調用函數**
下列任務狀態定義 (JSONPath) 會叫用名為 的 Lambda 函數`HelloFunction`。
```
"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 支援下列您可以在任務狀態定義中指定的任務類型：
+ [活動](#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 APIs](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` 適用於 [Lambda 函數](#state-task-lambda)。如果您與其他 整合 AWS 服務，例如 Amazon SNS 或 Amazon DynamoDB，請使用 `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 不支援跨分割區或區域參考 ARNs。例如， `aws-cn` 無法叫用`aws`分割區中的任務，反之亦然。
下列各節會提供每個任務類型的詳細資訊。
### 活動
活動代表由您實作和託管並可執行特定任務的工作者 (程序或執行緒)。活動僅受到標準工作流程支援，不受快速工作流程支持。
活動 `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` JSONata 與名為 的 Lambda 函數進行最佳化整合的範例。
```
"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
}
}
}
```
## 任務狀態欄位
除了[常見狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)以外，`Task` 狀態還有下列欄位。
** `Resource` (必要)**
URI，特別是能夠唯一識別要執行特定任務的 ARN。
**`Arguments` （選用，僅限 JSONata)**
用來將資訊傳遞給已連線資源的 API 動作。值可以包含 JSONata 表達式。如需詳細資訊，請參閱[在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
**`Output` （選用，僅限 JSONata)**
用來指定和轉換 狀態的輸出。指定時，值會覆寫狀態輸出預設值。
輸出欄位接受任何 JSON 值 （物件、陣列、字串、數字、布林值、 null)。任何字串值，包括物件或陣列內的值，如果被 \$1% %\$1 個字元包圍，將評估為 JSONata。
輸出也直接接受 JSONata 表達式，例如：「輸出」：「\$1% jsonata 表達式 %\$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`。或者，您也可以指定 JSONPath 值或[內部函數](intrinsic-functions.md)，根據執行輸入在執行時間解析為 IAM 角色 ARN。如果您指定 JSONPath 值，則必須在它前面加上 `$.` 符號。
如需在 `Task` 狀態中使用此欄位的範例，請參閱 [任務狀態的登入資料欄位範例](#task-state-example-credentials)。如需使用此欄位從您的狀態機器存取跨帳戶 AWS 資源的範例，請參閱 [在 Step Functions 中存取跨帳戶 AWS 資源](tutorial-access-cross-acct-resources.md)。
使用 [Lambda 函數](#state-task-lambda)和[支援的 AWS 服務](integrate-services.md)[任務類型](#task-types)支援此欄位。
** `ResultPath` （選用，僅限 JSONPath)**
指定要將執行 `Resource` 中所指定任務的結果放置於何處 (在輸入中)。輸入會先依據 `OutputPath` 欄位 (如果有的話) 所指定篩選，而後做為狀態的輸出。如需詳細資訊，請參閱[輸入和輸出處理](concepts-input-output-filtering.md)。
** `ResultSelector` （選用，僅限 JSONPath)**
傳遞金鑰值對的集合，其中值為靜態或從結果中選取。如需詳細資訊，請參閱[ResultSelector](input-output-inputpath-params.md#input-output-resultselector)。
** `Retry` (選用)**
稱為 Retrier 的物件陣列，這類物件可定義狀態發生執行時間錯誤時的重試政策。如需詳細資訊，請參閱[使用重試和擷取的狀態機器範例](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`。
逾時計數會在執行啟動事件時開始，例如在執行`LambdaFunctionStarted`事件歷史記錄中記錄 `ActivityStarted`、 `TaskStarted`或 事件時。對於活動，計數會在 `GetActivityTask`收到字符`ActivityStarted`時開始，並記錄在執行事件歷史記錄中。
當任務啟動時，Step Functions 會在指定的`TimeoutSeconds`持續時間內等待任務或活動工作者的成功或失敗回應。如果任務或活動工作者無法在這段時間內回應，Step Functions 會將工作流程執行標記為失敗。
HTTP 任務逾時最多可有 60 秒，即使 `TimeoutSeconds`超過該限制也一樣。請參閱 [與 HTTP 任務相關的配額](service-quotas.md#service-limits-http-task)
** `TimeoutSecondsPath` （選用，僅限 JSONPath)**
如果您想要使用參考路徑從狀態輸入動態提供逾時值，請使用 `TimeoutSecondsPath`。解析後，參考路徑必須選取值為正整數的欄位。
`Task` 狀態不能同時包含 `TimeoutSeconds`和 `TimeoutSecondsPath`。HTTP 任務逾時最多可有 60 秒，即使該`TimeoutSecondsPath`值超過該限制也一樣。
** `HeartbeatSeconds` (選用)**
決定活動工作者在執行任務期間傳送的活動訊號頻率。活動訊號表示任務仍在執行中，需要更多時間才能完成。活動訊號可防止活動或任務在`TimeoutSeconds`持續時間內逾時。
`HeartbeatSeconds` 必須是小於`TimeoutSeconds`欄位值的正非零整數值。預設值為 `99999999`。如果任務的訊號之間經過的時間超過指定的秒數，任務狀態會失敗並顯示[States.Timeout](concepts-error-handling.md#statestimeout)錯誤。
對於活動，計數會在 `GetActivityTask`收到字符`ActivityStarted`時開始，並記錄在執行事件歷史記錄中。
** `HeartbeatSecondsPath` （選用，僅限 JSONPath)**
如果您想要使用參考路徑從狀態輸入動態提供活動訊號值，請使用 `HeartbeatSecondsPath`。解析後，參考路徑必須選取值為正整數的欄位。
`Task` 狀態不能同時包含 `HeartbeatSeconds`和 `HeartbeatSecondsPath`。
如果狀態結束執行，則 `Task` 狀態必須將 `End` 欄位設定為 `true`，或必須在 `Task` 狀態完成時於 `Next` 欄位中提供執行的狀態。
## 任務狀態定義範例
下列範例示範如何根據您的需求指定任務狀態定義。
+ [指定任務狀態逾時和活動訊號間隔](#task-state-example-timeouts)
+ [靜態逾時和活動訊號通知範例](#task-state-example-static)
+ [動態任務逾時和活動訊號通知範例](#task-state-example-dynamic)
+ [使用登入資料欄位](#task-state-example-credentials)
+ [指定硬式編碼的 IAM 角色 ARN](#example-credentials-specify-role-arn)
+ [將 JSONPath 指定為 IAM 角色 ARN](#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
下列範例指定狀態機器執行角色必須擔任的目標 IAM 角色，才能存取名為 的跨帳戶 Lambda 函數`Echo`。在此範例中，目標角色 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
}
}
}
```
#### 將 JSONPath 指定為 IAM 角色 ARN
下列範例指定 JSONPath 值，該值將在執行時間解析為 IAM 角色 ARN。
```
{
"StartAt": "Lambda",
"States": {
"Lambda": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn.$": "$.roleArn"
},
...
}
}
}
```
#### 將內部函數指定為 IAM 角色 ARN
下列範例使用[`States.Format`](intrinsic-functions.md#asl-intrsc-func-generic)內部 函數，其會在執行時間解析為 IAM 角色 ARN。
```
{
"StartAt": "Lambda",
"States": {
"Lambda": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Credentials": {
"RoleArn.$": "States.Format('arn:aws:iam::{}:role/ROLENAME', $.accountId)"
},
...
}
}
}
```