本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 探索要在 Step Functions 中使用的工作流程狀態
*狀態*是狀態機器中的元素。狀態會使用自身的*名稱*來稱呼，這可以是任何字串，但在整個狀態機器範圍內必須是唯一的。
狀態會從調用或先前的狀態取得輸入。狀態可以篩選輸入，然後操作傳送至下一個狀態的輸出。
以下是名為 的範例狀態`HelloWorld`，可叫用 AWS Lambda函數。
```
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:HelloFunction",
"Next": "AfterHelloWorldState",
"Comment": "Run the HelloWorld Lambda function"
}
```
個別狀態可以根據其輸入做出決策、從這些輸入執行動作，並將輸出傳遞給其他狀態。在 中AWS Step Functions，您可以使用 Amazon States Language (ASL) 定義工作流程。Step Functions 主控台提供狀態機器的圖形表示，以協助視覺化應用程式的邏輯。
下列螢幕擷取畫面顯示工作流程 Studio 中一些最熱門**的動作**和七個**流程**狀態：
![\[顯示 Workflow Studio 中熱門動作和流程狀態的說明性螢幕擷取畫面\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/wfs-actions-flow-panel.png)
狀態有許多常見的功能：
+ 指出其狀態類型的`Type`欄位。
+ 選用`Comment`欄位，用於保留狀態的人類可讀註解或描述。
+ 每個狀態 ( `Succeed`或 `Fail` 狀態除外） 都需要一個`Next`欄位，指定工作流程中的下一個狀態。 `Choice` 狀態實際上在每個選擇規則`Next`中可以有多個狀態。或者，狀態可以透過將 `End` 欄位設定為 true 來成為結束狀態。
某些狀態類型需要額外的欄位，或者可能會重新定義常見欄位的用法。
**存取工作流程的日誌資訊**
+ 建立並執行標準工作流程之後，您可以在 Step Functions 主控台中檢視執行詳細資訊頁面，以存取每個狀態、其輸入和輸出、作用中的時間長度的相關資訊。
+ 建立 和 Express Workflow 執行之後，如果啟用記錄，您可以在 Step Functions 主控台或 Amazon CloudWatch Logs 中查看執行歷史記錄。
如需有關檢視和偵錯執行的資訊，請參閱 [檢視工作流程執行](concepts-view-execution-details.md)和 [使用 CloudWatch Logs 在 Step Functions 中記錄執行歷史記錄](cw-logs.md)。
## 工作流程狀態的參考清單
狀態在 Workflow Studio 中分隔為**動作**，也稱為**任務狀態**和七個**流程狀態**。使用**任務狀態**或 Workflow Studio 中的動作，您可以呼叫第三方服務、叫用 函數，並使用數百個AWS服務端點。透過**流程狀態**，您可以指示和控制您的工作流程。所有狀態都會從先前的狀態取得輸入，許多狀態都會提供輸入篩選，並篩選/轉換傳送至工作流程中下一個狀態的輸出。
+ [任務工作流程狀態](state-task.md)：新增要由狀態機器執行的單一工作單位。
+ [選擇工作流程狀態](state-choice.md)：在工作流程的執行分支之間新增選擇。
+ [平行工作流程狀態](state-parallel.md)：將平行執行分支新增至工作流程。
+ [映射工作流程狀態](state-map.md)：動態重複輸入陣列中每個元素的步驟。與`Parallel`流程狀態不同，`Map`狀態會針對狀態輸入中陣列的多個項目執行相同的步驟。
+ [傳遞工作流程狀態](state-pass.md)：將狀態輸入傳遞至輸出。或者，篩選、轉換並將固定資料新增至輸出。
+ [等待工作流程狀態](state-wait.md)：暫停您的工作流程一段時間，或直到指定的時間或日期。
+ [工作流程狀態成功](state-succeed.md)：成功停止工作流程。
+ [失敗的工作流程狀態](state-fail.md)：因失敗而停止工作流程。
# 任務工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 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)"
},
...
}
}
}
```
# 選擇工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`Choice` 狀態 (`"Type": "Choice"`) 會將條件式邏輯新增至狀態機器。
除了大多數[常見的狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)， `Choice` 狀態還包含下列其他欄位。
**`Choices` (必要)**
[選擇規則](#state-choice-rules)陣列，該陣列可決定狀態機器接下來會轉換到哪個狀態。您必須至少定義一個`Choice`處於 狀態的規則。
`Choice` 狀態執行時，Step Functions 會評估每個**選擇規則**為 true 或 false。根據結果，Step Functions 會轉換到工作流程中的下一個狀態。
**`Default` (選用、建議)**
如果沒有**選擇規則**評估為 true，則要轉換為的狀態名稱。
**重要**
`Choice` 狀態不支援 `End` 欄位。此外，這類狀態只會在其 `Choices` 欄位內使用 `Next`。
如果工作流程執行時沒有 **Choices** 評估為 true，且未提供 **Default**，則狀態機器會因*無法從 狀態轉換而*擲回**錯誤**。
## 選擇規則 (JSONata)
`Choice` 狀態必須具有`Choices`一個欄位，其值為非空白的選擇規則陣列，其中包含使用 JSONata 時的下列欄位：
+ **`Condition` field** – 評估為 true/false 的 JSONata 表達式。
+ **`Next` 欄位** – 必須符合狀態機器中狀態名稱的值。
以下範例會檢查數值是否等於 `1`。
```
{
"Condition": "{% $foo = 1 %}",
"Next": "NumericMatchState"
}
```
下列範例會檢查`type`變數是否等於 `local`。
```
{
"Condition": "{% $type = 'local' %}",
"Next": "StringMatchState"
}
```
以下範例會檢查字串是否大於 `MyStringABC`。
```
{
"Condition": "{% $foo > 'MyStringABC' %}",
"Next": "StringGreaterMatchState"
}
```
下列範例會檢查字串是否不是 null。
```
{
"Condition" : "{% $possiblyNullValue != null and $possiblyNullValue = 42 %}",
"Next": "NotNullAnd42"
}
```
## 選擇規則 (JSONPath)
`Choice` 狀態必須具有`Choices`一個欄位，其值為選擇規則的非空白陣列，該欄位在使用 JSONPath 時包含下列欄位：
+ **比較** – 兩個欄位，指定要比較的輸入變數、比較類型，以及要比較變數的值。選擇規則支援兩個變數之間的比較。在選擇規則中，變數的值可以透過附加`Path`到支援的比較運算子名稱，與狀態輸入的另一個值進行比較。比較中 `Variable`和 路徑欄位的值必須是有效的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。
+ **`Next` 欄位** – 此欄位的值必須符合狀態機器中的狀態名稱。
以下範例會檢查數值是否等於 `1`。
```
{
"Variable": "$.foo",
"NumericEquals": 1,
"Next": "FirstMatchState"
}
```
以下範例會檢查字串是否等於 `MyString`。
```
{
"Variable": "$.foo",
"StringEquals": "MyString",
"Next": "FirstMatchState"
}
```
以下範例會檢查字串是否大於 `MyStringABC`。
```
{
"Variable": "$.foo",
"StringGreaterThan": "MyStringABC",
"Next": "FirstMatchState"
}
```
下列範例會檢查字串是否為 null。
```
{
"Variable": "$.possiblyNullValue",
"IsNull": true
}
```
下列範例顯示 StringEquals 規則只有在 `$.keyThatMightNotExist` 存在時，才會因為上述`IsPresent`選擇規則而進行評估。
```
"And": [
{
"Variable": "$.keyThatMightNotExist",
"IsPresent": true
},
{
"Variable": "$.keyThatMightNotExist",
"StringEquals": "foo"
}
]
```
下列範例會檢查具有萬用字元的模式是否相符。
```
{
"Variable": "$.foo",
"StringMatches": "log-*.txt"
}
```
以下範例會檢查時間戳記是否等於 `2001-01-01T12:00:00Z`。
```
{
"Variable": "$.foo",
"TimestampEquals": "2001-01-01T12:00:00Z",
"Next": "FirstMatchState"
}
```
下列範例會將變數與狀態輸入的另一個值進行比較。
```
{
"Variable": "$.foo",
"StringEqualsPath": "$.bar"
}
```
Step Functions 會依 `Choices` 欄位中列出的順序檢查每個選擇規則。然後轉換為第一個「選擇規則」的 `Next` 欄位中指定的狀態，在該規則中變數會根據比較運算子來比對值。
支援下列比較運算子：
+ `And`
+ `BooleanEquals`,`BooleanEqualsPath`
+ `IsBoolean`
+ `IsNull`
+ `IsNumeric`
+ `IsPresent`
+ `IsString`
+ `IsTimestamp`
+ `Not`
+ `NumericEquals`,`NumericEqualsPath`
+ `NumericGreaterThan`,`NumericGreaterThanPath`
+ `NumericGreaterThanEquals`,`NumericGreaterThanEqualsPath`
+ `NumericLessThan`,`NumericLessThanPath`
+ `NumericLessThanEquals`,`NumericLessThanEqualsPath`
+ `Or`
+ `StringEquals`,`StringEqualsPath`
+ `StringGreaterThan`,`StringGreaterThanPath`
+ `StringGreaterThanEquals`,`StringGreaterThanEqualsPath`
+ `StringLessThan`,`StringLessThanPath`
+ `StringLessThanEquals`,`StringLessThanEqualsPath`
+ `StringMatches`
+ `TimestampEquals`,`TimestampEqualsPath`
+ `TimestampGreaterThan`,`TimestampGreaterThanPath`
+ `TimestampGreaterThanEquals`,`TimestampGreaterThanEqualsPath`
+ `TimestampLessThan`,`TimestampLessThanPath`
+ `TimestampLessThanEquals`,`TimestampLessThanEqualsPath`
對於每個運算子，對應的值必須是適當的類型：字串、數字、布林值或時間戳記。Step Functions 不會嘗試將數值欄位與字串值比對。不過，由於時間戳記欄位邏輯上為字串，因此 `StringEquals` 比較子可以比對被視為時間戳記的欄位。
**注意**
基於相互操作性，請勿假設數字比較適用於 [IEEE 754-2008 `binary64` 資料類型](https://en.wikipedia.org/wiki/IEEE_754#Basic_and_interchange_formats)所代表量級或精確度以外的值。尤其是，範圍 `[-253+1, 253-1]` 之外的整數可能無法以預期的方式進行比較。
時間戳記 (例如 `2016-08-18T17:33:00Z`) 必須符合 [RFC3339 設定檔 ISO 8601](https://www.ietf.org/rfc/rfc3339.txt)，以及進一步的限制：
大寫字母 `T` 必須分開日期與時間部分。
大寫字母 `Z` 必須表示不存在數字時間時區位移。
若要了解字串比較行為，請參閱 [Java `compareTo` 文件](https://docs.oracle.com/javase/8/docs/api/java/lang/String.html#compareTo-java.lang.String-)。
`And` 和 `Or` 運算子的值必須是本身不得包含 `Next` 欄位的非空白選擇規則陣列。同樣地，`Not` 運算子的值必須是不得包含 `Next` 欄位的單一選擇規則。
您可以使用 `And`、`Not` 及 `Or`，建立複雜的巢狀選擇規則。不過，`Next` 欄位只能出現在最上層選擇規則中。
可以使用 StringMatches 比較運算子執行與具有一或多個萬用字元 (“\$1”) 模式的字串比較。使用標準 逸出萬用字元`\\ (Ex: “\\*”)`。比對期間，除了「\$1」之外，沒有任何字元具有任何特殊意義。
# 平行工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`Parallel` 狀態 (`"Type": "Parallel"`) 可用於在狀態機器中新增個別的執行分支。
除了[常見狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)以外，`Parallel` 狀態還引進下列額外欄位。
** `Branches` (必要)**
指定要以平行方式執行狀態機器的物件陣列。每個這類狀態機器物件必須具有名為 `StartAt` 和 `States` 的欄位，其意義完全如同狀態機器最上層中的欄位。
**`Parameters` （選用，僅限 JSONPath)**
用來將資訊傳遞至`Branches`陣列中定義的狀態機器。
**`Arguments` （選用，僅限 JSONata)**
用來將資訊傳遞給已連線資源的 API 動作。值可以包含 JSONata 表達式。如需詳細資訊，請參閱[在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
**`Output` （選用，僅限 JSONata)**
用來指定和轉換 狀態的輸出。指定時，該值會覆寫狀態輸出預設值。
輸出欄位接受任何 JSON 值 （物件、陣列、字串、數字、布林值、 null)。任何字串值，包括物件或陣列內的值，如果被 \$1% %\$1 字元包圍，將評估為 JSONata。
輸出也直接接受 JSONata 表達式，例如：「輸出」：「\$1% jsonata 表達式 %\$1」
如需詳細資訊，請參閱[在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
** `Assign` (選用)**
用來存放變數。`Assign` 欄位接受具有定義變數名稱及其指派值之金鑰/值對的 JSON 物件。任何字串值，包括物件或陣列內的值，都會在以`{% %}`字元包圍時評估為 JSONata
如需詳細資訊，請參閱[使用變數在狀態之間傳遞資料](workflow-variables.md)。
** `ResultPath` （選用，僅限 JSONPath)**
指定要將分支的輸出放置於何處 (在輸入中)。輸入會先依據 `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)。
`Parallel` 狀態會導致 AWS Step Functions 執行每個分支，從該分支的 `StartAt`欄位中名為 的狀態開始，並盡可能同時執行，並等到所有分支終止 （達到結束狀態） 後再處理`Parallel`狀態的 `Next` 欄位。
## Parallel 狀態範例
```
{
"Comment": "Parallel Example.",
"StartAt": "LookupCustomerInfo",
"States": {
"LookupCustomerInfo": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "LookupAddress",
"States": {
"LookupAddress": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:AddressFinder",
"End": true
}
}
},
{
"StartAt": "LookupPhone",
"States": {
"LookupPhone": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:PhoneFinder",
"End": true
}
}
}
]
}
}
}
```
在這個範例中，`LookupAddress` 和 `LookupPhone` 分支會以平行方式執行。以下是 Step Functions 主控台中視覺化工作流程的外觀。
![\[範例平行工作流程的視覺化圖形。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/parallel-state.png)
每個分支必須可獨立自主運作。一個 `Parallel` 狀態分支中的狀態不得有以該分支外部欄位為目標的 `Next` 欄位，而且分支外部的任何其他狀態也不能轉移到該分支。
## Parallel 狀態輸入和輸出處理
`Parallel` 狀態會為每個分支提供一份自有的輸入資料 (可由 `InputPath` 欄位隨時修改)。它會產生陣列形式的輸出，其中包含分支輸出的每個分支都有一個元素。所有元素不需要都是相同的類型。按照一般方式使用 `ResultPath` 欄位，即可將輸出陣列插入輸入資料中 (以及整個當作 `Parallel` 狀態的輸出傳送) (請參閱[輸入和輸出處理](concepts-input-output-filtering.md))。
```
{
"Comment": "Parallel Example.",
"StartAt": "FunWithMath",
"States": {
"FunWithMath": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "Add",
"States": {
"Add": {
"Type": "Task",
"Resource": "arn:aws:states:region:123456789012:activity:Add",
"End": true
}
}
},
{
"StartAt": "Subtract",
"States": {
"Subtract": {
"Type": "Task",
"Resource": "arn:aws:states:region:123456789012:activity:Subtract",
"End": true
}
}
}
]
}
}
}
```
如果 `FunWithMath` 狀態取得陣列 `[3, 2]` 做為輸入，則 `Add` 和 `Subtract` 狀態都會收到該陣列做為輸入。`Add` 和 `Subtract`任務的輸出會是陣列元素 3 和 2 之間的總和和和差異，也就是 `5`和 `1`，而`Parallel`狀態的輸出會是陣列。
```
[ 5, 1 ]
```
**提示**
如果您在狀態機器中使用的平行或映射狀態傳回陣列，您可以將它們轉換為具有 [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 欄位的平面陣列。如需詳細資訊，請參閱[平面化陣列陣列](input-output-inputpath-params.md#flatten-array-of-arrays-result-selector)。
## 錯誤處理
如有任何分支因為未處理的錯誤或經由轉移到 `Fail` 狀態而失敗，則整個 `Parallel` 狀態會被視為失敗，而且其所有分支都會停止。如果錯誤不是由`Parallel`狀態本身處理，Step Functions 會在發生錯誤時停止執行。
**注意**
當平行狀態失敗時，調用 Lambda 函數會繼續執行，而且處理任務字符的活動工作者不會停止。
若要停止長時間執行的活動，請使用活動訊號來偵測 Step Functions 是否已停止其分支，並停止正在處理任務的工作者。如果狀態失敗，則呼叫 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html)、[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#API_SendTaskHeartbeat_Errors)。
無法停止執行 Lambda 函數。如果您已實作備用，請使用 `Wait` 狀態，以便在 Lambda 函數完成後進行清除工作。
# 映射工作流程狀態
使用 `Map` 狀態，為資料集中的每個項目執行一組工作流程步驟。`Map` 狀態的反覆運算會平行執行，讓您可以快速處理資料集。 `Map` 狀態可以使用各種輸入類型，包括 JSON 陣列、Amazon S3 物件清單或 CSV 檔案。
Step Functions 提供兩種在工作流程中使用 `Map` 狀態的處理模式：*內嵌*模式和*分散式*模式。
**提示**
若要部署使用 `Map` 狀態的工作流程範例，請參閱* AWS Step Functions 研討會*中的[使用選擇和映射處理資料陣列](https://catalog.workshops.aws/stepfunctions/choice-and-map)。
## 映射狀態處理模式
Step Functions 會根據您希望如何處理資料集中的項目，為 `Map` 狀態提供下列處理模式。
+ **內嵌** – 有限並行模式。在此模式中，狀態的每個反覆運算都會在包含 `Map` 狀態的工作流程內容中`Map`執行。Step Functions 會將這些反覆運算的執行歷史記錄新增至父工作流程的執行歷史記錄。根據預設，`Map`狀態會以內嵌模式執行。
在此模式中， `Map` 狀態只接受 JSON 陣列做為輸入。此外，此模式支援最多 40 個並行反覆運算。
如需詳細資訊，請參閱[在 Step Functions 工作流程的內嵌模式中使用映射狀態](state-map-inline.md)。
+ **分散式**：高並行模式。在此模式中， `Map` 狀態會以子工作流程執行方式執行每個反覆運算，從而實現高達 10，000 個平行子工作流程執行的高並行。每個子工作流程執行都有自己的獨立執行歷史記錄，與父工作流程的執行歷史記錄不同。
在此模式中， `Map` 狀態可接受 JSON 陣列或 Amazon S3 資料來源作為其輸入，例如 CSV 檔案。
如需詳細資訊，請參閱[分散式模式](state-map-distributed.md)。
您應該使用的模式取決於您希望如何處理資料集中的項目。如果工作流程的執行歷史記錄不超過 25，000 個項目，或您不需要超過 40 個並行反覆運算，請在內嵌模式中使用 `Map` 狀態。
當您需要協調符合下列任一條件組合的大規模平行工作負載時，請在分散式模式中使用 `Map` 狀態：
+ 資料集的大小超過 256 KiB。
+ 工作流程的執行事件歷史記錄會超過 25，000 個項目。
+ 您需要並行超過 40 個並行反覆運算。
### 內嵌模式和分散式模式差異
下表重點介紹內嵌和分散式模式之間的差異。
| 內嵌模式 | 分散式模式 |
| --- |--- |
| **Supported data sources** |
| --- |
| 接受從工作流程中上一個步驟傳遞的 JSON 陣列做為輸入。 | 接受以下資料來源做為輸入： 從工作流程中上一個步驟傳遞的 JSON 陣列 Amazon S3 儲存貯體中包含陣列的 JSON 檔案 Amazon S3 儲存貯體中的 CSV 檔案 Amazon S3 物件清單 Amazon S3 清查 |
| **Map iterations** |
| --- |
| 在此模式中，狀態的每個反覆運算都會在包含 `Map` 狀態的工作流程內容中`Map`執行。Step Functions 會將這些反覆運算的執行歷史記錄新增至父工作流程的執行歷史記錄。 | 在此模式中， `Map` 狀態會以子工作流程執行的方式執行每個反覆運算，這可實現高達 10，000 個平行子工作流程執行的高並行。每個子工作流程執行都有自己的獨立執行歷史記錄，與父工作流程的執行歷史記錄不同。 |
| **Maximum concurrency for parallel iterations** |
| --- |
| 可讓您盡可能同時執行最多 40 個反覆運算。 | 可讓您執行最多 10，000 個平行子工作流程執行，一次處理數百萬個資料項目。 |
| **Input payload and event history sizes** |
| --- |
| 對輸入承載大小和執行事件歷史記錄中的 25，000 個項目強制執行 256 KiB 的限制。 | 可讓您克服承載大小限制，因為`Map`狀態可以直接從 Amazon S3 資料來源讀取輸入。 在此模式中，您也可以克服執行歷史記錄限制，因為狀態啟動的子工作流程執行`Map`會維護自己的執行歷史記錄與父工作流程的執行歷史記錄分開。 |
| **Monitoring and observability** |
| --- |
| 您可以從主控台或叫用 `[GetExecutionHistory](https://docs.aws.amazon.com/step-functions/latest/apireference/API_GetExecutionHistory.html)` API 動作來檢閱工作流程的執行歷史記錄。 您也可以透過 CloudWatch 和 X-Ray 檢視執行歷史記錄。 | 當您在分散式模式下執行 `Map` 狀態時，Step Functions 會建立 Map Run 資源。Map Run 是指*分散式映射狀態*啟動的一組子工作流程執行。您可以在 Step Functions 主控台中檢視 Map Run。您也可以叫用 `[DescribeMapRun](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeMapRun.html)` API 動作。Map Run 也會向 CloudWatch 發出指標。 如需詳細資訊，請參閱[在 Step Functions 中檢視分散式映射執行](concepts-examine-map-run.md)。 |
# 在 Step Functions 工作流程的內嵌模式中使用映射狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
根據預設， `Map` 狀態會以**內嵌**模式執行。在內嵌模式中，映射狀態僅接受 JSON 陣列做為輸入。它會從工作流程中的上一個步驟接收此陣列。在此模式中，狀態的每個反覆運算都會在包含 `Map` 狀態的工作流程內容中`Map`執行。Step Functions 會將這些反覆運算的執行歷史記錄新增至父工作流程的執行歷史記錄。
在此模式中， `Map` 狀態最多支援 40 個並行反覆運算。
設定為**內嵌**`Map`的狀態稱為*內嵌映射狀態*。如果工作流程的執行歷史記錄不超過 25，000 個項目，或者您不需要超過 40 個並行反覆運算，請在內嵌模式中使用 `Map` 狀態。
如需使用*內嵌地圖狀態*的簡介，請參閱教學課程 [使用內嵌映射重複動作](tutorial-map-inline.md)。
**Topics**
+ [本主題中的關鍵概念](#key-concepts-inline-map)
+ [內嵌映射狀態欄位](#map-state-inline-additional-fields)
+ [已棄用的欄位](#map-state-inline-deprecated-fields)
+ [內嵌映射狀態範例 (JSONPath)](#inline-map-state-examples)
+ [使用 的內嵌映射狀態範例 `ItemSelector`](#inline-map-state-example-params)
+ [內嵌`Map`狀態輸入和輸出處理](#inline-map-state-output)
## 本主題中的關鍵概念
**內嵌模式**
`Map` 狀態的有限並行模式。在此模式中，狀態的每個反覆運算都會在包含 `Map` 狀態的工作流程內容中`Map`執行。Step Functions 會將這些反覆運算的執行歷史記錄新增至父工作流程的執行歷史記錄。 `Map` 狀態預設會在內嵌模式中執行。
此模式僅接受 JSON 陣列做為輸入，並支援最多 40 個並行反覆運算。
**內嵌映射狀態**
`Map` 狀態設定為**內嵌**模式。
**映射工作流程**
狀態針對每次反覆`Map`執行的一組步驟。
**映射狀態反覆運算**
在 `Map` 狀態內定義的工作流程重複。
## 內嵌映射狀態欄位
若要在工作流程中使用*內嵌映射狀態*，請指定一個或多個這些欄位。除了[常見狀態欄位之外，您還可以指定這些欄位](statemachine-structure.md#amazon-states-language-common-fields)。
**`Type` (必要)**
設定狀態類型，例如 `Map`。
**`ItemProcessor` (必要)**
包含下列指定`Map`狀態處理模式和定義的 JSON 物件。
定義包含處理每個陣列項目時要重複的一組步驟。
+ `ProcessorConfig` – 選用的 JSON 物件，指定 `Map` 狀態的處理模式。此物件包含 `Mode`子欄位。此欄位預設為 `INLINE`，這會在內嵌模式中使用 `Map` 狀態。
在此模式中，任何反覆運算的失敗都會導致`Map`狀態失敗。當`Map`狀態失敗時，所有反覆運算都會停止。
+ `StartAt` – 指定字串，指出工作流程中的第一個狀態。此字串區分大小寫，且必須符合其中一個狀態物件的名稱。此狀態會先針對資料集中的每個項目執行。您提供給 `Map` 狀態的任何執行輸入會先傳遞至 `StartAt` 狀態。
+ `States` – 包含逗號分隔狀態集的 JSON 物件[探索要在 Step Functions 中使用的工作流程狀態](workflow-states.md)。在此物件中，您可以定義 [Map workflow](#mapwflow)。
**注意**
`ItemProcessor` 欄位內的狀態只能彼此轉換。`ItemProcessor` 欄位外部的任何狀態都無法轉換為其中的狀態。
`ItemProcessor` 欄位會取代現在已棄用`Iterator`的欄位。雖然您可以繼續包含使用 `Iterator` 欄位`Map`的狀態，但強烈建議您使用 取代此欄位`ItemProcessor`。
[Step Functions Local](sfn-local.md) 目前不支援 `ItemProcessor` 欄位。建議您將 `Iterator` 欄位與 Step Functions Local 搭配使用。
**`Items` （選用，僅限 JSONata)**
必須評估為陣列的 JSON 陣列或 JSONata 表達式。
**`ItemsPath` （選用，僅限 JSONPath)**
使用 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法指定[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。此路徑會選取 JSON 節點，其中包含狀態輸入內的項目陣列。如需詳細資訊，請參閱[ItemsPath （地圖，僅限 JSONPath)](input-output-itemspath.md)。
**`ItemSelector` (選用)**
覆寫輸入陣列項目的值，然後再傳遞給每個`Map`狀態反覆運算。
在此欄位中，您可以指定有效的 JSON，其中包含鍵值對的集合。這些配對可以包含下列任何項目：
+ 您在狀態機器定義中定義的靜態值。
+ 使用[路徑](amazon-states-language-paths.md)從狀態輸入中選取的值。
+ 從[內容物件](input-output-contextobject.md)存取的值。
如需詳細資訊，請參閱[ItemSelector （地圖）](input-output-itemselector.md)。
`ItemSelector` 欄位會取代現在已棄用`Parameters`的欄位。雖然您可以繼續包含使用 `Parameters` 欄位`Map`的狀態，但強烈建議您使用 取代此欄位`ItemSelector`。
**`MaxConcurrency` (選用)**
指定整數值，在可平行執行`Map`的狀態反覆運算數量上提供上限。例如，`MaxConcurrency`值 10 會將`Map`狀態限制為一次執行 10 個並行反覆運算。
在 JSONata 狀態下，您可以指定評估為整數的 JSONata 表達式。
並行反覆運算可能會受到限制。發生這種情況時，某些反覆運算不會開始，直到先前的反覆運算完成為止。當您的輸入陣列有超過 40 個項目時，發生這種情況的可能性會增加。
若要實現更高的並行，請考慮 [分散式模式](state-map-distributed.md)。
預設值為 `0`，不限制並行。Step Functions 會盡可能同時叫用反覆運算。
`MaxConcurrency` 的值會為每個陣列元素`1`叫用`ItemProcessor`一次 。陣列中的項目會依其在輸入中的顯示順序進行處理。Step Functions 在完成先前的反覆運算之前，不會啟動新的反覆運算。
**`MaxConcurrencyPath` （選用，僅限 JSONPath)**
如果您想要使用參考路徑從狀態輸入動態提供最大並行值，請使用 `MaxConcurrencyPath`。解析後，參考路徑必須選取值為非負整數的欄位。
`Map` 狀態不能同時包含 `MaxConcurrency`和 `MaxConcurrencyPath`。
**`ResultPath` （選用，僅限 JSONPath)**
指定在輸入中存放`Map`狀態反覆運算輸出的位置。然後，映射狀態會篩選[`OutputPath`](input-output-example.md#input-output-outputpath)欄位指定的輸入，如果指定的話。然後，它會使用篩選的輸入做為狀態的輸出。如需詳細資訊，請參閱[輸入和輸出處理](concepts-input-output-filtering.md)。
**`ResultSelector` （選用，僅限 JSONPath)**
傳遞金鑰值對的集合，其中值為靜態或從結果中選取。如需詳細資訊，請參閱[ResultSelector](input-output-inputpath-params.md#input-output-resultselector)。
如果您在狀態機器中使用的平行或映射狀態傳回陣列，您可以將它們轉換為具有 [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 欄位的平面陣列。如需詳細資訊，請參閱[平面化陣列陣列](input-output-inputpath-params.md#flatten-array-of-arrays-result-selector)。
**`Retry` (選用)**
稱為 Retriers 的物件陣列，可定義重試政策。狀態會在遇到執行時間錯誤時使用重試政策。如需詳細資訊，請參閱[使用重試和擷取的狀態機器範例](concepts-error-handling.md#error-handling-examples)。
如果您為*內嵌映射狀態*定義重試器，則重試政策會套用至所有`Map`狀態反覆運算，而不只是失敗的反覆運算。例如，您的`Map`狀態包含兩個成功的反覆運算和一個失敗的反覆運算。如果您已定義`Map`狀態`Retry`的欄位，則重試政策會套用至所有三個`Map`狀態反覆運算，而不只是失敗的反覆運算。
**`Catch` (選用)**
稱為 Catcher 的物件陣列，可定義後援狀態。如果狀態遇到執行時間錯誤，並且沒有重試政策，或者其重試政策已用盡，則會執行擷取器。如需詳細資訊，請參閱[備用狀態](concepts-error-handling.md#error-handling-fallback-states)。
**`Output` （選用，僅限 JSONata)**
用來指定和轉換 狀態的輸出。指定時，值會覆寫狀態輸出預設值。
輸出欄位接受任何 JSON 值 （物件、陣列、字串、數字、布林值、 null)。任何字串值，包括物件或陣列內的值，如果被 \$1% %\$1 個字元包圍，將評估為 JSONata。
輸出也直接接受 JSONata 表達式，例如：「輸出」：「\$1% jsonata 表達式 %\$1」
如需詳細資訊，請參閱[在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
** `Assign` (選用)**
用來存放變數。`Assign` 欄位接受具有定義變數名稱及其指派值之金鑰/值對的 JSON 物件。任何字串值，包括物件或陣列內的值，都會在以`{% %}`字元包圍時評估為 JSONata
如需詳細資訊，請參閱[使用變數在狀態之間傳遞資料](workflow-variables.md)。
## 已棄用的欄位
**注意**
雖然您可以繼續包含使用下列欄位`Map`的狀態，但強烈建議您將 `Iterator` 取代為 `ItemProcessor`，並將 取代`Parameters`為 `ItemSelector`。
** `Iterator`**
指定 JSON 物件，定義一組處理陣列中每個元素的步驟。
**`Parameters`**
指定索引鍵/值對的集合，其中的值可以包含下列任何項目：
+ 您在狀態機器定義中定義的靜態值。
+ 使用[路徑](amazon-states-language-paths.md)從輸入中選取的值。
## 內嵌映射狀態範例 (JSONPath)
請考慮下列在**內嵌**模式下執行之`Map`狀態的輸入資料。
```
{
"ship-date": "2016-03-14T01:59:00Z",
"detail": {
"delivery-partner": "UQS",
"shipped": [
{ "prod": "R31", "dest-code": 9511, "quantity": 1344 },
{ "prod": "S39", "dest-code": 9511, "quantity": 40 },
{ "prod": "R31", "dest-code": 9833, "quantity": 12 },
{ "prod": "R40", "dest-code": 9860, "quantity": 887 },
{ "prod": "R40", "dest-code": 9511, "quantity": 1220 }
]
}
}
```
根據先前的輸入，下列範例中`Map`的狀態會針對 `shipped` 欄位中陣列的每個項目叫用名為 `ship-val` 一次的 AWS Lambda 函數。
```
"Validate All": {
"Type": "Map",
"InputPath": "$.detail",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "Validate",
"States": {
"Validate": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"OutputPath": "$.Payload",
"Parameters": {
"FunctionName": "arn:aws:lambda:us-east-2:account-id:function:ship-val:$LATEST"
},
"End": true
}
}
},
"End": true,
"ResultPath": "$.detail.shipped",
"ItemsPath": "$.shipped"
}
```
狀態的每個反覆運算都會`Map`傳送陣列中的項目，並以 [`ItemsPath`](input-output-itemspath.md) 欄位選取，做為 `ship-val` Lambda 函數的輸入。下列值是`Map`狀態傳送至 Lambda 函數呼叫的輸入範例：
```
{
"prod": "R31",
"dest-code": 9511,
"quantity": 1344
}
```
完成時，`Map` 狀態的輸出為 JSON 陣列，其中每個項目都是反覆運算的輸出。在此情況下，此陣列包含 `ship-val` Lambda 函數的輸出。
## 使用 的內嵌映射狀態範例 `ItemSelector`
假設上一個範例中的 `ship-val` Lambda 函數也需要有關貨物貨運業者的資訊。此資訊是每次反覆運算陣列中項目的補充。您可以包含來自輸入的資訊，以及`Map`狀態目前反覆運算的特定資訊。請注意下列範例中的 `ItemSelector` 欄位：
```
"Validate-All": {
"Type": "Map",
"InputPath": "$.detail",
"ItemsPath": "$.shipped",
"MaxConcurrency": 0,
"ResultPath": "$.detail.shipped",
"ItemSelector": {
"parcel.$": "$$.Map.Item.Value",
"courier.$": "$.delivery-partner"
},
"ItemProcessor": {
"StartAt": "Validate",
"States": {
"Validate": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:ship-val",
"End": true
}
}
},
"End": true
}
```
`ItemSelector` 區塊會以 JSON 節點取代反覆運算的輸入。此節點同時包含[內容物件](input-output-contextobject.md#contextobject-map)的目前項目資料，以及`Map`狀態輸入`delivery-partner`欄位的貨運業者資訊。以下是單一反覆運算的輸入範例。`Map` 狀態會將此輸入傳遞給 `ship-val` Lambda 函數的呼叫。
```
{
"parcel": {
"prod": "R31",
"dest-code": 9511,
"quantity": 1344
},
"courier": "UQS"
}
```
在先前的*內嵌映射狀態*範例中， `ResultPath` 欄位會以與輸入相同的格式產生輸出。不過，它會使用陣列覆寫 `detail.shipped` 欄位，其中每個元素都是每個反覆 `ship-val` Lambda 調用的輸出。
如需使用*內嵌映射狀態*及其欄位的詳細資訊，請參閱以下內容。
+ [使用內嵌映射重複動作](tutorial-map-inline.md)
+ [在 Step Functions 中處理輸入和輸出](concepts-input-output-filtering.md)
+ [ItemsPath （地圖，僅限 JSONPath)](input-output-itemspath.md)
+ [Map 狀態的內容物件資料](input-output-contextobject.md#contextobject-map)
## 內嵌`Map`狀態輸入和輸出處理
對於指定`Map`狀態， 會[`InputPath`](input-output-inputpath-params.md#input-output-inputpath)選取狀態輸入的子集。
`Map` 狀態的輸入必須包含 JSON 陣列。`Map` 狀態會針對陣列中的每個項目執行 `ItemProcessor`區段一次。如果您指定 [`ItemsPath`](input-output-itemspath.md) 欄位，`Map`狀態會選取輸入中要反覆運算的陣列位置。如果未指定，則 `ItemsPath` 的值為 `$`，而 `ItemProcessor` 區段預期陣列是唯一的輸入。如果您指定 `ItemsPath` 欄位，其值必須是[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。`Map` 狀態會在套用 之後，將此路徑套用至有效輸入`InputPath`。必須`ItemsPath`識別其值為 JSON 陣列的欄位。
根據預設，每次反覆運算的輸入都是 `ItemsPath`值所識別陣列欄位的單一元素。您可以使用 `ItemSelector （地圖）` 欄位覆寫此值。
完成時，`Map` 狀態的輸出為 JSON 陣列，其中每個項目都是反覆運算的輸出。
如需內嵌映射狀態輸入和輸出的詳細資訊，請參閱下列內容：
+ [使用內嵌映射重複動作](tutorial-map-inline.md)
+ [使用 的內嵌映射狀態範例 `ItemSelector`](#inline-map-state-example-params)
+ [在 Step Functions 中處理輸入和輸出](concepts-input-output-filtering.md)
+ [Map 狀態的內容物件資料](input-output-contextobject.md#contextobject-map)
+ [在 Step Functions 中處理來自具有映射狀態之佇列的資料](sample-map-state.md)
# 針對 Step Functions 中的大規模平行工作負載，在分散式模式中使用映射狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
使用 Step Functions，您可以協調大規模平行工作負載來執行任務，例如半結構化資料的隨需處理。這些平行工作負載可讓您同時處理存放在 Amazon S3 中的大規模資料來源。例如，您可以處理包含大量資料的單一 JSON 或 CSV 檔案。或者，您可以處理大量 Amazon S3 物件。
若要在工作流程中設定大規模平行工作負載，請在分散式模式中包含 `Map` 狀態。*映射狀態*會同時處理資料集中的項目。設定為**分散式**`Map`的狀態稱為*分散式映射狀態*。在*分散式模式中*， `Map` 狀態允許高並行處理。在分散式模式中， `Map` 狀態會在稱為*子工作流程執行的*反覆運算中處理資料集中的項目。您可以指定可平行執行的子工作流程執行數目。每個子工作流程執行都有自己的獨立執行歷史記錄，與父工作流程的執行歷史記錄不同。如果您未指定，Step Functions 會平行執行 10，000 個平行子工作流程執行。
下圖說明如何在工作流程中設定大規模平行工作負載。
![\[圖表說明協調大規模平行工作負載的概念。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/autobahn-concept.png)
**在研討會中學習**
了解 Step Functions 和 Lambda 等無伺服器技術如何簡化管理和擴展、卸載未區分的任務，以及解決大規模分散式資料處理的挑戰。在此過程中，您將使用分散式映射進行高並行處理。研討會也提供最佳化工作流程的最佳實務，以及用於宣告處理、漏洞掃描和 Monte Carlo 模擬的實際使用案例。
**研討會：[使用 Step Functions 進行大規模資料處理](https://catalog.workshops.aws/serverless-data-processing)**
**Topics**
+ [重要用語](#dist-map-orchestrate-parallel-workloads-key-terms)
+ [分散式映射狀態定義](#use-map-state-dist-mode)
+ [執行分散式映射的許可](#dist-map-permissions)
+ [分散式映射狀態欄位](#map-state-distributed-additional-fields)
+ [分散式映射失敗閾值](#maprun-fail-threshold)
+ [進一步了解分散式地圖](#dist-map-next-steps)
## 重要用語
**分散式模式**
Map [狀態](state-map.md)的處理模式。在此模式中，狀態的每個反覆運算`Map`都會執行為啟用高並行的子工作流程執行。每個子工作流程執行都有自己的執行歷史記錄，與父工作流程的執行歷史記錄分開。此模式支援從大規模 Amazon S3 資料來源讀取輸入。
**分散式映射狀態**
映射狀態設定為**分散式**[處理模式](state-map.md#concepts-map-process-modes)。
**映射工作流程**
`Map` 狀態執行的一組步驟。
**父工作流程**
包含一或多個分散式映射狀態的工作流程。
**子工作流程執行**
*分散式地圖狀態*的反覆運算。子工作流程執行有自己的執行歷史記錄，與父工作流程的執行歷史記錄分開。
**映射執行**
當您在分散式模式下執行 `Map` 狀態時，Step Functions 會建立 Map Run 資源。Map Run 是指*分散式映射狀態*啟動的一組子工作流程執行，以及控制這些執行的執行時間設定。Step Functions 會將 Amazon Resource Name (ARN) 指派給您的 Map Run。您可以在 Step Functions 主控台中檢查 Map Run。您也可以叫用 `[DescribeMapRun](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeMapRun.html)` API 動作。
Map Run 的子工作流程執行會向 發出指標 CloudWatch；。這些指標會有以下格式的已標記狀態機器 ARN：
`arn:partition:states:region:account:stateMachine:stateMachineName/MapRunLabel or UUID`
如需詳細資訊，請參閱[檢視地圖執行](concepts-examine-map-run.md)。
## 分散式映射狀態定義範例 (JSONPath)
當您需要協調符合下列任一條件組合的大規模平行工作負載時，請在分散式模式中使用 `Map` 狀態：
+ 資料集的大小超過 256 KiB。
+ 工作流程的執行事件歷史記錄會超過 25，000 個項目。
+ 您需要並行超過 40 個並行反覆運算。
下列*分散式映射狀態*定義範例會將資料集指定為存放在 Amazon S3 儲存貯體中的 CSV 檔案。它還指定了一個 Lambda 函數，用於處理 CSV 檔案的每一列中的資料。由於此範例使用 CSV 檔案，因此也會指定 CSV 資料欄標頭的位置。若要檢視此範例的完整狀態機器定義，請參閱教學課程 [使用分散式地圖複製大規模 CSV 資料](tutorial-map-distributed.md)。
```
{
"Map": {
"Type": "Map",
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csv-dataset/ratings.csv"
}
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "EXPRESS"
},
"StartAt": "LambdaTask",
"States": {
"LambdaTask": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"OutputPath": "$.Payload",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:account-id:function:processCSVData"
},
"End": true
}
}
},
"Label": "Map",
"End": true,
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
}
```
## 執行分散式映射的許可
當您在工作流程中包含*分散式地圖狀態*時，Step Functions 需要適當的許可，以允許狀態機器角色叫用*分散式地圖狀態*的 `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API 動作。
下列 IAM 政策範例會將執行*分散式映射狀態*所需的最低權限授予狀態機器角色。
**注意**
請務必將 `stateMachineName`取代為您使用*分散式地圖*狀態的狀態機器名稱。例如 `arn:aws:states:region:account-id:stateMachine:mystateMachine`。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"states:StartExecution"
],
"Resource": [
"arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachineName"
]
},
{
"Effect": "Allow",
"Action": [
"states:DescribeExecution"
],
"Resource": "arn:aws:states:us-east-1:123456789012:execution:myStateMachineName:*"
}
]
}
```
此外，您必須確定擁有存取*分散式地圖狀態*中使用的 AWS 資源所需的最低權限，例如 Amazon S3 儲存貯體。如需相關資訊，請參閱[使用分散式地圖狀態的 IAM 政策](iam-policies-eg-dist-map.md)。
## 分散式映射狀態欄位
若要在工作流程中使用*分散式映射狀態*，請指定一個或多個這些欄位。除了[常見狀態欄位之外，您還可以指定這些欄位](statemachine-structure.md#amazon-states-language-common-fields)。
**`Type` (必要)**
設定狀態類型，例如 `Map`。
**`ItemProcessor` (必要)**
包含下列指定`Map`狀態處理模式和定義的 JSON 物件。
+ `ProcessorConfig` – 指定處理項目模式的 JSON 物件，具有下列子欄位：
+ `Mode` – 設定為 **DISTRIBUTED** 以在分散式模式中使用 `Map` 狀態。
**警告**
標準工作流程支援分散式模式，但 Express 工作流程不支援。
+ `ExecutionType` – 指定映射工作流程的執行類型為 **STANDARD** 或 **EXPRESS**。如果您`DISTRIBUTED`為`Mode`子欄位指定 ，則必須提供此欄位。如需工作流程類型的詳細資訊，請參閱 [在 Step Functions 中選擇工作流程類型](choosing-workflow-type.md)。
+ `StartAt` – 指定字串，指出工作流程中的第一個狀態。此字串區分大小寫，且必須符合其中一個狀態物件的名稱。此狀態會先針對資料集中的每個項目執行。您提供給 `Map` 狀態的任何執行輸入會先傳遞至 `StartAt` 狀態。
+ `States` – 包含逗號分隔狀態集的 JSON 物件[探索要在 Step Functions 中使用的工作流程狀態](workflow-states.md)。在此物件中，您可以定義 [Map workflow](state-map-inline.md#mapwflow)。
**`ItemReader`**
指定資料集及其位置。`Map` 狀態會從指定的資料集接收其輸入資料。
在分散式模式中，您可以使用從先前狀態傳遞的 JSON 承載，或是使用大型 Amazon S3 資料來源做為資料集。如需詳細資訊，請參閱[ItemReader （地圖）](input-output-itemreader.md)。
**`Items` （選用，僅限 JSONata)**
JSON 陣列、JSON 物件或必須評估為陣列或物件的 JSONata 表達式。
**`ItemsPath` （選用，僅限 JSONPath)**
使用 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法指定[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，以選取包含項目陣列的 JSON 節點，或狀態輸入內具有鍵值對的物件。
在分散式模式中，只有當您使用上一個步驟的 JSON 陣列或物件做為狀態輸入時，才指定此欄位。如需詳細資訊，請參閱[ItemsPath （地圖，僅限 JSONPath)](input-output-itemspath.md)。
**`ItemSelector` （選用，僅限 JSONPath)**
覆寫個別資料集項目的值，然後再傳遞至每個`Map`狀態反覆運算。
在此欄位中，您可以指定有效的 JSON 輸入，其中包含鍵/值對的集合。這些對可以是您在狀態機器定義中定義的靜態值、使用[路徑](amazon-states-language-paths.md)從狀態輸入中選取的值，或從[內容物件](input-output-contextobject.md)存取的值。如需詳細資訊，請參閱[ItemSelector （地圖）](input-output-itemselector.md)。
**`ItemBatcher` (選用)**
指定 批次處理資料集項目。然後，每個子工作流程執行都會收到這些項目的批次做為輸入。如需詳細資訊，請參閱[ItemBatcher （地圖）](input-output-itembatcher.md)。
**`MaxConcurrency` (選用)**
指定可平行執行的子工作流程執行數目。解譯器最多只允許指定數量的平行子工作流程執行。如果您未指定並行值或將其設定為零，Step Functions 不會限制並行並執行 10，000 個平行子工作流程執行。在 JSONata 狀態下，您可以指定評估為整數的 JSONata 表達式。
雖然您可以為平行子工作流程執行指定更高的並行限制，但我們建議您不要超過下游 AWS 服務的容量，例如 AWS Lambda。
**`MaxConcurrencyPath` （選用，僅限 JSONPath)**
如果您想要使用參考路徑從狀態輸入動態提供最大並行值，請使用 `MaxConcurrencyPath`。解析後，參考路徑必須選取值為非負整數的欄位。
`Map` 狀態不能同時包含 `MaxConcurrency`和 `MaxConcurrencyPath`。
**`ToleratedFailurePercentage` (選用)**
定義映射執行中要容忍的失敗項目百分比。如果 Map Run 超過此百分比，則會自動失敗。Step Functions 計算失敗項目的百分比，是失敗或逾時項目總數除以項目總數的結果。您必須指定介於零到 100 之間的值。如需詳細資訊，請參閱[在 Step Functions 中設定分散式映射狀態的失敗閾值](#maprun-fail-threshold)。
在 JSONata 狀態下，您可以指定評估為整數的 JSONata 表達式。
**`ToleratedFailurePercentagePath` （選用，僅限 JSONPath)**
如果您想要使用參考路徑從狀態輸入動態提供可容忍的失敗百分比值，請使用 `ToleratedFailurePercentagePath`。解析後，參考路徑必須選取值介於零和 100 之間的欄位。
**`ToleratedFailureCount` (選用)**
定義映射執行中要容忍的失敗項目數量。如果 Map Run 超過此數字，則會自動失敗。如需詳細資訊，請參閱[在 Step Functions 中設定分散式映射狀態的失敗閾值](#maprun-fail-threshold)。
在 JSONata 狀態下，您可以指定評估為整數的 JSONata 表達式。
**`ToleratedFailureCountPath` （選用，僅限 JSONPath)**
如果您想要使用參考路徑從狀態輸入動態提供容錯計數值，請使用 `ToleratedFailureCountPath`。解析後，參考路徑必須選取值為非負整數的欄位。
**`Label` (選用)**
唯一識別`Map`狀態的字串。對於每個 Map Run，Step Functions 會將標籤新增至 Map Run ARN。以下是具有名為 之自訂標籤的 Map Run ARN 範例`demoLabel`：
```
arn:aws:states:region:account-id:mapRun:demoWorkflow/demoLabel:3c39a231-69bb-3d89-8607-9e124eddbb0b
```
如果您未指定標籤，Step Functions 會自動產生唯一的標籤。
標籤長度不能超過 40 個字元，在狀態機器定義中必須是唯一的，且不能包含以下任何字元：
+ 空格
+ 萬用字元 (`? *`)
+ 括號字元 (`< > { } [ ]`)
+ 特殊字元 (`: ; , \ | ^ ~ $ # % & ` "`)
+ 控制字元 (`\\u0000` - `\\u001f`或 `\\u007f` - `\\u009f`)。
Step Functions 接受包含非 ASCII 字元的狀態機器、執行、活動和標籤名稱。由於這類字元會阻止 Amazon CloudWatch 記錄資料，我們建議您僅使用 ASCII 字元，以便您可以追蹤 Step Functions 指標。
**`ResultWriter` (選用)**
指定 Step Functions 寫入所有子工作流程執行結果的 Amazon S3 位置。
Step Functions 會合併所有子工作流程執行資料，例如執行輸入和輸出、ARN 和執行狀態。然後，它會將狀態相同的執行匯出至指定 Amazon S3 位置中的個別檔案。如需詳細資訊，請參閱[ResultWriter （地圖）](input-output-resultwriter.md)。
如果您不匯出`Map`狀態結果，它會傳回所有子工作流程執行結果的陣列。例如：
```
[1, 2, 3, 4, 5]
```
**`ResultPath` （選用，僅限 JSONPath)**
指定輸入中要放置反覆運算輸出的位置。輸入接著會依 [`OutputPath`](input-output-example.md#input-output-outputpath) 欄位指定的內容進行篩選，再做為狀態的輸出傳遞。如需詳細資訊，請參閱[輸入和輸出處理](concepts-input-output-filtering.md)。
**`ResultSelector` (選用)**
傳遞金鑰值對的集合，其中的值為靜態或從結果中選取。如需詳細資訊，請參閱[ResultSelector](input-output-inputpath-params.md#input-output-resultselector)。
如果您在狀態機器中使用的平行或映射狀態傳回陣列，您可以將它們轉換為具有 [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 欄位的平面陣列。如需詳細資訊，請參閱[平面化陣列陣列](input-output-inputpath-params.md#flatten-array-of-arrays-result-selector)。
**`Retry` (選用)**
稱為 Retriers 的物件陣列，可定義重試政策。如果狀態遇到執行時間錯誤，則執行會使用重試政策。如需詳細資訊，請參閱[使用重試和擷取的狀態機器範例](concepts-error-handling.md#error-handling-examples)。
如果您為*分散式地圖狀態*定義重試器，則重試政策會套用至所有啟動`Map`狀態的子工作流程執行。例如，假設您的`Map`狀態開始了三個子工作流程執行，其中一個工作流程執行失敗。當失敗發生時，如果已定義，則執行會使用 `Retry` 欄位做為`Map`狀態。重試政策適用於所有子工作流程執行，而不只是失敗的執行。如果一或多個子工作流程執行失敗，則 Map Run 失敗。
當您重試`Map`狀態時，它會建立新的 Map Run。
**`Catch` (選用)**
稱為 Catcher 的物件陣列，可定義後援狀態。`Catch` 如果狀態遇到執行時間錯誤，Step Functions 會使用 中定義的 Catchers。發生錯誤時，執行會先使用 中定義的任何重試器`Retry`。如果未定義或耗盡重試政策，則如果已定義，則執行會使用其 Catchers。如需詳細資訊，請參閱[備用狀態](concepts-error-handling.md#error-handling-fallback-states)。
**`Output` （選用，僅限 JSONata)**
用來指定和轉換 狀態的輸出。指定時，值會覆寫狀態輸出預設值。
輸出欄位接受任何 JSON 值 （物件、陣列、字串、數字、布林值、 null)。任何字串值，包括物件或陣列內的值，如果被 \$1% %\$1 個字元包圍，將評估為 JSONata。
輸出也直接接受 JSONata 表達式，例如：「輸出」：「\$1% jsonata 表達式 %\$1」
如需詳細資訊，請參閱[在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
** `Assign` (選用)**
用來存放變數。`Assign` 欄位接受具有定義變數名稱及其指派值之金鑰/值對的 JSON 物件。任何字串值，包括物件或陣列內的值，都會在以`{% %}`字元包圍時評估為 JSONata
如需詳細資訊，請參閱[使用變數在狀態之間傳遞資料](workflow-variables.md)。
## 在 Step Functions 中設定分散式映射狀態的失敗閾值
當您協調大規模平行工作負載時，您也可以定義可容忍的故障閾值。此值可讓您將失敗項目的數量上限或百分比指定為 [Map Run](concepts-examine-map-run.md) 的失敗閾值。根據您指定的值，如果 Map Run 超過閾值，則會自動失敗。如果您同時指定這兩個值，當工作流程超出任一個值時，就會失敗。
指定閾值有助於您在整個 Map Run 失敗之前，使特定數量的項目失敗。Step Functions 會在 Map Run 失敗時傳回`States.ExceedToleratedFailureThreshold`錯誤，因為超過指定的閾值。
**注意**
Step Functions 可以在 Map Run 中繼續執行子工作流程，即使超過可容忍的失敗閾值，但在 Map Run 失敗之前。
若要在 Workflow Studio 中指定閾值，請在**執行時間設定**欄位下**的其他組態**中選取**設定容錯閾值**。
**容錯失敗百分比**
定義要容忍的失敗項目百分比。如果超過此值，您的 Map Run 失敗。Step Functions 計算失敗項目的百分比，是失敗或逾時項目總數除以項目總數的結果。您必須指定介於零到 100 之間的值。預設百分比值為零，這表示如果其任何一個子工作流程執行失敗或逾時，工作流程就會失敗。如果您將百分比指定為 100，即使所有子工作流程執行都失敗，工作流程也不會失敗。
或者，您可以指定百分比做為*分散式映射狀態*輸入中現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。此路徑必須在執行時間解析為介於 0 到 100 之間的正整數。您可以在 `ToleratedFailurePercentagePath`子欄位中指定參考路徑。
例如，假設有下列輸入：
```
{
"percentage": 15
}
```
您可以使用該輸入的參考路徑指定百分比，如下所示：
```
{
...
"Map": {
"Type": "Map",
...
"ToleratedFailurePercentagePath": "$.percentage"
...
}
}
```
您可以在*分散式映射狀態*定義中指定 `ToleratedFailurePercentage`或 `ToleratedFailurePercentagePath`，但不能同時指定兩者。
**容錯失敗計數**
定義要容忍的失敗項目數量。如果超過此值，您的 Map Run 失敗。
或者，您可以指定計數做為*分散式映射狀態*輸入中現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。此路徑必須在執行時間解析為正整數。您可以在 `ToleratedFailureCountPath`子欄位中指定參考路徑。
例如，假設有下列輸入：
```
{
"count": 10
}
```
您可以使用該輸入的參考路徑指定數字，如下所示：
```
{
...
"Map": {
"Type": "Map",
...
"ToleratedFailureCountPath": "$.count"
...
}
}
```
您可以在*分散式映射狀態*定義中指定 `ToleratedFailureCount`或 `ToleratedFailureCountPath`，但不能同時指定兩者。
## 進一步了解分散式地圖
若要繼續進一步了解*分散式地圖狀態*，請參閱下列資源：
+
**輸入和輸出處理**
若要設定*分散式映射狀態*接收的輸入及其產生的輸出，Step Functions 會提供下列欄位：
+ [ItemReader （地圖）](input-output-itemreader.md)
+ [ItemsPath （地圖，僅限 JSONPath)](input-output-itemspath.md)
+ [ItemSelector （地圖）](input-output-itemselector.md)
+ [ItemBatcher （地圖）](input-output-itembatcher.md)
+ [ResultWriter （地圖）](input-output-resultwriter.md)
+ [Step Functions 如何剖析輸入 CSV 檔案](example-csv-parse-dist-map.md)
除了這些欄位之外，Step Functions 也可讓您定義分散式映射的可容忍失敗閾值。此值可讓您將失敗項目的數量上限或百分比指定為 [Map Run](concepts-examine-map-run.md) 的失敗閾值。如需設定可容忍失敗閾值的詳細資訊，請參閱 [在 Step Functions 中設定分散式映射狀態的失敗閾值](#maprun-fail-threshold)。
+
**使用分散式映射狀態**
請參閱下列教學課程和範例專案，以開始使用*分散式地圖狀態*。
+ [使用分散式地圖複製大規模 CSV](tutorial-map-distributed.md)
+ [在 Step Functions 中使用 Lambda 函數處理批次資料](tutorial-itembatcher-param-task.md)
+ [在 Step Functions 中使用 Lambda 函數處理個別項目](tutorial-itembatcher-single-item-process.md)
+ [範例專案：使用分散式映射處理 CSV 檔案](sample-dist-map-csv-process.md)
+ [範例專案：使用分散式映射處理 Amazon S3 儲存貯體中的資料](sample-dist-map-s3data-process.md)
+
**檢查分散式映射狀態執行**
Step Functions 主控台提供*映射執行詳細資訊*頁面，其中會顯示*與分散式映射狀態*執行相關的所有資訊。如需如何檢查此頁面上顯示的資訊，請參閱 [檢視地圖執行](concepts-examine-map-run.md)。
# 傳遞工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`Pass` 狀態 (`"Type": "Pass"`) 會將其輸入傳遞到其輸出，而不執行任何工作。在建構及偵錯狀態機器時，`Pass` 狀態非常實用。
您也可以使用 `Pass` 狀態來使用篩選條件轉換 JSON 狀態輸入，然後將轉換的資料傳遞至工作流程中的下一個狀態。如需輸入轉換的相關資訊，請參閱 [在 Step Functions 工作流程中操作參數](input-output-inputpath-params.md)。
除了[常見狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)以外，`Pass` 狀態還允許使用下列欄位。
** `Assign` （選用，僅限 JSONata)**
將資料指派給變數的鍵值對集合。如需詳細資訊，請參閱[使用變數在狀態之間傳遞資料](workflow-variables.md)。
**`Output` （選用，僅限 JSONata)**
用來指定和轉換 狀態的輸出。指定時，值會覆寫狀態輸出預設值。
輸出欄位接受任何 JSON 值 （物件、陣列、字串、數字、布林值、 null)。任何字串值，包括物件或陣列內的值，如果被 \$1% %\$1 個字元包圍，將評估為 JSONata。
輸出也直接接受 JSONata 表達式，例如：「輸出」：「\$1% jsonata 表達式 %\$1」
如需詳細資訊，請參閱[在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
** `Result` （選用，僅限 JSONPath)**
指傳遞至下一個狀態之虛擬任務的輸出。如果您在狀態機器定義中包含 `ResultPath` 欄位， `Result`會依 指定放置，`ResultPath`並傳遞至下一個狀態。
** `ResultPath` （選用，僅限 JSONPath)**
指定要放置 中指定之虛擬任務*輸出* （相對於輸入） 的位置`Result`。輸入會先依據 `OutputPath` 欄位 (如果有的話) 所指定進一步篩選，而後做為狀態的輸出。如需詳細資訊，請參閱[在 Step Functions 中處理輸入和輸出](concepts-input-output-filtering.md)。
** `Parameters` （選用，僅限 JSONPath)**
建立將做為輸入傳遞的鍵值對集合。您可以指定 `Parameters`做為靜態值，或使用路徑從輸入中選取 。如需詳細資訊，請參閱[在 Step Functions 工作流程中操作參數](input-output-inputpath-params.md)。
## 通過狀態範例 (JSONPath)
以下是 `Pass` 狀態的範例，該範例會將一些固定資料插入狀態機器 (可能用於進行測試)。
```
"No-op": {
"Type": "Pass",
"Result": {
"x-datum": 0.381018,
"y-datum": 622.2269926397355
},
"ResultPath": "$.coords",
"End": true
}
```
假設此狀態的輸入如下。
```
{
"georefOf": "Home"
}
```
然後，輸出會是這個。
```
{
"georefOf": "Home",
"coords": {
"x-datum": 0.381018,
"y-datum": 622.2269926397355
}
}
```
# 等待工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`Wait` 狀態 (`"Type": "Wait"`) 會使狀態機器延遲，而無法繼續執行一段指定的時間。您可以選擇相對時間 (以狀態開始後的秒數指定)，或絕對結束時間 (以時間戳記形式指定)。
除了[常見狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)以外，`Wait` 狀態具有下列其中一個欄位。
** `Seconds` **
開始 `Next` 欄位中指定的狀態之前所要等待的時間 (以秒為單位)。您必須將時間指定為從 0 到 99999999 的整數值。在 JSONata 狀態中，您也可以指定 JSONata 表達式，該表達式必須評估為指定範圍內的整數。
** `Timestamp` **
開始 `Next` 欄位中指定的狀態之前，所要等待的絕對時間。
時間戳記必須符合 ISO 8601 的 RFC3339 設定檔，並且有以下的進一步限制：大寫 `T` 必須分隔日期和時間部分，以及大寫 `Z` 必須表示數字時區位移不存在，例如 `2024-08-18T17:33:00Z`。
在 JSONata 狀態下，您可以指定 JSONata 表達式，該表達式會產生符合先前要求的字串。
目前，如果您將等待時間指定為時間戳記，Step Functions 會考慮最多 秒的時間值，並截斷毫秒。
** `SecondsPath` （選用，僅限 JSONPath) **
中的[路徑](concepts-input-output-filtering.md)會將輸入資料狀態為整數值，指定在繼續下一個狀態之前等待的時間，以秒為單位。
** `TimestampPath` （選用，僅限 JSONPath) **
狀態中的[路徑](concepts-input-output-filtering.md)會將資料輸入至絕對日期和時間 （時間戳記），以便在繼續下一個狀態之前等待。
**注意**
您必須指定 `Seconds`、`Timestamp`、`SecondsPath` 或 `TimestampPath` 其中一項。此外，您可以為標準工作流程和快速工作流程指定的最長等待時間為一年又五分鐘。
## Wait 狀態範例
以下 `Wait` 狀態導致狀態機器延遲 10 秒。
```
"wait_ten_seconds": {
"Type": "Wait",
"Seconds": 10,
"Next": "NextState"
}
```
在下一個範例中，`Wait`狀態會等到絕對時間：2024 年 3 月 14 日上午 1：59 UTC。
```
"wait_until" : {
"Type": "Wait",
"Timestamp": "2024-03-14T01:59:00Z",
"Next": "NextState"
}
```
您不需對此期間進行硬式編碼。舉例而言，假定是以下輸入資料：
```
{
"expirydate": "2024-03-14T01:59:00Z"
}
```
使用參考[路徑](concepts-input-output-filtering.md)從輸入資料中選取 "expirydate" 值，即可從輸入中選取該值。
```
"wait_until" : {
"Type": "Wait",
"TimestampPath": "$.expirydate",
"Next": "NextState"
}
```
# 工作流程狀態成功
`Succeed` 狀態 (`"Type": "Succeed"`) 會成功終止狀態機器、結束 分支[平行工作流程狀態](state-parallel.md)，或結束 的反覆運算[映射工作流程狀態](state-map.md)。`Succeed` 狀態是 `Choice` 狀態分支的有用目標，除了終止狀態機器之外，不會執行任何動作。
因為 `Succeed` 狀態是終端狀態，所以沒有 `Next` 欄位，也不需要 `End` 欄位，如以下範例所示。
```
"SuccessState": {
"Type": "Succeed"
}
```
**`Output` （選用，僅限 JSONata)**
除了[常見的狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)，使用 JSONata `Succeed`的狀態可以包含輸出欄位，以指定和轉換狀態的輸出。指定時，`Output`值會覆寫狀態輸出預設值。
輸出欄位接受任何 JSON 值 （物件、陣列、字串、數字、布林值、 null)。任何字串值，包括物件或陣列內的值，如果被`{% %}`字元包圍，將評估為 JSONata。
輸出也會直接接受 JSONata 表達式，例如：
```
"Output" : "{% jsonata expression %}"
```
如需 JSONata 的詳細資訊，請參閱 [在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)。
# 失敗的工作流程狀態
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`Fail` 狀態 (`"Type": "Fail"`) 會停止執行狀態機器，並將其標示為失敗，除非被`Catch`區塊攔截。
`Fail` 狀態僅允許使用來自一組常見狀態`Comment`欄位的 `Type`和 欄位。 [工作流程中的常見狀態欄位](statemachine-structure.md#amazon-states-language-common-fields)此外，`Fail` 狀態允許使用下列欄位。
** `Cause` (選用)**
描述錯誤原因的自訂字串。您可以指定此欄位用於操作或診斷目的。
在 JSONata 狀態下，您也可以指定 JSONata 表達式。
** `CausePath` （選用，僅限 JSONPath) **
如果您想要使用[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，從狀態輸入動態提供錯誤原因的詳細說明，請使用 `CausePath`。解決後，參考路徑必須選取包含字串值的欄位。
您也可以`CausePath`使用傳回字串[的內部 函數](intrinsic-functions.md)來指定 。這些內部是： [States.Format](intrinsic-functions.md#asl-intrsc-func-generic)、[States.JsonToString](intrinsic-functions.md#jsontostring)、[States.ArrayGetItem](intrinsic-functions.md#arraygetitem)[States.Base64Encode](intrinsic-functions.md#base64encode)、[States.Base64Decode](intrinsic-functions.md#base64decode)、 [States.Hash](intrinsic-functions.md#asl-intrsc-func-uuid-generate) 和 [States.UUID](intrinsic-functions.md#statesuuid)。
+ 您可以在失敗狀態定義中指定 `Cause`或 `CausePath`，但不能同時指定兩者。
+ 作為資訊安全最佳實務，我們建議您從原因描述中移除任何敏感資訊或內部系統詳細資訊。
** `Error` (選用)**
您可以使用[重試](concepts-error-handling.md#error-handling-retrying-after-an-error)或[擷取](concepts-error-handling.md#error-handling-fallback-states)欄位提供錯誤名稱來執行錯誤處理。您也可以提供用於操作或診斷目的的錯誤名稱。
在 JSONata 狀態下，您也可以指定 JSONata 表達式。
** `ErrorPath` （選用，僅限 JSONPath) **
如果您想要使用[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)從狀態輸入動態提供錯誤的名稱，請使用 `ErrorPath`。解決後，參考路徑必須選取包含字串值的欄位。
您也可以`ErrorPath`使用傳回字串[的內部 函數](intrinsic-functions.md)來指定 。這些內部是： [States.Format](intrinsic-functions.md#asl-intrsc-func-generic)、、[States.JsonToString](intrinsic-functions.md#jsontostring)[States.ArrayGetItem](intrinsic-functions.md#arraygetitem)[States.Base64Encode](intrinsic-functions.md#base64encode)、[States.Base64Decode](intrinsic-functions.md#base64decode)、 [States.Hash](intrinsic-functions.md#asl-intrsc-func-uuid-generate) 和 [States.UUID](intrinsic-functions.md#statesuuid)。
+ 您可以在失敗狀態定義中指定 `Error`或 `ErrorPath`，但不能同時指定兩者。
+ 作為資訊安全最佳實務，我們建議您從錯誤名稱中移除任何敏感資訊或內部系統詳細資訊。
由於 `Fail` 狀態一律會結束狀態機器，因此沒有 `Next` 欄位，也不需要 `End` 欄位。
## 失敗狀態定義範例
下列失敗狀態定義範例會指定靜態`Error`和`Cause`欄位值。
```
"FailState": {
"Type": "Fail",
"Cause": "Invalid response.",
"Error": "ErrorA"
}
```
下列失敗狀態定義範例會動態使用參考路徑來解析 `Error`和 `Cause` 欄位值。
```
"FailState": {
"Type": "Fail",
"CausePath": "$.Cause",
"ErrorPath": "$.Error"
}
```
下列失敗狀態定義範例使用 [States.Format](intrinsic-functions.md#asl-intrsc-func-generic) 內部函數動態指定 `Error`和 `Cause` 欄位值。
```
"FailState": {
"Type": "Fail",
"CausePath": "States.Format('This is a custom error message for {}, caused by {}.', $.Error, $.Cause)",
"ErrorPath": "States.Format('{}', $.Error)"
}
```