本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Step Functions 中處理輸入和輸出
**使用變數和 JSONata 管理狀態**
Step Functions 最近新增了變數和 JSONata 來管理狀態和轉換資料。
在部落格文章中進一步了解 [使用 中的變數和 JSONata 簡化開發人員體驗AWS Step Functions](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/)
當 Step Functions 執行收到 JSON 輸入時，它會將該資料傳遞至工作流程中的第一個狀態做為輸入。
使用 JSONata，您可以從 擷取狀態輸入`$states.input`。您的狀態機器執行也會在 中提供該初始輸入資料[前後關聯物件](input-output-contextobject.md)。您可以從 擷取工作流程中任何時間點的原始狀態機器輸入`$states.context.Execution.Input`。
當狀態結束時，其輸出可供狀態機器中*下一個*狀態使用。除非您**修改**狀態輸出，否則狀態輸入預設會傳遞為狀態輸出。對於後續步驟中可能需要的資料，請考慮將其儲存在變數中。如需更多詳細資訊，請參閱[使用變數在狀態之間傳遞資料](workflow-variables.md)。
**QueryLanguage 建議**
對於新的狀態機器，我們建議使用 JSONata 查詢語言。在未指定查詢語言的狀態機器中，狀態機器會預設為 JSONPath，以確保回溯相容性。您必須選擇加入，為您的狀態機器或個別狀態使用 JSONata。
**使用 JSONata 處理輸入和輸出**
使用 JSONata 表達式，您可以選取和轉換資料。在 `Arguments`欄位中，您可以自訂傳送至 動作的資料。結果可以在 `Output` 欄位中轉換為自訂狀態輸出。您也可以將資料存放在 `Assign` 欄位中的變數中。如需詳細資訊，請參閱[使用 JSONata 轉換資料](transforming-data.md)。
下圖顯示 JSON 資訊如何在 JSONata 任務狀態中移動。
![\[Diagram showing JSONata task state flow with input, arguments, output, and action components.\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/vars-jsonata.png)
**使用 JSONPath 處理輸入和輸出**
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
對於使用 JSONPath 的狀態機器，下列欄位控制從狀態到狀態的資料流程：`InputPath`、`Parameters`、`ResultPath`、 `ResultSelector`和 `OutputPath`。每個 JSONPath 欄位都可以在工作流程中的每個狀態移動時操作 JSON。
JSONPath 欄位可以使用[路徑](amazon-states-language-paths.md)，從輸入或結果中選取 JSON 的部分。路徑是以 開頭的字串`$`，可識別 JSON 文字中的節點。Step Functions 路徑使用 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法。
下圖顯示 JSON 資訊如何通過 JSONPath 任務狀態。會`InputPath`選取要傳遞給`Task`狀態任務的 JSON 輸入部分 （例如 AWS Lambda函數）。您可以在 `Parameters` 欄位中調整傳送至動作的資料。然後，使用 `ResultSelector`，您可以選取要繼續執行的動作結果部分。 `ResultPath` 然後， 會選取要傳遞至輸出的狀態輸入和任務結果組合。 `OutputPath`可以篩選 JSON 輸出，以進一步限制傳遞至輸出的資訊。
![\[篩選條件順序：InputPath、參數、ResultSelector、ResultPath 和 OutputPath。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/vars-jsonpath.png)
**Topics**
+ [使用變數在狀態之間傳遞資料](workflow-variables.md)
+ [在 Step Functions 中使用 JSONata 轉換資料](transforming-data.md)
+ [從 Step Functions 中的內容物件存取執行資料](input-output-contextobject.md)
+ [使用 JSONPath 路徑](amazon-states-language-paths.md)
+ [在 Step Functions 工作流程中操作參數](input-output-inputpath-params.md)
+ [範例：使用 Step Functions 工作流程中的路徑處理狀態資料](input-output-example.md)
+ [在 Step Functions 中使用 ResultPath 指定狀態輸出](input-output-resultpath.md)
+ [Step Functions 中的映射狀態輸入和輸出欄位](input-output-fields-dist-map.md)
# 使用變數在狀態之間傳遞資料
**使用變數和 JSONata 管理狀態**
Step Functions 最近新增了變數和 JSONata 來管理狀態和轉換資料。
進一步了解 部落格文章 使用 [中的變數和 JSONata 簡化開發人員體驗 AWS Step Functions](https://aws.amazon.com/blogs/compute/simplifying-developer-experience-with-variables-and-jsonata-in-aws-step-functions/)
以下影片使用 DynamoDB 範例描述 Step Functions 中的變數和 JSONata：
透過變數和狀態輸出，您可以在工作流程的步驟之間傳遞資料。
使用工作流程變數，您可以在步驟中存放資料，並在未來的步驟中擷取該資料。例如，您可以存放 API 回應，其中包含稍後可能需要的資料。相反地，狀態輸出只能用作下一個步驟的輸入。
## 變數的概念概觀
使用工作流程變數，您可以存放資料以供稍後參考。例如，步驟 1 可能會儲存 API 請求的結果，因此稍後可在步驟 5 中重複使用該請求的一部分。
在下列案例中，狀態機器會從 API 擷取資料一次。在步驟 1 中，工作流程會將傳回的 API 資料 （每個狀態最多 256 KiB) 存放在變數「x」中，以供後續步驟使用。
如果沒有變數，您需要透過步驟 1 到步驟 2 到步驟 3 到步驟 4 的輸出來傳遞資料，以在步驟 5 中使用它。如果這些中繼步驟不需要資料該怎麼辦？ 將資料透過輸出和輸入從狀態傳遞到狀態會是不必要的工作。
透過 變數，您可以存放資料，並在任何未來的步驟中使用。您也可以修改、重新排列或新增步驟，而不會中斷資料的流程。有鑑於變數的彈性，您可能只需要使用**輸出**從平行和映射子工作流程傳回資料，並在狀態機器執行結束時傳回資料。
![\[Diagram showing step 1 assigning a value to $x, used in step 5.\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/vars-diag-opt1.png)
**支援變數的狀態 **
下列狀態類型支援`Assign`宣告和指派值給變數：*Pass、Task、Map、Parallel、Choice、Watch。*
若要設定變數，請為 JSON 物件提供變數名稱和值：
```
"Assign": {
"productName": "product1",
"count" : 42,
"available" : true
}
```
若要參考變數，請在名稱前面加上貨幣符號 (`$`)，例如 `$productName`。
## 預留變數 ：\$1states
Step Functions 會定義名為 的單一預留變數**`$states`**。在 JSONata 狀態下，下列結構會指派給 `$states` 以用於 JSONata 表達式：
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
在狀態項目上，Step Functions 會將狀態輸入指派給 **`$states.input`**。的值`$states.input`可用於接受 JSONata 表達式的所有欄位。 `$states.input`一律參考原始狀態輸入。
對於 `Task`、 `Parallel`和 `Map` 狀態：
+ **`$states.result`** 如果成功，則是指 API 或子工作流程的原始結果。
+ **`$states.errorOutput`** 是指 API 或子工作流程失敗時的錯誤輸出。
`$states.errorOutput` 可用於 `Catch` 欄位的 `Assign`或 `Output`。
在建立、更新`$states.result`或驗證狀態機器時，將攔截無法存取它們`$states.errorOutput`的欄位和狀態中嘗試存取 或 。
`$states.context` 物件會提供有關其特定執行的工作流程資訊，例如 `StartTime`、任務字符和初始工作流程輸入。如需詳細資訊，請參閱 [從 Step Functions 中的內容物件存取執行資料](input-output-contextobject.md)。
## 變數名稱語法
變數名稱遵循 Unicode[® Standard Annex \$131 中所述的 Unicode](https://unicode.org/reports/tr31/) 識別符規則。變數名稱的第一個字元必須是 Unicode ID\$1Start 字元，第二個和後續字元必須是 Unicode ID\$1Continue 字元。變數名稱的長度上限為 80。
變數名稱慣例類似於 JavaScript 和其他程式設計語言的規則。
## 變數範圍
Step Functions 工作流程使用*工作流程本機範圍*來避免具有變數的競爭條件。
工作流程本機範圍包括狀態機器**狀態**欄位內的所有狀態，但不包括平行或映射狀態內的所有狀態。Parallel 或 Map 狀態內的狀態可以參考外部範圍變數，但它們會建立和維護自己的個別工作流程本機變數和值。
`Parallel` 分支和`Map`反覆運算可以從**外部範圍**存取變數值，但無法從其他並行分支或反覆運算存取變數值。處理錯誤時， 中的 `Assign` 欄位`Catch`可以將值指派給外部範圍內的變數，也就是 Parallel/Map 狀態存在的範圍。
例外狀況：**分散式映射狀態**目前無法參考外部範圍內的變數。
如果範圍內的任何狀態為其指派值，則變數存在於範圍內。為了協助避免常見錯誤，內部範圍內指派的變數不能具有與外部範圍內指派的變數相同的名稱。例如，如果最上層範圍將值指派給名為 的變數`myVariable`，則也無法將其他範圍 （在 內`Map`，`Parallel`) 指派給 `myVariable`。
變數的存取取決於目前的範圍。平行和映射狀態有自己的範圍，但可以存取外部範圍中的變數。
當平行或映射狀態完成時，其所有變數都將超出範圍並停止存取。使用**輸出欄位**從平行分支和映射反覆運算中傳遞資料。
## ASL 中的指派欄位
ASL 中的 `Assign` 欄位用於將值指派給一或多個變數。`Assign` 欄位可在每個狀態的頂層 ( `Succeed`和 除外`Fail`)、`Choice`狀態內規則和`Catch`欄位內使用。例如：
```
# Example of Assign with JSONata
"Store inputs": {
"Type": "Pass",
"Next": "Get Current Price",
"Comment": "Store the input desired price into a variable: $desiredPrice",
"Assign": {
"desiredPrice": "{% $states.input.desired_price %}",
"maximumWait": "{% $states.input.max_days %}"
}
},
```
`Assign` 欄位接受 JSON 物件。每個最上層欄位都會命名要指派的變數。在先前的範例中，變數名稱為 `desiredPrice`和 `maximumWait`。使用 JSONata 時， `{% ... %}`會指出可能包含變數或更複雜表達式的 JSONata 表達式。如需 JSONata 表達式的詳細資訊，請參閱 [JSONata.org 文件。 ](https://docs.jsonata.org/overview.html)
使用 **JSONata** 做為查詢語言時，下圖顯示如何平行處理**指派**和**輸出**欄位。請注意隱含：*指派變數值不會影響狀態輸出。 *
![\[Diagram showing a comparison of JSONPath and JSONata flow.\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/vars-jsonata.png)
下列 JSONata 範例`order.product`會從狀態輸入擷取 。變數`currentPrice`會設定為任務結果的值。
```
# Example of Task with JSONata assignment from result
{
"Type": "Task",
...
"Assign": {
"product": "{% $states.input.order.product %}",
"currentPrice": "{% $states.result.Payload.current_price %}"
},
"Next": "the next state"
}
```
注意：**您無法**將值指派給變數的一部分。例如，您可以 `"Assign":{"x":42}`，但無法 `"Assign":{"x.y":42}`或 `"Assign":{"x[2]":42}`。
## 指派欄位中的評估順序
Step Functions 狀態中的所有變數參考都會使用**與狀態項目**相同的值。
先前的事實對於了解 `Assign` 欄位如何將值指派給一或多個變數非常重要。首先，計算新值，然後 Step Functions 會將新值指派給變數。新的變數值將從**下一個**狀態開始提供。例如，請考慮下列`Assign`欄位：
```
# Starting values: $x=3, $a=6
"Assign": {
"x": "{% $a %}",
"nextX": "{% $x %}"
}
# Ending values: $x=6, $nextX=3
```
在上述範例中，`x`會同時指派和參考 變數。
請記住，所有表達式都會***先評估***，然後進行指派。而新指派的值將在**下一個**狀態提供。
讓我們詳細介紹範例。假設在先前的狀態下， `$x` 獲指派三 (3) 個值， `$a`獲指派六 (6) 個值。下列步驟說明此程序：
1. 系統會使用所有變數的**目前**值來評估所有表達式。
表達式`"{% $a %}"`將評估為 6，`"{% $x %}"`並將評估為 3。
1. 接下來，會進行指派：
`$x` 將獲指派值六 (6)
`$nextX` 將獲指派三 (3) 個
注意：如果先前`$x`未指派 ，則範例會**失敗**，因為 `$x`未定義。 **
總而言之，Step Functions 會評估**所有**表達式，然後進行指派。變數在 `Assign` 欄位中發生的順序**並不**重要。
## 限制
標準和快速工作流程的單一變數大小上限為 256Kib。
單一`Assign`欄位中所有變數的合併大小上限也是 256Kib。例如，您可以將 X 和 Y 指派給 128KiB，但無法在相同`Assign`欄位中將 X 和 Y 指派給 256KiB。
所有存放變數的總大小不能超過每次執行 10MiB。
## 在 JSONPath 狀態中使用變數
變數也可用於使用 JSONPath 查詢語言的狀態。
您可以在任何接受 JSONpath 表達式 ( `$.`或 `$$.` 語法） 的欄位中參考變數，但 除外`ResultPath`，它會指定狀態輸入中的位置以注入狀態的結果。變數無法在 中使用`ResultPath`。
在 JSONPath 中，`$`符號是指「目前」值，並`$$`代表狀態內容物件。JSONPath 表達式的開頭可以是 ，`$.`如 所示`$.customer.name`。您可以使用 存取內容`$$.`，如 所示`$$.Execution.Id`。
若要參考變數，您也可以在變數名稱之前使用 `$`符號，例如 `$x`或 `$order.numItems`。
在接受內部函數的** JSONPath** 欄位中，變數可用於引數，例如 `States.Format('The order number is {}', $order.number)`。
下列圖表說明 **JSONPath** 任務中的指派步驟與 ResultSelector 同時在 中發生的方式：
![\[Logical diagram of a state that uses JSONPath query language.\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/vars-jsonpath.png)
**在 JSONPath 中指派變數**
JSONPath 變數指派的行為類似於承載範本。以 結尾的欄位`.$`表示值是 JSONPath 表達式，Step Functions 會在狀態機器執行期間評估為值 （例如： `$.order..product`和 `$.order.total`)。
```
# Example of Assign with JSONPath
{
"Type": "Task",
...
"Assign": {
"products.$": "$.order..product",
"orderTotal.$": "$.order.total"
},
"Next": "the next state"
}
```
對於 JSONPath 狀態， `$` `Assign` 欄位中的 值取決於狀態類型。在 `Task,` `Map`中， `Parallel` 狀態`$`是指 API/子工作流程結果。在 `Choice`和 `Wait` 狀態中， `$`是指*有效的輸入*，即 之後的值`InputPath`已套用至狀態輸入。對於 `Pass`， `$`是指結果，無論是由 `Result` 欄位還是 `InputPath`/`Parameters` 欄位產生。
下列 JSONPath 範例會將 JSON 物件指派給 `details`變數、將 JSONPath 表達式的結果`$.result.code`指派給 `resultCode`，並將 JSONPath 表達式的結果`States.Format('Hello {}', $customer.name)`指派給 `message`。如果處於 `Task` 狀態，則 `$` 中的 `$.order.items`和 `$.result.code`會參考 API 結果。`startTime` 變數的指派值來自內容物件 `$$.Execution.StartTime`。
```
"Assign": {
"details": {
"status": "SUCCESS",
"lineItems.$": "$.order.items"
},
"resultCode.$": "$.result.code",
"message.$": "States.Format('Hello {}', $customer.name)",
"startTime.$": "$$.Execution.StartTime"
}
```
# 在 Step Functions 中使用 JSONata 轉換資料
使用 JSONata，您可以獲得強大的開放原始碼查詢和表達式語言，以**選取**和**轉換**工作流程中的資料。如需簡介和完整的 JSONata 參考，請參閱 [JSONata.org 文件。 ](https://docs.jsonata.org/overview.html)
**支援的 JSONata 版本**
Step Functions 支援 JSONata 2.0.6 版。
以下影片使用 DynamoDB 範例描述 Step Functions 中的變數和 JSONata：
您必須選擇加入，才能將 JSONata 查詢和轉換語言用於現有工作流程。在主控台中建立工作流程時，建議您為頂層狀態機器 選擇 JSONata`QueryLanguage`。對於使用 JSONPath 的現有或新工作流程，主控台提供將個別狀態轉換為 JSONata 的選項。
選取 JSONata 之後，您的工作流程欄位將從五個 JSONPath 欄位 (`InputPath`、`ResultPath`、、 `Parameters` `ResultSelector`和 `OutputPath`) 縮減為僅兩個欄位： `Arguments`和 `Output`。此外，您不會在 JSON 物件金鑰名稱****`.$`上使用 。
如果您是 Step Functions 的新手，則只需要知道 JSONata 表達式使用以下語法：
**JSONata 語法：** `"{% %}"`
下列程式碼範例顯示從 JSONPath 轉換為 JSONata：
```
# Original sample using JSONPath
{
"QueryLanguage": "JSONPath", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Parameters": {
"static": "Hello",
"title.$": "$.title",
"name.$": "$customerName", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
```
# Sample after conversion to JSONata
{
"QueryLanguage": "JSONata", // Set explicitly; could be set and inherited from top-level
"Type": "Task",
...
"Arguments": { // JSONata states do not have Parameters
"static": "Hello",
"title": "{% $states.input.title %}",
"name": "{% $customerName %}", // With $customerName declared as a variable
"not-evaluated": "$customerName"
}
}
```
指定的輸入`{ "title" : "Doctor" }`和`customerName`指派給 的變數`"María"`，兩個狀態機器都會產生下列 JSON 結果：
```
{
"static": "Hello",
"title": "Doctor",
"name": "María",
"not-evaluated": "$customerName"
}
```
在下圖中，您可以看到圖形化顯示將 JSONPath （左） 轉換為 JSONata （右） 如何降低狀態機器中步驟的複雜性：
![\[比較 JSONPath 和 JSONata 狀態欄位的圖表。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/compare-jsonpath-jsonata.png)
您可以 （選擇性） 從狀態輸入選取資料並將其轉換為要傳送至整合動作的**引數**。然後，您可以使用 JSONata 從 動作選取並轉換**結果**，以指派給變數和狀態**輸出**。
注意：**指派**和**輸出**步驟會**平行**進行。如果您選擇在變數指派期間轉換資料，該轉換的資料**將無法**在輸出步驟中使用。您必須在輸出步驟中重新套用 JSONata 轉換。
![\[使用 JSONata 查詢語言的狀態邏輯圖。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/vars-jsonata.png)
## QueryLanguage 欄位
在您的工作流程 ASL 定義中，狀態機器定義的最上層和個別狀態都有一個`QueryLanguage`欄位。透過在個別狀態`QueryLanguage`內設定，您可以在現有狀態機器中逐步採用 JSONata，而不是一次全部升級狀態機器。
`QueryLanguage` 欄位可以設定為 `"JSONPath"`或 `"JSONata"`。如果省略最上層`QueryLanguage`欄位，則預設為 `"JSONPath"`。如果狀態包含狀態層級`QueryLanguage`欄位，Step Functions 將使用該狀態的指定查詢語言。如果狀態不包含`QueryLanguage`欄位，則會使用最上層`QueryLanguage`欄位中指定的查詢語言。
## 以 JSON 字串撰寫 JSONata 表達式
當 ASL 欄位值中的字串、JSON 物件欄位或 JSON 陣列元素被`{% %}`字元包圍時，該字串將評估為 JSONata 。請注意，字串必須以 開頭`{%`，沒有開頭空格，且結尾必須`%}`沒有結尾空格。不當開啟或關閉表達式會導致驗證錯誤。
一些範例：
+ `"TimeoutSeconds" : "{% $timeout %}"`
+ `"Arguments" : {"field1" : "{% $name %}"}` 處於 `Task` 狀態
+ `"Items": [1, "{% $two %}", 3]` 處於 `Map` 狀態
並非所有 ASL 欄位都接受 JSONata。例如，每個狀態`Type`的欄位都必須設定為常數字串。同樣地，`Task`狀態`Resource`的欄位必須是常數字串。`Map` 狀態`Items`欄位將接受 JSON 陣列、JSON 物件或必須評估為陣列或物件的 JSONata 表達式。
## 預留變數 ：\$1states
Step Functions 會定義名為 ** `$states` **的單一預留變數。在 JSONata 狀態下，下列結構會指派給 `$states` 以用於 JSONata 表達式：
```
# Reserved $states variable in JSONata states
$states = {
"input": // Original input to the state
"result": // API or sub-workflow's result (if successful)
"errorOutput": // Error Output (only available in a Catch)
"context": // Context object
}
```
在狀態項目上，Step Functions 會將狀態輸入指派給 ** `$states.input` **。的值`$states.input`可用於接受 JSONata 表達式的所有欄位。 `$states.input`一律參考原始狀態輸入。
對於 `Task`、 `Parallel`和 `Map` 狀態：
+ ** `$states.result` ** 如果成功，則是指 API 或子工作流程的原始結果。
+ ** `$states.errorOutput` ** 是指 API 或子工作流程失敗時的錯誤輸出。
`$states.errorOutput` 可用於 `Catch` 欄位的 `Assign`或 `Output`。
在建立、更新`$states.result`或驗證狀態機器時，將會擷取無法存取它們`$states.errorOutput`的欄位和狀態中嘗試存取 或 。
`$states.context` 物件會提供有關其特定執行的工作流程資訊，例如 `StartTime`、任務字符和初始工作流程輸入。若要進一步了解，請參閱 [從 Step Functions 中的內容物件存取執行資料](input-output-contextobject.md) 。
## 處理表達式錯誤
在執行時間，JSONata 表達式評估可能會因為各種原因而失敗，例如：
+ **類型錯誤** - 如果 `$x`或 `$y`不是數字`{% $x + $y %}`，則 等表達式將會失敗。
+ **類型不相容** - 表達式可能會評估為 欄位不接受的類型。例如， 欄位`TimeoutSeconds`需要數值輸入，因此如果 `$timeout`傳回字串，表達式`{% $timeout %}`將會失敗。
+ **值超出範圍 **- 產生超出欄位可接受範圍的值的表達式將會失敗。例如， 等表達式`{% $evaluatesToNegativeNumber %}`會在 `TimeoutSeconds` 欄位中失敗。
+ **無法傳回結果** - JSON 無法代表未定義的值表達式，因此表達式`{% $data.thisFieldDoesNotExist %}`會導致錯誤。
在每個案例中，解譯器都會擲回錯誤：`States.QueryEvaluationError`。您的任務、映射和平行狀態可以提供一個`Catch`欄位來捕捉錯誤，以及一個`Retry`欄位來重試錯誤。
## 從 JSONPath 轉換為 JSONata
下列各節會比較並說明使用 JSONPath 和 JSONata 編寫的程式碼之間的差異。
### 沒有更多路徑欄位
ASL 要求開發人員使用 中的欄位`Path`版本`TimeoutSecondsPath`，以便在使用 JSONPath 時從狀態資料中選取值。當您使用 JSONata 時，您不再使用`Path`欄位，因為 ASL 會在非路徑欄位中自動為您解譯 `{% %}`括住的 JSONata 表達式，例如 `TimeoutSeconds`。
+ JSONPath 舊版範例： `"TimeoutSecondsPath": "$timeout"`
+ JSONata： `"TimeoutSeconds": "{% $timeout %}"`
同樣地，`Map`狀態`ItemsPath`已被接受 JSON 陣列、JSON 物件或必須評估為陣列或物件的 JSONata 表達式`Items`的欄位取代。
### JSON 物件
ASL 使用*承載範本*一詞來描述 JSON 物件，該物件可包含 `Parameters`和 `ResultSelector` 欄位值的 JSONPath 表達式。ASL 不會使用 JSONata 的承載範本一詞，因為 JSONata 評估會針對所有字串執行，無論這些字串是自行執行或在 JSON 物件或 JSON 陣列內執行。
### 不再需要 .\$1
ASL 要求您將「`.$`」附加至承載範本中的欄位名稱，以使用 JSONPath 和內部函數。當您指定 時`"QueryLanguage":"JSONata"`，您不再使用 JSON 物件欄位名稱的「`.$`」慣例。反之，您以`{% %}`字元括住 JSONata 表達式。您為所有字串值欄位使用相同的慣例，無論物件巢狀在其他陣列或物件中的深度為何。
### 引數和輸出欄位
`QueryLanguage` 當 設為 時`JSONata`，舊的 I/O 處理欄位將會停用 (`InputPath`、`ResultSelector`、 `ResultPath`和 `OutputPath`)`Parameters`，而且大多數狀態都會取得兩個新欄位： `Arguments`和 `Output`。
相較於搭配 JSONPath 使用的欄位，JSONata 提供更簡單的 I/O 轉換執行方式。JSONata 的功能使用 JSONPath 讓 `Arguments`和 變得比前五個欄位`Output`更強大。這些新的欄位名稱也有助於簡化您的 ASL，並釐清傳遞和傳回值的模型。
`Arguments` 和 `Output` 欄位 （以及其他類似的欄位，例如`Map`狀態的 `ItemSelector`) 將接受 JSON 物件，例如：
```
"Arguments": {
"field1": 42,
"field2": "{% jsonata expression %}"
}
```
或者，您可以直接使用 JSONata 表達式，例如：
```
"Output": "{% jsonata expression %}"
```
輸出也可以接受任何類型的 JSON 值，例如：`"Output":true`、`"Output":42`。
`Arguments` 和 `Output` 欄位僅支援 JSONata，因此與使用 JSONPath 的工作流程搭配使用是無效的。相反地，`InputPath`、`Parameters`、、、 `ResultSelector` `ResultPath` `OutputPath` 和其他 JSONPath 欄位僅支援 JSONPath，因此使用 JSONata 做為頂層工作流程或狀態查詢語言時，使用路徑型欄位無效。
### 傳遞狀態
進入通過狀態的選用**結果**先前視為虛擬任務的*輸出*。選取 JSONata 做為工作流程或狀態查詢語言時，您現在可以使用新的**輸出**欄位。
### 選擇狀態
使用 JSONPath 時，選擇狀態具有輸入`Variable`和許多比較路徑，例如下列 `NumericLessThanEqualsPath` ：
```
# JSONPath choice state sample, with Variable and comparison path
"Check Price": {
"Type": "Choice",
"Default": "Pause",
"Choices": [
{
"Variable": "$.current_price.current_price",
"NumericLessThanEqualsPath": "$.desired_price",
"Next": "Send Notification"
} ],
}
```
使用 JSONata 時，選擇狀態具有 ，您可以在`Condition`其中使用 JSONata 表達式：
```
# Choice state after JSONata conversion
"Check Price": {
"Type": "Choice",
"Default": "Pause"
"Choices": [
{
"Condition": "{% $current_price <= $states.input.desired_priced %}",
"Next": "Send Notification"
} ]
```
注意：變數和比較欄位僅適用於 JSONPath。條件僅適用於 JSONata。
## JSONata 範例
下列範例可在 Workflow Studio 中建立，以實驗 JSONata。您可以建立和執行狀態機器，或使用**測試狀態**來傳入資料，甚至修改狀態機器定義。
### 範例：輸入和輸出
此範例顯示當您選擇加入 JSONata 時，如何使用 `$states.input`來使用狀態輸入和 `Output` 欄位來指定狀態輸出。
```
{
"Comment": "Input and Output example using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "Basic Input and Output",
"States": {
"Basic Input and Output": {
"QueryLanguage": "JSONata",
"Type": "Succeed",
"Output": {
"lastName": "{% 'Last=>' & $states.input.customer.lastName %}",
"orderValue": "{% $states.input.order.total %}"
}
}
}
}
```
以下列做為輸入執行工作流程時：
```
{
"customer": {
"firstName": "Martha",
"lastName": "Rivera"
},
"order": {
"items": 7,
"total": 27.91
}
}
```
測試狀態或狀態機器執行將傳回下列 JSON 輸出：
```
{
"lastName": "Last=>Rivera",
"orderValue": 27.91
}
```
![\[螢幕擷取畫面顯示待測狀態的輸入和輸出。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/jsonata-basic-io.png)
### 範例：使用 JSONata 篩選
您可以使用 JSONata [路徑運算子](https://docs.jsonata.org/path-operators)來篩選資料。例如，假設您有一個產品清單可供輸入，而且您只想處理零卡的產品。您可以使用下列 ASL 建立狀態機器定義，並使用下列範例輸入測試`FilterDietProducts`狀態。
**使用 JSONata 篩選的狀態機器定義**
```
{
"Comment": "Filter products using JSONata",
"QueryLanguage": "JSONata",
"StartAt": "FilterDietProducts",
"States": {
"FilterDietProducts": {
"Type": "Pass",
"Output": {
"dietProducts": "{% $states.input.products[calories=0] %}"
},
"End": true
}
}
}
```
**測試的範例輸入**
```
{
"products": [
{
"calories": 140,
"flavour": "Cola",
"name": "Product-1"
},
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 160,
"flavour": "Orange",
"name": "Product-3"
},
{
"calories": 100,
"flavour": "Orange",
"name": "Product-4"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
**在狀態機器中測試步驟的輸出**
```
{
"dietProducts": [
{
"calories": 0,
"flavour": "Cola",
"name": "Product-2"
},
{
"calories": 0,
"flavour": "Lime",
"name": "Product-5"
}
]
}
```
![\[測試中 JSONata 表達式的範例輸出。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/test-state-jsonata.png)
## Step Functions 提供的 JSONata 函數
JSONata 包含用於字串、數值、彙總、布林值、陣列、物件、日期/時間和高階函數的函數程式庫。Step Functions 提供您可以在 JSONata 表達式中使用的其他 JSONata 函數。這些內建函數可取代 Step Functions 內部函數。內部函數僅適用於使用 JSONPath 查詢語言的狀態。
注意：需要整數值作為參數的內建 JSONata 函數會自動捨去所提供的任何非整數。
**\$1partition -** JSONata 等同於`States.ArrayPartition`內部函數來分割大型陣列。
第一個參數是要分割的陣列，第二個參數是代表區塊大小的整數。傳回值將是二維陣列。解譯器會將輸入陣列區塊化為區塊大小所指定大小的多個陣列。如果陣列中剩餘項目的數量小於區塊大小，則最後一個陣列區塊的長度可能會小於先前陣列區塊的長度。
```
"Assign": {
"arrayPartition": "{% $partition([1,2,3,4], $states.input.chunkSize) %}"
}
```
**\$1range** - JSONata 等同於`States.ArrayRange`內部函數以產生值陣列。
此函數需要三個引數。第一個引數是代表新陣列第一個元素的整數，第二個引數是代表新陣列最終元素的整數，第三個引數是新陣列中元素的差異值整數。傳回值是新產生的值陣列，範圍從函數的第一個引數到函數的第二個引數，其中元素在 之間由差異調整。差異值可以是正值或負值，這會從最後一個遞增或遞減每個元素，直到達到或超過結束值為止。
```
"Assign": {
"arrayRange": "{% $range(0, 10, 2) %}"
}
```
**\$1hash** - JSONata 等同於`States.Hash`內部函數，用於計算指定輸入的雜湊值。
此函數需要兩個引數。第一個引數是要雜湊的來源字串。第二個引數是代表雜湊演算法的字串，用於雜湊計算。雜湊演算法必須是下列其中一個值：`"MD5"`、`"SHA-1"`、`"SHA-256"`、`"SHA-384"`、`"SHA-512"`。傳回值是計算資料雜湊的字串。
建立此函數是因為 JSONata 原生不支援計算雜湊的能力。
```
"Assign": {
"myHash": "{% $hash($states.input.content, $hashAlgorithmName) %}"
}
```
**\$1random** - JSONata 等同於`States.MathRandom`內部函數，以傳回隨機數字 n，其中 `0 ≤ n < 1`。
函數會採用*選用*的整數引數，代表隨機函數的種子值。如果您使用此函數搭配相同的種子值，則會傳回相同的數字。
建立此過載函數是因為內建 JSONata 函數[https://docs.jsonata.org/numeric-functions#random](https://docs.jsonata.org/numeric-functions#random)不接受種子值。
```
"Assign": {
"randNoSeed": "{% $random() %}",
"randSeeded": "{% $random($states.input.seed) %}"
}
```
**\$1uuid** - JSONata 版`States.UUID`的內部函數。
函數不採用引數。此函數會傳回 v4 UUID。
建立此函數是因為 JSONata 原生不支援產生 UUIDs的能力。
```
"Assign": {
"uniqueId": "{% $uuid() %}"
}
```
**\$1parse** - 用於還原序列化 JSON 字串的 JSONata 函數。
函數採用字串化 JSON 作為其唯一引數。
JSONata 透過 支援此功能`$eval`；但 Step Functions 工作流程`$eval`不支援 。
```
"Assign": {
"deserializedPayload": "{% $parse($states.input.json_string) %}"
}
```
# 從 Step Functions 中的內容物件存取執行資料
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
內容物件是在執行期間可用的內部 JSON 結構，其中包含狀態機器和執行的相關資訊。內容提供工作流程特定執行的相關資訊。您的工作流程可以使用 參考 JSONata 表達式中的內容物件`$states.context`。
## 存取內容物件
**存取 JSONata 中的內容物件**
若要以 JSONata 狀態存取內容物件，請在 JSONata 表達式`$states.context`中使用 。
```
{
"ExecutionID" : "{% $states.context.Execution.Id %}"
}
```
**在 JSONPath 中存取內容物件**
若要存取 JSONPath 中的內容物件，請先附加`.$`至金鑰的結尾，以指出值為路徑。然後，在值前面加上 ，`$$.`以選取內容物件中的節點。
```
{
"ExecutionID.$": "$$.Execution.Id"
}
```
JSONPath 狀態可以參考下列 JSONPath 欄位的內容 (`$$.`)：
+ `InputPath`
+ `OutputPath`
+ `ItemsPath` （在映射狀態下）
+ `Variable` （在選擇狀態）
+ `ResultSelector`
+ `Parameters`
+ 變數對變數比較運算子的變數
## 內容物件欄位
內容物件包含狀態機器、狀態、執行和任務的相關資訊。內容 JSON 物件包含每種資料類型的節點，格式如下：
```
{
"Execution": {
"Id": "String",
"Input": {},
"Name": "String",
"RoleArn": "String",
"StartTime": "Format: ISO 8601",
"RedriveCount": Number,
"RedriveTime": "Format: ISO 8601"
},
"State": {
"EnteredTime": "Format: ISO 8601",
"Name": "String",
"RetryCount": Number
},
"StateMachine": {
"Id": "String",
"Name": "String"
},
"Task": {
"Token": "String"
}
}
```
在執行期間，內容物件會填入相關資料。
有時候，新的欄位會新增至內容。如果您直接處理 JSON 內容，建議您製作可正常處理新未知欄位的程式碼。例如，如果使用 Jackson 程式庫取消封送 JSON，建議您在 `false`中`FAIL_ON_UNKNOWN_PROPERTIES`將 設定為 `ObjectMapper` ，以防止 `UnrecognizedPropertyException`。
`RedriveTime` 內容物件只有在您有redriven執行時才可用。如果您有 [redriven a Map Run](redrive-map-run.md)，`RedriveTime`內容物件僅適用於 Standard 類型的子工作流程。對於具有 Express 類型的子工作流程的 redriven Map Run， `RedriveTime` 無法使用。
執行中執行的內容包含以下格式的詳細資訊：
```
{
"Execution": {
"Id": "arn:aws:states:region:123456789012:execution:stateMachineName:executionName",
"Input": {
"key": "value"
},
"Name": "executionName",
"RoleArn": "arn:aws:iam::123456789012:role...",
"StartTime": "2025-08-27T10:04:42Z"
},
"State": {
"EnteredTime": "2025-08-27T10:04:42.001Z",
"Name": "Test",
"RetryCount": 3
},
"StateMachine": {
"Id": "arn:aws:states:region:123456789012:stateMachine:stateMachineName",
"Name": "stateMachineName"
},
"Task": {
"Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
}
}
```
**具有小數秒的時間戳記格式**
Step Functions 遵循 ISO8601 規格，該規格指出輸出可以是零、三、六或九位數。當時間戳記具有零分秒時，Step Functions 會移除結尾的零，而不是填補輸出。
如果您建立使用 Step Functions 時間戳記的程式碼，您的程式碼必須能夠處理小數秒的變數數目。
## Map 狀態的內容物件資料
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
處理[`Map`狀態](state-map.md)時，內容也會包含 `Index`、 `Value`和 `Source`。
對於每個`Map`狀態反覆運算， `Index` 包含目前正在處理的陣列項目索引號碼、`Value`包含正在處理的陣列項目，並將`Source`是 `CSV`、`JSON`、 `JSONL`或 的 InputType`PARQUET`。
在 `Map` 狀態中，內容物件包含下列資料：
```
"Map": {
"Item": {
"Index" : Number,
"Key" : "String", // Only valid for JSON objects
"Value" : "String",
"Source": "String"
}
}
```
這些只能在 `Map` 狀態中使用，並且可以在 `ItemSelector （地圖）` 欄位中指定。
**注意**
您必須從主要`Map`狀態`ItemSelector`區塊中的內容物件定義參數，而不是在`ItemProcessor`區段中包含的狀態內。
如果狀態機器使用 **JSONPath** `Map` 狀態，您可以從內容物件插入資訊，如下所示。
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex.$": "$$.Map.Item.Index",
"ContextValue.$": "$$.Map.Item.Value",
"ContextSource.$": "$$.Map.Item.Source"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
對於 JSONata，您可以從 `$states.context`變數存取額外的映射狀態內容資訊：
```
{
"StartAt": "ExampleMapState",
"States": {
"ExampleMapState": {
"Type": "Map",
"ItemSelector": {
"ContextIndex": "{% $states.context.Map.Item.Index %}",
"ContextValue": "{% $states.context.Map.Item.Value %}",
"ContextSource": "{% $states.context.Map.Item.Source %}"
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "TestPass",
"States": {
"TestPass": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
如果您使用下列輸入執行先前的狀態機器，`Index` 和 `Value` 會插入到輸出中。
```
[
{
"who": "bob"
},
{
"who": "meg"
},
{
"who": "joe"
}
]
```
執行的輸出會傳回三個反覆運算中的每個 `Index`和 `Value`項目的值，如下所示：
```
[
{
"ContextIndex": 0,
"ContextValue": {
"who": "bob"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 1,
"ContextValue": {
"who": "meg"
},
"ContextSource" : "STATE_DATA"
},
{
"ContextIndex": 2,
"ContextValue": {
"who": "joe"
},
"ContextSource" : "STATE_DATA"
}
]
```
請注意， `$states.context.Map.Item.Source` 將是下列其中一項：
+ 對於狀態輸入，值將為 ： `STATE_DATA`
+ 對於`Amazon S3 LIST_OBJECTS_V2`使用 的 `Transformation=NONE`，值會顯示儲存貯體的 S3 URI。例如：`S3://bucket-name`。
+ 對於所有其他輸入類型，值將是 Amazon S3 URI。例如：`S3://bucket-name/object-key`。
# 使用 JSONPath 路徑
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
在 Amazon States Language 中，*路徑*是開頭為 的字串`$`，可用來識別 JSON 文字中的元件。路徑遵循 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 語法，只有在 `QueryLanguage` 設定為 JSONPath 時才能使用。當指定 `InputPath`、`ResultPath` 和 `OutputPath` 的值時，您可以指定用來存取輸入子集的路徑。
如果您的欄位名稱包含 [JsonPath ABNF](https://www.ietf.org/archive/id/draft-ietf-jsonpath-base-21.html#jsonpath-abnf) 規則`member-name-shorthand`定義中未包含的任何字元，則必須使用方括號表示法。因此，若要編碼特殊字元，例如標點符號 ( 除外`_`)，您必須使用方括號表示法。例如 `$.abc.['def ghi']`。
## 參考路徑
*參考路徑*是一種語法有限的路徑，可供僅只識別 JSON 結構中的單一節點：
+ 您可以僅使用點 (`.`) 和方括號 (`[ ]`) 符號來存取物件欄位。
+ 不支援函數，例如 `length()`。
+ 不支援非符號的語彙運算子，例如 `subsetof` 。
+ 不支援依規則表達式或參考 JSON 結構中的另一個值進行篩選。
+ `?` 不支援運算子 `@`、`:`、 `,`和
例如，如果狀態輸入資料包含下列值：
```
{
"foo": 123,
"bar": ["a", "b", "c"],
"car": {
"cdr": true
}
}
```
下列參考路徑會傳回下列。
```
$.foo => 123
$.bar => ["a", "b", "c"]
$.car.cdr => true
```
有些狀態使用路徑和參考路徑來控制狀態機器的流程，或設定狀態的設定或選項。如需詳細資訊，請參閱[使用資料流程模擬器建立工作流程輸入和輸出路徑處理的模型](https://aws.amazon.com/blogs/compute/modeling-workflow-input-output-path-processing-with-data-flow-simulator/)，以及[有效使用 JSONPathAWS Step Functions](https://aws.amazon.com/blogs/compute/using-jsonpath-effectively-in-aws-step-functions/)。
### 平面化陣列陣列
如果狀態機器中的 [平行工作流程狀態](state-parallel.md)或 [映射工作流程狀態](state-map.md) 狀態傳回陣列，您可以使用 [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 欄位將陣列轉換為平面陣列。您可以在平行或映射狀態定義中包含此欄位，以操作這些狀態的結果。
若要扁平化陣列，請在 `ResultSelector` `[*]`欄位中使用語法：，如下列範例所示。
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
如需示範如何扁平化陣列的範例，請參閱下列教學課程中*的步驟 3*：
+ [在 Step Functions 中使用 Lambda 函數處理批次資料](tutorial-itembatcher-param-task.md)
+ [在 Step Functions 中使用 Lambda 函數處理個別項目](tutorial-itembatcher-single-item-process.md)
# 在 Step Functions 工作流程中操作參數
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`InputPath`、 `Parameters`和 `ResultSelector` 欄位提供在 JSON 在工作流程中移動時操作 JSON 的方法。 `InputPath`可以使用路徑篩選 JSON 表示法來限制傳遞的輸入 （請參閱 [使用 JSONPath 路徑](amazon-states-language-paths.md))。使用 `Parameters` 欄位，您可以使用靜態值或使用路徑從輸入中選擇來傳遞鍵值對的集合。
`ResultSelector` 欄位提供在`ResultPath`套用 之前操作狀態結果的方法。
AWS Step Functions會先套用 `InputPath` 欄位，再套用 `Parameters` 欄位。您可以先使用 `InputPath` 將原始輸入篩選成您所要的選取範圍，然後套用 `Parameters` 來進一步操作輸入，或增加新的值。然後，您可以在`ResultPath`套用 之前使用 `ResultSelector` 欄位來操作狀態的輸出。
## InputPath
使用 `InputPath` 來選取一部分的狀態輸入。
例如，假設狀態的輸入包含下列項目：
```
{
"comment": "Example for InputPath.",
"dataset1": {
"val1": 1,
"val2": 2,
"val3": 3
},
"dataset2": {
"val1": "a",
"val2": "b",
"val3": "c"
}
}
```
您可以套用 `InputPath`。
```
"InputPath": "$.dataset2",
```
透過前述的 `InputPath`，依輸入方式傳遞的 JSON 將如下所示。
```
{
"val1": "a",
"val2": "b",
"val3": "c"
}
```
**注意**
路徑可以產生一組值。請考量下列範例。
```
{ "a": [1, 2, 3, 4] }
```
如果您套用路徑 `$.a[0:2]`，則結果如下。
```
[ 1, 2 ]
```
## Parameters
本節說明您可以使用參數欄位的不同方式。
### 鍵值對
使用 `Parameters` 欄位來建立做為輸入傳遞的鍵值對集合。每個 的值可以是您在狀態機器定義中包含的靜態值，也可以從具有路徑的輸入或內容物件中選取。對於使用路徑來選取值的索引鍵/值組，索引鍵名稱必須以 `.$` 做為結尾。
例如，假設您提供以下輸入。
```
{
"comment": "Example for Parameters.",
"product": {
"details": {
"color": "blue",
"size": "small",
"material": "cotton"
},
"availability": "in stock",
"sku": "2317",
"cost": "$23"
}
}
```
若要選取一些資訊，您可以在狀態機器定義中指定這些參數。
```
"Parameters": {
"comment": "Selecting what I care about.",
"MyDetails": {
"size.$": "$.product.details.size",
"exists.$": "$.product.availability",
"StaticValue": "foo"
}
},
```
在前述輸入及 `Parameters` 欄位條件下，這是所傳遞的 JSON。
```
{
"comment": "Selecting what I care about.",
"MyDetails": {
"size": "small",
"exists": "in stock",
"StaticValue": "foo"
}
},
```
除了輸入之外，您還可以存取稱為內容物件的特殊 JSON 物件。內容物件包含狀態機器執行的相關資訊。請參閱 [從 Step Functions 中的內容物件存取執行資料](input-output-contextobject.md)。
### 連線的資源
`Parameters` 欄位也可以將資訊傳遞給已連線的資源。例如，如果您的任務狀態正在協調AWS Batch任務，您可以將相關的 API 參數直接傳遞至該服務的 API 動作。如需詳細資訊，請參閱：
+ [在 Step Functions 中將參數傳遞至服務 API](connect-parameters.md)
+ [整合 服務](integrate-services.md)
### Amazon S3
如果您要在狀態之間傳遞的 Lambda 函數資料可能成長到超過 262，144 個位元組，我們建議您使用 Amazon S3 來存放資料，並實作下列其中一種方法：
+ 在工作流程中使用*分散式映射狀態*，讓`Map`狀態可以直接從 Amazon S3 資料來源讀取輸入。如需詳細資訊，請參閱[分散式模式](state-map-distributed.md)。
+ 在 `Payload` 參數中剖析儲存貯體的 Amazon Resource Name (ARN)，以取得儲存貯體名稱和金鑰值。如需詳細資訊，請參閱[在 Step Functions 中使用 Amazon S3 ARNs 而非傳遞大型承載](sfn-best-practices.md#avoid-exec-failures)。
或者，您可以調整實作，以在執行中傳遞較小的承載。
## ResultSelector
在`ResultPath`套用 之前，使用 `ResultSelector` 欄位來操作狀態的結果。`ResultSelector` 欄位可讓您建立金鑰值對的集合，其中值為靜態或從狀態的結果中選取。使用 `ResultSelector` 欄位，您可以選擇您要傳遞給 `ResultPath` 欄位之狀態結果的哪些部分。
**注意**
使用 `ResultPath` 欄位，您可以將 `ResultSelector` 欄位的輸出新增至原始輸入。
`ResultSelector` 是下列狀態的選用欄位：
+ [映射工作流程狀態](state-map.md)
+ [任務工作流程狀態](state-task.md)
+ [平行工作流程狀態](state-parallel.md)
例如，除了結果中的承載之外，Step Functions 服務整合還傳回中繼資料。 `ResultSelector`可以選取結果的一部分，並將其與狀態輸入與 合併`ResultPath`。在此範例中，我們只想選取 `resourceType`和 `ClusterId`，並將其與來自 Amazon EMR createCluster.sync. 假設下列事項：
```
{
"resourceType": "elasticmapreduce",
"resource": "createCluster.sync",
"output": {
"SdkHttpMetadata": {
"HttpHeaders": {
"Content-Length": "1112",
"Content-Type": "application/x-amz-JSON-1.1",
"Date": "Mon, 25 Nov 2019 19:41:29 GMT",
"x-amzn-RequestId": "1234-5678-9012"
},
"HttpStatusCode": 200
},
"SdkResponseMetadata": {
"RequestId": "1234-5678-9012"
},
"ClusterId": "AKIAIOSFODNN7EXAMPLE"
}
}
```
然後，您可以使用 選取 `resourceType`和 `ClusterId` `ResultSelector`：
```
"Create Cluster": {
"Type": "Task",
"Resource": "arn:aws:states:::elasticmapreduce:createCluster.sync",
"Parameters": {
},
"ResultSelector": {
"ClusterId.$": "$.output.ClusterId",
"ResourceType.$": "$.resourceType"
},
"ResultPath": "$.EMROutput",
"Next": "Next Step"
}
```
透過指定的輸入，使用 `ResultSelector`會產生：
```
{
"OtherDataFromInput": {},
"EMROutput": {
"ClusterId": "AKIAIOSFODNN7EXAMPLE",
"ResourceType": "elasticmapreduce",
}
}
```
### 平面化陣列陣列
如果狀態機器中的 [平行工作流程狀態](state-parallel.md)或 [映射工作流程狀態](state-map.md) 狀態傳回陣列，您可以使用 [ResultSelector](#input-output-resultselector) 欄位將陣列轉換為平面陣列。您可以在平行或映射狀態定義中包含此欄位，以操作這些狀態的結果。
若要扁平化陣列，請在 `ResultSelector` `[*]`欄位中使用語法：，如下列範例所示。
```
"ResultSelector": {
"flattenArray.$": "$[*][*]"
}
```
如需示範如何扁平化陣列的範例，請參閱下列教學課程中*的步驟 3*：
+ [在 Step Functions 中使用 Lambda 函數處理批次資料](tutorial-itembatcher-param-task.md)
+ [在 Step Functions 中使用 Lambda 函數處理個別項目](tutorial-itembatcher-single-item-process.md)
# 範例：使用 Step Functions 工作流程中的路徑處理狀態資料
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
本主題包含如何使用 InputPath、ResultPath 和 OutputPath 欄位來操作狀態輸入和輸出 JSON 的範例。
狀態[失敗的工作流程狀態](state-fail.md)或[工作流程狀態成功](state-succeed.md)狀態以外的任何狀態都可以包含輸入和輸出處理欄位，例如 `InputPath`、 `ResultPath`或 `OutputPath`。此外， [等待工作流程狀態](state-wait.md)和 [選擇工作流程狀態](state-choice.md) 狀態不支援 `ResultPath` 欄位。透過這些欄位，您可以使用 [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/) 來篩選在工作流程中移動的 JSON 資料。
您也可以使用 `Parameters` 欄位，在 JSON 資料在工作流程中移動時對其進行操作。如需使用 `Parameters` 的相關資訊，請參閱 [在 Step Functions 工作流程中操作參數](input-output-inputpath-params.md)。
例如，從[建立使用 Lambda 的 Step Functions 狀態機器](tutorial-creating-lambda-state-machine.md)教學中描述的 AWS Lambda 函數和狀態機器開始。修改狀態機器，使其包含下列 `InputPath`、`ResultPath` 及 `OutputPath`。
```
{
"Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function",
"StartAt": "HelloWorld",
"States": {
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:HelloFunction",
"InputPath": "$.lambda",
"ResultPath": "$.data.lambdaresult",
"OutputPath": "$.data",
"End": true
}
}
}
```
使用以下輸入開始執行。
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
假設可以捨棄 `comment`和 `extra`節點，但您想要包含 Lambda 函數的輸出，並保留`data`節點中的資訊。
在已更新的狀態機器中，`Task` 狀態會更改為處理任務輸入。
```
"InputPath": "$.lambda",
```
狀態機器定義中的這一行會將任務輸入限制為僅限任務輸入中的 `lambda` 節點。Lambda 函數只會接收 JSON 物件`{"who": "AWS Step Functions"}`做為輸入。
```
"ResultPath": "$.data.lambdaresult",
```
這會`ResultPath`告知狀態機器將 Lambda 函數的結果插入名為 的節點`lambdaresult`，做為原始狀態機器輸入中`data`節點的子項。由於您沒有使用 對原始輸入和結果執行任何其他操作`OutputPath`，因此狀態的輸出現在會包含 Lambda 函數的結果與原始輸入。
```
{
"comment": "An input comment.",
"data": {
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
},
"extra": "foo",
"lambda": {
"who": "AWS Step Functions"
}
}
```
但是，我們的目標是只保留`data`節點，並包含 Lambda 函數的結果。 會先`OutputPath`篩選此合併 JSON，再將其傳遞至狀態輸出。
```
"OutputPath": "$.data",
```
這只會選取原始輸入中要傳遞到輸出的 `data` 節點 (包括 `ResultPath` 所插入的 `lambdaresult` 子系)。狀態輸出會篩選到下列。
```
{
"val1": 23,
"val2": 17,
"lambdaresult": "Hello, AWS Step Functions!"
}
```
在此 `Task` 狀態中：
1. `InputPath` 只會將`lambda`節點從輸入傳送至 Lambda 函數。
1. `ResultPath` 會插入結果做為原始輸入中 `data` 節點的子節點。
1. `OutputPath` 會篩選狀態輸入 （現在包含 Lambda 函數的結果），使其僅將`data`節點傳遞至狀態輸出。
**Example 使用 JsonPath 操作原始狀態機器輸入、結果和最終輸出**
請考慮以下狀態機器，以驗證保險申請人的身分和地址。
若要檢視完整範例，請參閱 [Step Functions 中的如何使用 JSON 路徑](https://github.com/aws-samples/serverless-account-signup-service)。
```
{
"Comment": "Sample state machine to verify an applicant's ID and address",
"StartAt": "Verify info",
"States": {
"Verify info": {
"Type": "Parallel",
"End": true,
"Branches": [
{
"StartAt": "Verify identity",
"States": {
"Verify identity": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-identity:$LATEST"
},
"End": true
}
}
},
{
"StartAt": "Verify address",
"States": {
"Verify address": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:us-east-2:111122223333:function:check-address:$LATEST"
},
"End": true
}
}
}
]
}
}
}
```
如果您使用以下輸入執行此狀態機器，則執行會失敗，因為執行驗證的 Lambda 函數只預期需要驗證為輸入的資料。因此，您必須指定包含要使用適當 JsonPath 驗證之資訊的節點。
```
{
"data": {
"firstname": "Jane",
"lastname": "Doe",
"identity": {
"email": "jdoe@example.com",
"ssn": "123-45-6789"
},
"address": {
"street": "123 Main St",
"city": "Columbus",
"state": "OH",
"zip": "43219"
},
"interests": [
{
"category": "home",
"type": "own",
"yearBuilt": 2004
},
{
"category": "boat",
"type": "snowmobile",
"yearBuilt": 2020
},
{
"category": "auto",
"type": "RV",
"yearBuilt": 2015
},
]
}
}
```
若要指定 `check-identity` Lambda 函數必須使用的節點，請使用 `InputPath` 欄位，如下所示：
```
"InputPath": "$.data.identity"
```
若要指定 `check-address` Lambda 函數必須使用的節點，請使用 `InputPath` 欄位，如下所示：
```
"InputPath": "$.data.address"
```
現在，如果您想要將驗證結果存放在原始狀態機器輸入中，請使用 `ResultPath` 欄位，如下所示：
```
"ResultPath": "$.results"
```
不過，如果您只需要身分和驗證結果並捨棄原始輸入，請使用 `OutputPath` 欄位，如下所示：
```
"OutputPath": "$.results"
```
如需詳細資訊，請參閱[在 Step Functions 中處理輸入和輸出](concepts-input-output-filtering.md)。
## 使用 OutputPath 篩選狀態輸出
使用 `OutputPath` ，您可以選取要傳遞至下一個狀態的部分狀態輸出。使用此方法，您可以篩選掉不需要的資訊，並只傳遞您需要的 JSON 部分。
如未指定 `OutputPath`，預設值將會是 `$`。這樣會將整個 JSON 節點 (由狀態輸入、任務結果及 `ResultPath` 決定) 傳遞至下一個狀態。
# 在 Step Functions 中使用 ResultPath 指定狀態輸出
**管理狀態和轉換資料**
此頁面是指 JSONPath。Step Functions 最近新增了變數和 JSONata 來管理狀態和轉換資料。
了解如何[使用變數傳遞資料](workflow-variables.md)，以及[使用 JSONata 轉換資料](transforming-data.md)。
狀態的輸出可以是其輸入的複本、所產生的結果 (例如，從 `Task` 狀態之 Lambda 函數的輸出)，或輸入和結果的結合。使用 `ResultPath` 以控制哪些組合會傳遞至狀態輸出。
以下狀態類型可以產生結果，並可包含 `ResultPath:`
+ [傳遞工作流程狀態](state-pass.md)
+ [任務工作流程狀態](state-task.md)
+ [平行工作流程狀態](state-parallel.md)
+ [映射工作流程狀態](state-map.md)
使用 `ResultPath` 合併任務結果與任務輸入，或選取其中一個。您提供給 `ResultPath` 的路徑會控制哪些資訊會傳遞到輸出。
**注意**
`ResultPath` 僅限於使用[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，這會限制範圍，因此路徑必須僅識別 JSON 中的單一節點。請參閱 [Amazon States Language](concepts-amazon-states-language.md) [參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)中的 。
## 使用 ResultPath 將輸入取代為任務結果
如果您未指定 `ResultPath`，預設行為會與 相同`"ResultPath": "$"`。狀態會將整個狀態輸入取代為任務的結果。
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$"
# Task result
"Hello, Step Functions!"
# State Output
"Hello, Step Functions!"
```
**注意**
`ResultPath` 是在傳遞至輸出之前，用於在輸入中包含來自結果的內容。但是，如果`ResultPath`未指定 ，則預設動作是取代整個輸入。
## 捨棄結果並保留原始輸入
如果您將 `ResultPath`設定為 `null`，狀態會將**原始輸入**傳遞至輸出。狀態的輸入承載會直接複製到輸出，而不考慮任務結果。
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": null
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
```
## 使用 ResultPath 在輸入中包含結果
如果您為 ResultPath 指定路徑，狀態輸出將結合狀態輸入和任務結果：
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.taskresult"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions",
"taskresult" : "Hello, Step Functions!"
}
```
您也可以在子節點的輸入中插入結果。將 `ResultPath` 設定為下列。
```
"ResultPath": "$.strings.lambdaresult"
```
根據下列輸入：
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz"
},
"who": "AWS Step Functions"
}
```
任務結果會插入為輸入中`strings`節點的子項。
```
{
"comment": "An input comment.",
"strings": {
"string1": "foo",
"string2": "bar",
"string3": "baz",
"lambdaresult": "Hello, Step Functions!"
},
"who": "AWS Step Functions"
}
```
狀態輸入現在會將原始輸入 JSON 做為子節點包含在結果中。
## 使用 ResultPath 以結果更新輸入中的節點
如果您為 ResultPath 指定現有節點，任務結果將取代該現有節點：
```
# State Input
{
"comment": "This is a test",
"details": "Default example",
"who" : "Step Functions"
}
# Path
"ResultPath": "$.comment"
# Task result
"Hello, Step Functions!"
# State Output
{
"comment": "Hello, Step Functions!",
"details": "Default example",
"who" : "Step Functions"
}
```
## 使用 ResultPath 在 中同時包含錯誤和輸入 `Catch`
在某些情況下，您可能想要保留原始輸入的錯誤。在 `Catch` 中使用 `ResultPath` 以包含錯誤與原始輸入，而不是將其取代。
```
"Catch": [{
"ErrorEquals": ["States.ALL"],
"Next": "NextTask",
"ResultPath": "$.error"
}]
```
如果之前的 `Catch` 陳述式截獲錯誤，它會在狀態輸入內的 `error` 節點包含結果。例如，透過以下輸入：
```
{"foo": "bar"}
```
在截獲錯誤時的狀態輸出如下。
```
{
"foo": "bar",
"error": {
"Error": "Error here"
}
}
```
如需錯誤處理的詳細資訊，請參閱以下內容：
+ [處理 Step Functions 工作流程中的錯誤](concepts-error-handling.md)
+ [在 Step Functions 狀態機器中處理錯誤條件](tutorial-handling-error-conditions.md)
# Step Functions 中的映射狀態輸入和輸出欄位
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
映射狀態會逐一查看資料集中的項目集合。資料集的範例包括：
+ 來自先前狀態的 JSON 陣列和物件。
+ 存放在 Amazon S3 中的個別資料檔案，格式如下：JSON、JSONL、CSV、Parquet 檔案。
+ 對多個物件的參考，例如：Athena 資訊清單和 Amazon S3 清查檔案
映射會針對資料集中的每個項目重複一組步驟。您可以使用各種組態選項來設定 `Map state` 接收的輸入和映射產生的輸出。Step Functions 會依照下列清單所示的順序，在您的*分散式映射狀態下*套用每個選項。根據您的使用案例，您可能不需要套用所有欄位。
1. [ItemReader （地圖）](input-output-itemreader.md) - 用來讀取您的資料項目
1. [ItemsPath （地圖，僅限 JSONPath)](input-output-itemspath.md) 或 **項目 (JSONata)** - 選用；用於在資料集中指定項目
1. [ItemSelector （地圖）](input-output-itemselector.md) - 選用；用於選取和修改資料集中的項目
1. [ItemBatcher （地圖）](input-output-itembatcher.md) - 用於在處理大型項目集時處理項目群組
1. [ResultWriter （地圖）](input-output-resultwriter.md) - 為子工作流程的輸出結果提供選項
# ItemReader （地圖）
`ItemReader` 欄位是 JSON 物件，可指定資料集及其位置。*分散式映射狀態*會使用此資料集做為其輸入。
下列範例顯示 **JSONPath 型**工作流程中`ItemReader`欄位的語法，適用於存放在 Amazon S3 儲存貯體的文字分隔檔案中的資料集。
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csvDataset/ratings.csv",
"VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
}
}
```
在下列以 **JSONata 為基礎的**工作流程中，請注意 `Parameters` 會取代為**引數**。
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW"
},
"Resource": "arn:aws:states:::s3:getObject",
"Arguments": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csvDataset/ratings.csv"
"VersionId": "BcK42coT2jE1234VHLUvBV1yLNod2OEt"
}
}
```
## ItemReader 欄位的內容
根據您的資料集， `ItemReader` 欄位的內容會有所不同。例如，如果您的資料集是從工作流程中上一個步驟傳遞的 JSON 陣列，則會省略 `ItemReader` 欄位。如果您的資料集是 Amazon S3 資料來源，此欄位會包含下列子欄位。
**`Resource`**
Step Functions 將使用的 Amazon S3 API 整合動作，例如 `arn:aws:states:::s3:getObject`
**`Arguments (JSONata) or Parameters (JSONPath)`**
JSON 物件，指定存放資料集的 Amazon S3 儲存貯體名稱和物件金鑰。
如果儲存貯體已啟用版本控制，您也可以提供 Amazon S3 物件版本。
**`ReaderConfig`**
指定下列詳細資訊的 JSON 物件：
+ `InputType`
接受下列其中一個值：`CSV`、`JSON`、`JSONL`、`PARQUET`、`MANIFEST`。
指定 Amazon S3 資料來源的類型，例如以文字分隔的檔案 (`CSV`)、物件、JSON 檔案、JSON Lines、Parquet 檔案、Athena 資訊清單或 Amazon S3 清查清單。在 Workflow Studio 中，您可以從 **S3 項目來源**選取輸入類型。
大多數使用`S3GetObject`擷取的輸入類型也在其參數中支援 `ExpectedBucketOwner`和 `VersionId` 欄位。Parquet 檔案是不支援 的例外狀況`VersionId`。
輸入檔案支援下列外部壓縮類型：GZIP、ZSTD。
範例檔案名稱： `myObject.jsonl.gz`和 `myObject.csv.zstd`。
注意：Parquet 檔案是內部壓縮的二進位檔案類型。支援 GZIP、ZSTD 和 Snappy 壓縮。
+ `Transformation`
「選用」**。值將為 或 `NONE`或 `LOAD_AND_FLATTEN`。
如果未指定，`NONE`則會假設 。設定為 時`LOAD_AND_FLATTEN`，您還必須設定 `InputType`。
預設行為，映射會逐一查看從呼叫 傳回的**中繼資料物件**`S3:ListObjectsV2`。設定為 時`LOAD_AND_FLATTEN`，映射會讀取並處理結果清單中參考的實際**資料物件**。
+ `ManifestType`
「選用」**。值將為 或 `ATHENA_DATA`或 `S3_INVENTORY`。
注意：如果設定為 `S3_INVENTORY`，您也**不能**指定 ，`InputType`因為類型假設為 `CSV`。
+ `CSVDelimiter`
當 `InputType`為 `CSV`或 時，您可以指定此欄位`MANIFEST`。
接受下列其中一個值： `COMMA`（預設）`PIPE`、`SEMICOLON`、、`SPACE`、`TAB`。
**注意**
使用 `CSVDelimiter` 欄位， `ItemReader`可以處理以逗號以外的字元分隔的檔案。參考「CSV 檔案」也包含使用 `CSVDelimiter` 欄位指定之替代分隔符號的檔案。
+ `CSVHeaderLocation`
當 `InputType`為 `CSV`或 時，您可以指定此欄位`MANIFEST`。
接受下列其中一個值來指定資料欄標頭的位置：
+ `FIRST_ROW` – 如果檔案的第一行是 標頭，請使用此選項。
+ `GIVEN` – 使用此選項在狀態機器定義中指定 標頭。
例如，如果您的檔案包含下列資料。
```
1,307,3.5,1256677221
1,481,3.5,1256677456
1,1091,1.5,1256677471
...
```
您可以提供下列 JSON 陣列做為 CSV 標頭：
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "GIVEN",
"CSVHeaders": [
"userId",
"movieId",
"rating",
"timestamp"
]
}
}
```
**CSV 標頭大小**
Step Functions 針對以文字分隔的檔案支援高達 10 KiB 的標頭。
+ `ItemsPointer`
「選用」**。當 `InputType`為 時，您可以指定此欄位`JSON`。
`ItemsPointer` 使用 JSONPointer 語法來選取 JSON 檔案中巢狀的特定陣列或物件。JSONPointer 是一種標準化語法，專門用於導覽和參考 JSON 文件中的位置。
JSONPointer 語法使用正斜線 (/) 來分隔每個巢狀層級，陣列索引表示為不含括號的數字。例如：
+ `/Data/Contents` - 參考資料物件中的內容陣列
+ `/Data/Contents/0` - 參考內容陣列的第一個元素
目標陣列的起始位置必須在 JSON 檔案的前 16MB 內，而且 JSONPointer 路徑長度必須少於 2000 個字元。
例如，如果您的 JSON 檔案包含：
```
{"data": {"items": [{"id": 1}, {"id": 2}]}}
```
您可以指定 `"ItemsPointer": "/data/items"`來處理項目陣列。
+ `MaxItems`
根據預設，`Map`狀態會反覆查看指定資料集中的所有項目。透過設定 `MaxItems`，您可以限制傳遞至 `Map` 狀態的資料項目數量。例如，如果您提供包含 1，000 個資料列的文字分隔檔案，且您設定限制為 100，則解譯器*只會*將 100 個資料列傳遞至*分散式地圖狀態*。`Map` 狀態會依序處理項目，從標頭列開始。
對於 **JSONPath** 工作流程，您可以在解析為整數的狀態輸入中使用 `MaxItemsPath`和索引鍵/值對的*參考路徑*。請注意，您可以指定 `MaxItems`或 `MaxItemsPath`，但不能同時指定**兩者**。
**注意**
您可以指定最多 100，000，000 個的限制，之後 會`Distributed Map`停止讀取項目。
**帳戶和區域的需求**
您的 Amazon S3 儲存貯體必須與狀態機器位於相同的 AWS 帳戶 和 AWS 區域 。
請注意，即使您的狀態機器可以跨相同 中的不同 存取儲存貯 AWS 帳戶 體中的檔案 AWS 區域，Step Functions 僅支援在*與* AWS 區域 狀態機器相同 AWS 帳戶 和相同的 Amazon S3 儲存貯體中列出物件。
## 處理巢狀資料集 (2025 年 9 月 11 日更新）
使用新`Transformation`參數，您可以指定 的值，`LOAD_AND_FLATTEN`而且映射會從呼叫 的結果清單中讀取參考**的實際**資料物件`S3:ListObjectsV2`。
在此版本之前，您需要建立巢狀分散式地圖來**擷取**中繼資料，然後**處理**實際資料。第一個映射會逐一查看 傳回的**中繼資料**`S3:ListObjectsV2`，並叫用子工作流程。每個子狀態機器中的另一個映射會從個別檔案讀取**實際資料**。使用轉換選項，您可以一次完成這兩個步驟。
假設您想要對系統每小時產生的過去 24 個日誌檔案執行每日稽核，並存放在 Amazon S3 中。您的分散式映射狀態可以使用 列出日誌檔案`S3:ListObjectsV2`，然後逐一查看每個物件的*中繼資料*，或者它現在可以載入和分析存放在 Amazon S3 儲存貯體中的**實際資料**物件。
使用 `LOAD_AND_FLATTEN`選項可以提高可擴展性、減少開放的 Map Run 計數，以及同時處理多個物件。Athena 和 Amazon EMR 任務通常會產生可使用新組態處理的輸出。
以下是 `ItemReader`定義中參數的範例：
```
{
"QueryLanguage": "JSONata",
"States": {
...
"Map": {
...
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"ReaderConfig": {
// InputType is required if Transformation is LOAD_AND_FLATTEN.
"InputType": "CSV | JSON | JSONL | PARQUET",
// Transformation is OPTIONAL and defaults to NONE if not present
"Transformation": "NONE | LOAD_AND_FLATTEN"
},
"Arguments": {
"Bucket": "amzn-s3-demo-bucket1",
"Prefix": "{% $states.input.PrefixKey %}"
}
},
...
}
}
```
## 資料集的範例
您可以指定下列其中一個選項做為資料集：
+ [上一個步驟的 JSON 資料](#itemsource-json-array)
+ [Amazon S3 物件的清單](#itemsource-example-s3-object-data)
+ [由 LOAD\$1AND\$1FLATTEN 轉換的 Amazon S3 物件](#itemsource-example-s3-object-data-flatten)
+ [Amazon S3 儲存貯體中的 JSON 檔案](#itemsource-example-json-data)
+ [Amazon S3 儲存貯體中的 JSON Lines 檔案](#itemsource-example-json-lines-data)
+ [Amazon S3 儲存貯體中的 CSV 檔案](#itemsource-example-csv-data)
+ [Amazon S3 儲存貯體中的 Parquet 檔案](#itemsource-example-parquet-data)
+ [Athena 資訊清單 （處理多個項目）](#itemsource-example-athena-manifest-data)
+ [Amazon S3 清查 （處理多個項目）](#itemsource-example-s3-inventory)
**注意**
Step Functions 需要適當的許可才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。
### 上一個步驟的 JSON 資料
*分散式映射狀態*可以接受從工作流程中上一個步驟傳遞的 JSON 輸入。
輸入可以是 JSON 陣列、JSON 物件或 JSON 物件節點內的陣列。
Step Functions 會直接反覆運算陣列的元素，或 JSON 物件的鍵值對。
若要從輸入中選取包含巢狀 JSON 陣列或物件的特定節點，您可以使用 `ItemsPath （地圖，僅限 JSONPath)`，或在 JSONata 狀態的 `Items` 欄位中使用 JSONata 表達式。
若要處理個別項目，*分散式映射狀態*會為每個項目啟動子工作流程執行。下列索引標籤顯示傳遞至 `Map` 狀態的輸入範例，以及傳遞至子工作流程執行的對應輸入。
**注意**
當您的資料集是上一個步驟的 JSON 資料時，則不需要 `ItemReader` 欄位。
------
#### [ Input passed to the Map state ]
請考慮以下三個項目的 JSON 陣列。
```
"facts": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "mostly-true",
"statement_date": "5/18/2016",
"statement_source": "news"
}
]
```
------
#### [ Input passed to a child workflow execution ]
*分散式映射狀態*會啟動三個子工作流程執行。每個執行都會收到陣列項目做為輸入。下列範例顯示子工作流程執行收到的輸入。
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Amazon S3 物件的清單
*分散式映射狀態*可以反覆查看存放在 Amazon S3 儲存貯體中的物件。當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) API 動作，這會傳回 Amazon S3 **物件中繼資料**的陣列。在此陣列中，每個項目都包含儲存貯體中實際資料的資料，例如 **ETag** 和 **Key**。
若要處理陣列中的個別項目，*分散式映射狀態*會啟動子工作流程執行。例如，假設您的 Amazon S3 儲存貯體包含 100 個映像。然後，調用 `ListObjectsV2` API 動作後傳回的陣列包含 100 個中繼資料項目。*然後，分散式映射狀態*會啟動 100 個子工作流程執行來處理每個項目。
若要在沒有巢狀工作流程的情況下直接處理資料物件，您可以選擇 LOAD\$1AND\$1FLATTEN 轉換選項，以**直接**處理項目。
**注意**
Step Functions 也會包含使用 Amazon S3 **主控台**在 Amazon S3 儲存貯體中建立的每個**資料夾**的項目。資料夾項目會導致啟動額外的子工作流程執行。
為了避免為每個資料夾建立額外的子工作流程執行，建議您使用 AWS CLI 來建立資料夾。如需詳細資訊，請參閱*AWS Command Line Interface 《 使用者指南*》中的[高階 Amazon S3 命令](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-s3-commands.html#using-s3-commands-managing-buckets-creating)。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。
下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。
------
#### [ ItemReader syntax ]
在此範例中，您已在名為 的 Amazon S3 儲存貯體`processData`中名為 的字首內整理資料，其中包含影像、JSON 檔案和物件`amzn-s3-demo-bucket`。
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Prefix": "processData"
}
}
```
------
#### [ Input passed to a child workflow execution ]
*分散式映射狀態*啟動的子工作流程執行數量與 Amazon S3 儲存貯體中存在的中繼資料項目數量相同。下列範例顯示子工作流程執行收到的輸入。
```
{
"Etag": "\"05704fbdccb224cb01c59005bebbad28\"",
"Key": "processData/images/n02085620_1073.jpg",
"LastModified": 1668699881,
"Size": 34910,
"StorageClass": "STANDARD"
}
```
------
### 由 轉換的 Amazon S3 物件 `LOAD_AND_FLATTEN`
透過增強對 S3 ListObjectsV2 的支援作為分散式地圖中的輸入來源，您的狀態機器可以直接從 Amazon S3 儲存貯體讀取和處理多個**資料物件**，無需巢狀地圖來處理中繼資料！
使用 `LOAD_AND_FLATTEN`選項，您的狀態機器會執行下列動作：
+ 讀取 Amazon S3 `ListObjectsV2`呼叫列出的每個物件**的實際內容**。
+ 根據 InputType (CSV、JSON、JSONL、Parquet) 剖析內容。
+ 從檔案內容 （資料列/記錄） 而非中繼資料建立項目。
使用轉換選項，您不再需要巢狀分散式地圖來處理中繼資料。使用 LOAD\$1AND\$1FLATTEN 選項可提高可擴展性、減少作用中的映射執行計數，並同時處理多個物件。
下列組態顯示 的設定`ItemReader`：
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:listObjectsV2",
"ReaderConfig": {
"InputType": "JSON",
"Transformation": "LOAD_AND_FLATTEN"
},
"Arguments": {
"Bucket": "S3_BUCKET_NAME",
"Prefix": "S3_BUCKET_PREFIX"
}
}
```
**儲存貯體字首建議**
我們建議您在字首上包含結尾斜線。例如，如果您選取字首為 的資料`folder1`，您的狀態機器將同時處理 `folder1/myData.csv`和 `folder10/myData.csv`。使用 `folder1/` 只會嚴格處理一個資料夾。
### Amazon S3 儲存貯體中的 JSON 檔案
*分散式映射狀態*可以接受存放在 Amazon S3 儲存貯體中的 JSON 檔案做為資料集。JSON 檔案必須包含陣列或 JSON 物件。
當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作來擷取指定的 JSON 檔案。
如果 JSON 檔案包含巢狀物件結構，您可以使用 來選取具有資料集的特定節點`ItemsPointer`。例如，下列組態會擷取*庫存*中*特色產品的*巢狀清單。
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "JSON",
"ItemsPointer": "/inventory/products/featured"
},
"Arguments": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "nested-data-file.json"
}
}
```
接著`Map`狀態會反覆查看陣列中的每個項目，並為每個項目啟動子工作流程執行。例如，如果您的 JSON 檔案包含 1000 個陣列項目，`Map`狀態會啟動 1000 個子工作流程執行。
**注意**
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過，如果您接著套用選用`ItemSelector`欄位來減少項目的大小，Step Functions 支援從文字分隔檔案、JSON 或 JSON Lines 檔案讀取最多 8 MB 的項目。
Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。
下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。
在此範例中，假設您有一個名為 的 JSON 檔案`factcheck.json`。您已將此檔案存放在 Amazon S3 儲存貯體`jsonDataset`中名為 的字首中。以下是 JSON 資料集的範例。
```
[
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "mostly-true",
"statement_date": "5/18/2016",
"statement_source": "news"
},
...
]
```
------
#### [ ItemReader syntax ]
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "JSON"
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "jsonDataset/factcheck.json"
}
}
```
------
#### [ Input to a child workflow execution ]
*分散式映射狀態*啟動的子工作流程執行數量與 JSON 檔案中存在的陣列項目數量相同。下列範例顯示子工作流程執行收到的輸入。
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Amazon S3 儲存貯體中的 JSON Lines 檔案
*分散式映射狀態*可以接受存放在 Amazon S3 儲存貯體中的 JSON Lines 檔案做為資料集。
**注意**
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過，如果您接著套用選用`ItemSelector`欄位來減少項目的大小，Step Functions 支援從文字分隔檔案、JSON 或 JSON Lines 檔案讀取最多 8 MB 的項目。
Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。
下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。
在此範例中，假設您有一個名為 的 JSON Lines 檔案`factcheck.jsonl`。您已將此檔案存放在 Amazon S3 儲存貯`jsonlDataset`體中名為 的字首中。以下是檔案內容的範例。
```
{"verdict": "true", "statement_date": "6/11/2008", "statement_source": "speech"}
{"verdict": "false", "statement_date": "6/7/2022", "statement_source": "television"}
{"verdict": "mostly-true", "statement_date": "5/18/2016", "statement_source": "news"}
```
------
#### [ ItemReader syntax ]
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "JSONL"
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "jsonlDataset/factcheck.jsonl"
}
}
```
------
#### [ Input to a child workflow execution ]
*分散式映射狀態*會啟動與 JSONL 檔案中存在的行數一樣多的子工作流程執行。下列範例顯示子工作流程執行收到的輸入。
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
------
### Amazon S3 儲存貯體中的 CSV 檔案
**注意**
使用 `CSVDelimiter` 欄位， `ItemReader`可以處理以逗號以外的字元分隔的檔案。參考「CSV 檔案」也包含使用 `CSVDelimiter` 欄位指定之替代分隔符號的檔案。
*分散式映射狀態*可以接受以文字分隔的檔案，該檔案存放在 Amazon S3 儲存貯體中做為資料集。如果您使用以文字分隔的檔案做為資料集，則需要指定資料欄標頭。如需如何指定標頭的資訊，請參閱 [ItemReader 欄位的內容](#itemreader-field-contents)。
Step Functions 會根據下列規則剖析以文字分隔的檔案：
+ 分隔欄位的分隔符號由 *ReaderConfig* `CSVDelimiter`中的 指定。分隔符號預設為 `COMMA`。
+ Newlines 是分隔**記錄**的分隔符號。
+ 欄位視為字串。對於資料類型轉換，請使用 中的`States.StringToJson`內部 函數[ItemSelector （地圖）](input-output-itemselector.md)。
+ 不需要雙引號 (" ") 來括住字串。不過，以雙引號括住的字串可包含逗號和換行，而不做為記錄分隔符號。
+ 您可以重複雙引號來保留雙引號。
+ 反斜線 (\$1) 是逸出特殊字元的另一種方式。反斜線僅適用於其他反斜線、雙引號和設定的欄位分隔符號，例如逗號或縱線。反斜線後面接著任何其他字元會被無提示移除。
+ 您可以重複斜線來保留斜線。例如：
```
path,size
C:\\Program Files\\MyApp.exe,6534512
```
+ 逸出雙引號的反斜線 (`\"`) 只有在包含在組內時才有效，因此我們建議重複逸出雙引號：`""`。
+ 如果資料列中的欄位數目**小於** 標頭中的欄位數目，Step Functions 會提供缺少值**的空字串**。
+ 如果資料列中的欄位數目**超過**標頭中的欄位數目，Step Functions **會略過**其他欄位。
如需 Step Functions 如何剖析以文字分隔檔案的詳細資訊，請參閱 [Example of parsing an input CSV file](example-csv-parse-dist-map.md#example-csv-parse)。
當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作來擷取指定的檔案。接著`Map`狀態會逐一查看 檔案中的每一列，並啟動子工作流程執行，以處理每一列中的項目。例如，假設您提供以文字分隔的檔案，其中包含 100 列做為輸入。然後，解譯器會將每一列傳遞至 `Map` 狀態。`Map` 狀態會以序列順序處理項目，從標頭列開始。
**注意**
用來啟動子工作流程執行的執行輸入不能超過 256 KiB。不過，如果您接著套用選用`ItemSelector`欄位來減少項目的大小，Step Functions 支援從文字分隔檔案、JSON 或 JSON Lines 檔案讀取最多 8 MB 的項目。
Step Functions 支援 10 GB 作為 Amazon S3 中個別檔案的大小上限。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。
下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。
------
#### [ ItemReader syntax ]
例如，假設您有一個名為 的 CSV 檔案`ratings.csv`。然後，您已將此檔案存放在 Amazon S3 儲存貯體`csvDataset`中名為 的字首中。
```
"ItemReader": {
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "FIRST_ROW",
"CSVDelimiter": "PIPE"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "csvDataset/ratings.csv"
}
}
```
------
#### [ Input to a child workflow execution ]
*分散式映射狀態*啟動的子工作流程執行數目與 CSV 檔案中存在的資料列數目相同，如果在檔案中，則不含標頭列。下列範例顯示子工作流程執行收到的輸入。
```
{
"rating": "3.5",
"movieId": "307",
"userId": "1",
"timestamp": "1256677221"
}
```
------
### Amazon S3 儲存貯體中的 Parquet 檔案
Parquet 檔案可以用作輸入來源。存放在 Amazon S3 中的 Apache Parquet 檔案可大規模提供高效率的單欄式資料處理。
使用 Parquet 檔案時，適用下列條件：
+ 256MB 是資料列群組大小上限，而 5MB 是頁尾大小上限。如果您提供的輸入檔案超過任一限制，狀態機器將傳回執行時間錯誤。
+ **不支援** `VersionId` 欄位`InputType=Parquet`。
+ 原生支援內部 GZIP、ZSTD 和 Snappy 資料壓縮。不需要副檔名。
以下顯示 `InputType` 設定為 Parquet 的範例 ASL 組態：
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "PARQUET"
},
"Arguments": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "my-parquet-data-file-1.parquet"
}
}
```
**大規模任務處理**
對於非常大規模的任務，Step Functions 將使用許多輸入讀取器。讀者交錯處理，這可能會導致某些讀者暫停，而其他讀者則進行。間歇性進度是大規模的預期行為。
### Athena 資訊清單 （處理多個項目）
您可以使用從`UNLOAD`查詢結果產生的 Athena 資訊清單檔案，來指定映射狀態的資料檔案**來源**。您可以將 `ManifestType`設定為 `ATHENA_DATA`，並將 `InputType`設定為 `CSV`、 `JSONL`或 `Parquet`。
執行`UNLOAD`查詢時，除了實際的資料物件之外，Athena 還會產生資料資訊清單檔案。資訊清單檔案提供資料檔案的結構化 CSV 清單。資訊清單和資料檔案都會儲存至 Amazon S3 中的 Athena 查詢結果位置。
```
UNLOAD () TO 'S3_URI_FOR_STORING_DATA_OBJECT' WITH (format = 'JSON')
```
程序的概念概觀，簡要來說：
1. 使用 Athena 中的`UNLOAD`查詢從資料表中選取您的資料。
1. Athena 會在 Amazon S3 中產生資訊清單檔案 (CSV) 和資料物件。
1. 設定 Step Functions 以讀取資訊清單檔案並處理輸入。
此功能可以處理來自 Athena 的 CSV、JSONL 和 Parquet 輸出格式。單一資訊清單檔案中參考的所有物件都必須是相同的 InputType 格式。請注意，`UNLOAD`查詢匯出的 CSV 物件**不包含**第一行中的標頭。了解`CSVHeaderLocation`您是否需要提供資料欄標頭。
地圖內容也會包含 `$states.context.Map.Item.Source`，讓您可以根據資料來源自訂處理。
以下是`ItemReader`設定為使用 Athena 資訊清單之 的範例組態：
```
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"ManifestType": "ATHENA_DATA",
"InputType": "CSV | JSONL | PARQUET"
},
"Arguments": {
"Bucket": "",
"Key": "-manifest.csv"
}
}
```
**在 Workflow Studio 中使用 Athena 資訊清單模式**
資料處理的常見案例會將映射套用至來自 Athena UNLOAD 查詢的資料來源。映射會叫用 Lambda 函數來處理 Athena 資訊清單中描述的每個項目。Step Functions Workflow Studio 提供現成模式，將所有這些元件結合成封鎖您拖曳到狀態機器畫布上。
### S3 清查 （處理多個項目）
*分散式映射狀態*可以接受存放在 Amazon S3 儲存貯體中的 Amazon S3 清查清單檔案做為資料集。
當工作流程執行達到 `Map` 狀態時，Step Functions 會叫用 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作來擷取指定的 Amazon S3 清查清單檔案。
根據預設，`Map`狀態接著會反覆查看清查中的**物件**，以傳回 Amazon S3 清查物件中繼資料的陣列。
如果您指定 ManifestType 為 S3\$1INVENTORY，則無法指定 InputType。
**注意**
Step Functions 支援 10 GB 做為解壓縮後 Amazon S3 清查報告中個別檔案的大小上限。不過，如果每個檔案小於 10 GB，Step Functions 可以處理超過 10 GB。
Step Functions 需要適當的許可，才能存取您使用的 Amazon S3 資料集。如需資料集的 IAM 政策相關資訊，請參閱 [資料集的 IAM 政策建議](#itemreader-iam-policies)。
以下是 CSV 格式的庫存檔案範例。此檔案包含名為 `csvDataset`和 的物件`imageDataset`，這些物件存放在名為 的 Amazon S3 儲存貯體中`amzn-s3-demo-source-bucket`。
```
"amzn-s3-demo-source-bucket","csvDataset/","0","2022-11-16T00:27:19.000Z"
"amzn-s3-demo-source-bucket","csvDataset/titles.csv","3399671","2022-11-16T00:29:32.000Z"
"amzn-s3-demo-source-bucket","imageDataset/","0","2022-11-15T20:00:44.000Z"
"amzn-s3-demo-source-bucket","imageDataset/n02085620_10074.jpg","27034","2022-11-15T20:02:16.000Z"
...
```
**重要**
Step Functions 不支援使用者定義的 Amazon S3 清查報告做為資料集。
Amazon S3 清查報告的輸出格式必須為 CSV。
如需 Amazon S3 清查以及如何設定它們的詳細資訊，請參閱 [Amazon S3 清查](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-inventory.html)。
下列 Amazon S3 清查資訊清單檔案範例顯示清查物件中繼資料的 CSV 標頭。
```
{
"sourceBucket" : "amzn-s3-demo-source-bucket",
"destinationBucket" : "arn:aws:s3:::amzn-s3-demo-inventory",
"version" : "2016-11-30",
"creationTimestamp" : "1668560400000",
"fileFormat" : "CSV",
"fileSchema" : "Bucket, Key, Size, LastModifiedDate",
"files" : [ {
"key" : "amzn-s3-demo-bucket/destination-prefix/data/20e55de8-9c21-45d4-99b9-46c732000228.csv.gz",
"size" : 7300,
"MD5checksum" : "a7ff4a1d4164c3cd55851055ec8f6b20"
} ]
}
```
下列索引標籤顯示 `ItemReader` 欄位語法的範例，以及傳遞給此資料集子工作流程執行的輸入。
------
#### [ ItemReader syntax ]
```
"ItemReader": {
"ReaderConfig": {
"InputType": "MANIFEST"
},
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Key": "destination-prefix/amzn-s3-demo-bucket/config-id/YYYY-MM-DDTHH-MMZ/manifest.json"
}
}
```
------
#### [ Input to a child workflow execution ]
```
{
"LastModifiedDate": "2022-11-16T00:29:32.000Z",
"Bucket": "amzn-s3-demo-source-bucket",
"Size": "3399671",
"Key": "csvDataset/titles.csv"
}
```
根據您在設定 Amazon S3 清查報告時選取的欄位，`manifest.json`檔案的內容可能與範例不同。
------
## 資料集的 IAM 政策建議
當您使用 Step Functions 主控台建立工作流程時，Step Functions 可以根據您工作流程定義中的資源自動產生 IAM 政策。產生的政策包含允許狀態機器角色叫用*分散式映射狀態*的 `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API 動作和存取 AWS 資源所需的最低權限，例如 Amazon S3 儲存貯體和物件，以及 Lambda 函數。
我們建議您在 IAM 政策中只包含必要的許可。例如，如果您的工作流程包含分散式模式中`Map`的狀態，請將您的政策範圍縮小到包含您的資料的特定 Amazon S3 儲存貯體和資料夾。
**重要**
如果您指定 Amazon S3 儲存貯體和物件或字首，並在*分散式映射狀態*輸入中具有現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，請務必更新工作流程的 IAM 政策。將政策範圍縮小至路徑在執行時間解析的儲存貯體和物件名稱。
下列範例顯示使用 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) 和 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 動作授予存取 Amazon S3 資料集所需最低權限的技術。
**Example 使用 Amazon S3 物件做為資料集的條件**
下列條件授予存取 Amazon S3 儲存貯體`processImages`資料夾中物件的最低權限。
```
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ],
"Condition": {
"StringLike": {
"s3:prefix": [ "processImages" ]
}
}
```
**Example 使用 CSV 檔案做為資料集**
下列範例顯示存取名為 的 CSV 檔案所需的動作`ratings.csv`。
```
"Action": [ "s3:GetObject" ],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/csvDataset/ratings.csv"
]
```
**Example 使用 Amazon S3 清查做為資料集**
以下顯示 Amazon S3 清查清單檔案和資料檔案的範例資源。
```
"Resource": [
"arn:aws:s3:::myPrefix/amzn-s3-demo-bucket/myConfig-id/YYYY-MM-DDTHH-MMZ/manifest.json",
"arn:aws:s3:::myPrefix/amzn-s3-demo-bucket/myConfig-id/data/*"
]
```
**Example 使用 ListObjectsV2 限制為資料夾字首**
使用 [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) 時，會產生兩個政策。需要一個允許**列出**儲存貯體 (`ListBucket`) 的內容，另一個政策將允許**擷取儲存貯體 () 中的物件**`GetObject`。
以下顯示動作、資源和條件的範例：
```
"Action": [ "s3:ListBucket" ],
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket" ],
"Condition": {
"StringLike": {
"s3:prefix": [ "/path/to/your/json/" ]
}
}
```
```
"Action": [ "s3:GetObject" ],
"Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket/path/to/your/json/*" ]
```
請注意， `GetObject`不會設定範圍，而您將針對物件使用萬用字元 (`*`)。
# ItemsPath （地圖，僅限 JSONPath)
**管理狀態和轉換資料**
此頁面是指 JSONPath。Step Functions 最近新增了變數和 JSONata 來管理狀態和轉換資料。
了解如何[使用變數傳遞資料](workflow-variables.md)，以及[使用 JSONata 轉換資料](transforming-data.md)。
在以 JSONPath 為基礎的狀態下，使用 `ItemsPath` 欄位在提供給 `Map` 狀態的 JSON 輸入內選取陣列或物件。根據預設，`Map`狀態會`ItemsPath`設定為 `$`，這會選取整個輸入。
+ 如果`Map`狀態的輸入是 JSON 陣列，它會針對陣列中的每個項目執行反覆運算，將該項目傳遞給反覆運算做為輸入
+ 如果`Map`狀態的輸入是 JSON 物件，它會針對物件中的每個鍵值對執行反覆運算，並將該對傳遞給反覆運算做為輸入
**注意**
只有在您使用從工作流程中先前狀態傳遞`ItemsPath`的 *JSON 輸入時，才能在分散式映射*狀態下使用 。
的值`ItemsPath`必須是[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，且該路徑必須評估為 JSON 陣列或物件。例如，請考慮包含兩個陣列的 `Map` 狀態輸入，如下列範例所示。
```
{
"ThingsPiratesSay": [
{
"say": "Avast!"
},
{
"say": "Yar!"
},
{
"say": "Walk the Plank!"
}
],
"ThingsGiantsSay": [
{
"say": "Fee!"
},
{
"say": "Fi!"
},
{
"say": "Fo!"
},
{
"say": "Fum!"
}
]
}
```
在此情況下，您可以使用 選取要用於`Map`狀態反覆運算的陣列`ItemsPath`。下列狀態機器定義會使用 指定輸入中的`ThingsPiratesSay`陣列`ItemsPath`。然後，它會針對`ThingsPiratesSay`陣列中的每個項目執行`SayWord`傳遞狀態的反覆運算。
```
{
"StartAt": "PiratesSay",
"States": {
"PiratesSay": {
"Type": "Map",
"ItemsPath": "$.ThingsPiratesSay",
"ItemProcessor": {
"StartAt": "SayWord",
"States": {
"SayWord": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
對於巢狀 JSON 物件，您可以使用 在輸入內`ItemsPath`選取特定物件。考慮以下具有巢狀組態資料的輸入：
```
{
"environment": "production",
"servers": {
"web": {
"server1": {"port": 80, "status": "active"},
"server2": {"port": 8080, "status": "inactive"}
},
"database": {
"primary": {"host": "db1.example.com", "port": 5432},
"replica": {"host": "db2.example.com", "port": 5432}
}
}
}
```
若要逐一查看 Web 伺服器物件，請將 `ItemsPath`設定為 `$.servers.web`：
```
{
"StartAt": "ProcessWebServers",
"States": {
"ProcessWebServers": {
"Type": "Map",
"ItemsPath": "$.servers.web",
"ItemProcessor": {
"StartAt": "CheckServer",
"States": {
"CheckServer": {
"Type": "Pass",
"End": true
}
}
},
"End": true
}
}
}
```
處理輸入時，`Map`狀態會在 `ItemsPath`之後套用[`InputPath`](input-output-inputpath-params.md#input-output-inputpath)。在`InputPath`篩選輸入之後，它會在狀態的有效輸入上操作。
如需 `Map` 狀態的詳細資訊，請參閱下列內容：
+ [對應狀態](state-map.md)
+ [映射狀態處理模式](state-map.md#concepts-map-process-modes)
+ [使用內嵌映射重複動作](tutorial-map-inline.md)
+ [內嵌`Map`狀態輸入和輸出處理](state-map-inline.md#inline-map-state-output)
# ItemSelector （地圖）
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
根據預設，`Map`狀態的有效輸入是原始狀態輸入中存在的一組個別資料項目。使用 `ItemSelector` 欄位，您可以在資料項目傳遞至 `Map` 狀態之前覆寫資料項目的值。
若要覆寫值，請指定包含鍵值對集合的有效 JSON 輸入。這些對可以是狀態機器定義中提供的靜態值、使用[路徑](amazon-states-language-paths.md)從狀態輸入中選取的值，或從[內容物件](input-output-contextobject.md)存取的值。
如果您使用路徑或內容物件指定鍵值對，則鍵名稱必須以 結尾`.$`。
**注意**
`ItemSelector` 欄位會取代 `Map` 狀態內的 `Parameters` 欄位。如果您使用`Map`狀態定義中的 `Parameters` 欄位來建立自訂輸入，建議您將其取代為 `ItemSelector`。
您可以同時指定*內嵌映射狀態*和*分散式映射狀態*`ItemSelector`的欄位。
例如，請考慮下列 JSON 輸入，其中包含`imageData`節點內三個項目的陣列。對於每個*`Map`狀態反覆運算*，陣列項目會做為輸入傳遞至反覆運算。
```
[
{
"resize": "true",
"format": "jpg"
},
{
"resize": "false",
"format": "png"
},
{
"resize": "true",
"format": "jpg"
}
]
```
使用 `ItemSelector` 欄位，您可以定義自訂 JSON 輸入來覆寫原始輸入，如下列範例所示。步驟函數接著會將此自訂輸入傳遞給每個*`Map`狀態反覆運算*。自訂輸入包含 的靜態值，`size`以及 `Map` 狀態的內容物件資料值。`$$.Map.Item.Value` 內容物件包含每個個別資料項目的值。
```
{
"ItemSelector": {
"size": 10,
"value.$": "$$.Map.Item.Value"
}
}
```
下列範例顯示內嵌*映射狀態*反覆運算收到的輸入：
```
{
"size": 10,
"value": {
"resize": "true",
"format": "jpg"
}
}
```
**提示**
如需使用 `ItemSelector` 欄位之*分散式映射狀態*的完整範例，請參閱 [使用分散式地圖複製大規模 CSV](tutorial-map-distributed.md)。
# ItemBatcher （地圖）
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`ItemBatcher` 欄位是 JSON 物件，指定 在單一子工作流程執行中處理一組項目。處理大型 CSV 檔案或 JSON 陣列或大型 Amazon S3 物件集時，請使用批次處理。
下列範例顯示 `ItemBatcher` 欄位的語法。在下列語法中，每個子工作流程執行應處理的項目數目上限設定為 100。
```
{
"ItemBatcher": {
"MaxItemsPerBatch": 100
}
}
```
根據預設，資料集中的每個項目都會做為輸入傳遞給個別子工作流程執行。例如，假設您將 JSON 檔案指定為包含下列陣列的輸入：
```
[
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
{
"verdict": "true",
"statement_date": "5/18/2016",
"statement_source": "news"
},
...
]
```
對於指定的輸入，每個子工作流程執行都會收到陣列項目做為其輸入。下列範例顯示子工作流程執行的輸入：
```
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
}
```
為了協助最佳化處理任務的效能和成本，請選取可平衡項目數量與項目處理時間的批次大小。如果您使用批次處理，Step Functions 會將項目新增至**項目**陣列。然後，它會將陣列做為輸入傳遞給每個子工作流程執行。下列範例顯示一批兩個項目，做為子工作流程執行的輸入傳遞：
```
{
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
}
]
}
```
**提示**
若要進一步了解如何在工作流程中使用 `ItemBatcher` 欄位，請嘗試下列教學課程和研討會：
[在 Lambda 函數中處理整批資料](tutorial-itembatcher-param-task.md)
[在子工作流程執行內反覆運算批次中的項目](tutorial-itembatcher-single-item-process.md)
* AWS Step Functions 研討會*中的[分散式地圖和相關資源](https://catalog.workshops.aws/stepfunctions/use-cases/distributed-map)
**Contents**
+ [指定項目批次處理的欄位](#input-output-itembatcher-subfields)
## 指定項目批次處理的欄位
若要批次項目，請指定要批次的項目數量上限、批次大小上限或兩者。您必須指定其中一個值來批次處理項目。
**每個批次的項目上限**
指定每個子工作流程執行處理的項目數量上限。解譯器會將`Items`陣列中批次處理的項目數量限制在此值。如果您同時指定批次號碼和大小，解譯器會減少批次中的項目數量，以避免超過指定的批次大小限制。
如果您未指定此值，但提供最大批次大小的值，Step Functions 會在每個子工作流程執行中處理盡可能多的項目，而不會超過最大批次大小，以位元組為單位。
例如，假設您使用包含 1130 個節點的輸入 JSON 檔案執行 。如果您為每個批次指定 100 個項目的值上限，Step Functions 會建立 12 個批次。其中，11 個批次各包含 100 個項目，而第 12 個批次則包含剩餘的 30 個項目。
或者，您可以指定每個批次的最大項目，做為*分散式映射狀態*輸入中現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。此路徑必須解析為正整數。
例如，假設有下列輸入：
```
{
"maxBatchItems": 500
}
```
您可以使用參考路徑 (**僅限 JSONPath**) 指定要批次處理的項目數量上限，如下所示：
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxItemsPerBatchPath": "$.maxBatchItems"
}
...
...
}
}
```
對於以 **JSONata 為基礎的**狀態，您也可以提供評估為正整數的 JSONata 表達式。
您可以指定 `MaxItemsPerBatch`或 `MaxItemsPerBatchPath (JSONPath only)`子欄位，但不能同時指定兩者。
**每個批次的最大 KiB **
指定批次的大小上限，以位元組為單位，最多 256 KiB。如果您同時指定最大批次數量和大小，Step Functions 會減少批次中的項目數量，以避免超過指定的批次大小限制。
或者，您可以指定最大批次大小，做為*分散式映射狀態*輸入中現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)。此路徑必須解析為正整數。
如果您使用批次處理且未指定最大批次大小，解譯器會在每個子工作流程執行中處理最多 256 KiB 的項目。
例如，假設有下列輸入：
```
{
"batchSize": 131072
}
```
您可以使用參考路徑指定批次大小上限，如下所示：
```
{
...
"Map": {
"Type": "Map",
"MaxConcurrency": 2000,
"ItemBatcher": {
"MaxInputBytesPerBatchPath": "$.batchSize"
}
...
...
}
}
```
對於以 **JSONata 為基礎的**狀態，您也可以提供評估為正整數的 JSONata 表達式。
您可以指定 `MaxInputBytesPerBatch`或 `MaxInputBytesPerBatchPath`（僅限 JSONPath) 子欄位，但不能同時指定兩者。
**批次輸入**
您也可以選擇性地指定固定的 JSON 輸入，包含在傳遞給每個子工作流程執行的每個批次中。Step Functions 會將此輸入與每個個別子工作流程執行的輸入合併。例如，假設下列項目陣列上事實檢查日期的固定輸入：
```
"ItemBatcher": {
"BatchInput": {
"factCheck": "December 2022"
}
}
```
每個子工作流程執行都會收到下列項目做為輸入：
```
{
"BatchInput": {
"factCheck": "December 2022"
},
"Items": [
{
"verdict": "true",
"statement_date": "6/11/2008",
"statement_source": "speech"
},
{
"verdict": "false",
"statement_date": "6/7/2022",
"statement_source": "television"
},
...
]
}
```
對於以 **JSONata 為基礎的**狀態，您可以將 JSONata 表達式直接提供給 BatchInput，或在 JSON 物件或陣列中使用 JSONata 表達式。
# ResultWriter （地圖）
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
`ResultWriter` 欄位是 JSON 物件，提供由分散式映射狀態啟動之子工作流程執行的輸出結果選項。如果您選擇匯出輸出結果，您可以為輸出結果指定不同的格式選項，以及 Amazon S3 位置來存放它們。Step Functions 預設不會匯出這些結果。
**Topics**
+ [ResultWriter 欄位的內容](#input-output-resultwriter-field-contents)
+ [範例](#input-output-resultwriter-examples)
+ [匯出至 Amazon S3](#input-output-resultwriter-exporting-to-S3)
+ [ResultWriter 的 IAM 政策](#resultwriter-iam-policies)
## ResultWriter 欄位的內容
`ResultWriter` 欄位包含下列子欄位。欄位的選擇會決定輸出的格式，以及輸出是否匯出至 Amazon S3。
**`ResultWriter`**
指定下列詳細資訊的 JSON 物件：
+ `Resource`
Step Functions 調用以匯出執行結果的 Amazon S3 API 動作。
+ `Parameters`
JSON 物件，指定存放執行輸出的 Amazon S3 儲存貯體名稱和字首。
+ `WriterConfig`
此欄位可讓您設定下列選項。
+ `Transformation`
+ `NONE` - 除了工作流程中繼資料之外， 還會傳回子工作流程執行的輸出不變。將子工作流程執行結果匯出至 Amazon S3 且未`WriterConfig`指定時為預設值。
+ `COMPACT` - 傳回子工作流程執行的輸出。`ResultWriter` 未指定 時的預設 。
+ `FLATTEN` - 傳回子工作流程執行的輸出。如果子工作流程執行傳回陣列，此選項會扁平化陣列，然後再將結果傳回狀態輸出或將結果寫入 Amazon S3 物件。
**注意**
如果子工作流程執行失敗，Step Functions 會傳回其執行結果不變。結果等同於將 `Transformation`設為 `NONE`。
+ `OutputType`
+ `JSON` - 將結果格式化為 JSON 陣列。
+ `JSONL` - 將結果格式化為 JSON Lines。
**必要欄位組合**
`ResultWriter` 欄位不能為空。您必須指定其中一組子欄位。
+ `WriterConfig` - 預覽格式化的輸出，而不將結果儲存至 Amazon S3。
+ `Resource` 和 `Parameters` - 將結果儲存至 Amazon S3，無需其他格式。
+ 所有三個欄位： `WriterConfig``Resource`和 `Parameters` - 以格式化輸出並將其儲存至 Amazon S3。
## 範例組態和轉換輸出
下列主題示範不同轉換選項中處理結果的可能組態設定`ResultWriter`和範例。
+ [ResultWriter 組態](#input-output-resultwriter-example-configurations)
+ [轉換](#input-output-resultwriter-example-transformations)
### ResultWriter 組態的範例
下列範例示範具有三個欄位可能組合的組態：`WriterConfig`、 `Resources`和 `Parameters`。
**僅限 *WriterConfig***
此範例會設定狀態輸出在預覽中呈現的方式，並在 `WriterConfig` 欄位中指定輸出格式和轉換。不存在`Resource`並提供 Amazon S3 儲存貯體規格`Parameters`的欄位，表示*狀態輸出*資源。結果會傳遞至下一個狀態。
```
"ResultWriter": {
"WriterConfig": {
"Transformation": "FLATTEN",
"OutputType": "JSON"
}
}
```
**僅限*資源*和*參數***
此範例會將狀態輸出匯出至指定的 Amazon S3 儲存貯體，而沒有不存在`WriterConfig`欄位指定的其他格式和轉換。
```
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
```
**所有三個欄位：*WriterConfig*、*資源*和*參數***
此範例會根據 `WriterConfig` 欄位中的規格格式化狀態輸出。它也會根據 `Resource`和 `Parameters`欄位中的規格，將其匯出至 Amazon S3 儲存貯體。
```
"ResultWriter": {
"WriterConfig": {
"Transformation": "FLATTEN",
"OutputType": "JSON"
},
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
```
### 轉換的範例
對於這些範例，假設每個子工作流程執行都會傳回輸出，這是物件陣列。
```
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
}
]
```
這些範例示範不同`Transformation`值的格式化輸出，使用 `OutputType`的 `JSON`。
**轉換 NONE**
這是您使用`NONE`轉換時已處理結果的範例。輸出保持不變，且包含工作流程中繼資料。
```
[
{
"ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:da4e9fc7-abab-3b27-9a77-a277e463b709",
"Input": ...,
"InputDetails": {
"Included": true
},
"Name": "da4e9fc7-abab-3b27-9a77-a277e463b709",
"Output": "[{\"customer_id\":\"145538\",\"order_id\":\"100000\"},{\"customer_id\":\"898037\",\"order_id\":\"100001\"}]",
"OutputDetails": {
"Included": true
},
"RedriveCount": 0,
"RedriveStatus": "NOT_REDRIVABLE",
"RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven",
"StartDate": "2025-02-04T01:49:50.099Z",
"StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders",
"Status": "SUCCEEDED",
"StopDate": "2025-02-04T01:49:50.163Z"
},
...
{
"ExecutionArn": "arn:aws:states:region:account-id:execution:orderProcessing/getOrders:f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a",
"Input": ...,
"InputDetails": {
"Included": true
},
"Name": "f43a56f7-d21e-3fe9-a40c-9b9b8d0adf5a",
"Output": "[{\"customer_id\":\"169881\",\"order_id\":\"100005\"},{\"customer_id\":\"797471\",\"order_id\":\"100006\"}]",
"OutputDetails": {
"Included": true
},
"RedriveCount": 0,
"RedriveStatus": "NOT_REDRIVABLE",
"RedriveStatusReason": "Execution is SUCCEEDED and cannot be redriven",
"StartDate": "2025-02-04T01:49:50.135Z",
"StateMachineArn": "arn:aws:states:region:account-id:stateMachine:orderProcessing/getOrders",
"Status": "SUCCEEDED",
"StopDate": "2025-02-04T01:49:50.227Z"
}
]
```
**轉換 COMPACT**
這是使用`COMPACT`轉換時已處理結果的範例。請注意，它是子工作流程執行與原始陣列結構的合併輸出。
```
[
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
}
],
...,
[
{
"customer_id": "169881",
"order_id": "100005"
},
{
"customer_id": "797471",
"order_id": "100006"
}
]
]
```
**轉換 FLATTEN**
這是您使用`FLATTEN`轉換時已處理結果的範例。請注意，它是將子工作流程執行陣列的組合輸出扁平化為一個陣列。
```
[
{
"customer_id": "145538",
"order_id": "100000"
},
{
"customer_id": "898037",
"order_id": "100001"
},
...
{
"customer_id": "169881",
"order_id": "100005"
},
{
"customer_id": "797471",
"order_id": "100006"
}
]
```
## 匯出至 Amazon S3
**重要**
請確定您用來匯出 Map Run 結果的 Amazon S3 儲存貯體與您的狀態機器位於相同 AWS 帳戶和 AWS 區域。否則，您的狀態機器執行會失敗並顯示`States.ResultWriterFailed`錯誤。
如果您的輸出承載大小超過 256 KiB，將結果匯出至 Amazon S3 儲存貯體會很有幫助。Step Functions 會合併所有子工作流程執行資料，例如執行輸入和輸出、ARN 和執行狀態。然後，它會將狀態相同的執行匯出至指定 Amazon S3 位置中的個別檔案。
以下範例使用 **JSONPath**，顯示 `ResultWriter` 欄位的語法`Parameters`與 匯出子工作流程執行結果。在此範例中，您將結果存放在名為 的儲存貯`amzn-s3-demo-destination-bucket`體中，前綴稱為 `csvProcessJobs`。
```
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
```
對於 **JSONata** 狀態， `Parameters`將取代為 `Arguments`。
```
{
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Arguments": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Prefix": "csvProcessJobs"
}
}
}
```
**提示**
在 Workflow Studio 中，您可以選取匯出**映射狀態結果至 Amazon S3，以匯出子工作流程執行結果**。然後，提供您要匯出結果的 Amazon S3 儲存貯體名稱和字首。
Step Functions 需要適當的許可，才能存取您要匯出結果的儲存貯體和資料夾。如需所需 IAM 政策的資訊，請參閱 [ResultWriter 的 IAM 政策](#resultwriter-iam-policies)。
如果您匯出子工作流程執行結果，*分散式映射狀態*執行會以下列格式傳回映射執行 ARN 和有關 Amazon S3 匯出位置的資料：
```
{
"MapRunArn": "arn:aws:states:us-east-2:account-id:mapRun:csvProcess/Map:ad9b5f27-090b-3ac6-9beb-243cd77144a7",
"ResultWriterDetails": {
"Bucket": "amzn-s3-demo-destination-bucket",
"Key": "csvProcessJobs/ad9b5f27-090b-3ac6-9beb-243cd77144a7/manifest.json"
}
}
```
Step Functions 會將狀態相同的執行匯出至各自的檔案。例如，如果子工作流程執行產生 500 個成功和 200 個失敗結果，Step Functions 會在指定的 Amazon S3 位置建立兩個檔案，以取得成功和失敗結果。在此範例中，成功結果檔案包含 500 個成功結果，而失敗結果檔案包含 200 個失敗結果。
對於指定的執行嘗試，Step Functions 會根據您的執行輸出，在指定的 Amazon S3 位置建立下列檔案：
+ `manifest.json` – 包含 Map Run 中繼資料，例如匯出位置、Map Run ARN，以及結果檔案的相關資訊。
如果您有 [redriven](redrive-map-run.md) Map Run， `manifest.json` 檔案會包含所有 Map Run 嘗試之所有成功子工作流程執行的參考。不過，此檔案包含對特定 的失敗和待定執行的參考redrive。
+ `SUCCEEDED_n.json` – 包含所有成功子工作流程執行的合併資料。*n* 代表檔案的索引號碼。索引號碼從 0 開始。例如 `SUCCEEDED_1.json`。
+ `FAILED_n.json` – 包含所有失敗、逾時和中止子工作流程執行的合併資料。使用此檔案從失敗的執行中復原。*n* 代表檔案的索引。索引號碼從 0 開始。例如 `FAILED_1.json`。
+ `PENDING_n.json` – 包含因映射執行失敗或中止而未啟動的所有子工作流程執行的合併資料。*n* 代表檔案的索引。索引號碼從 0 開始。例如 `PENDING_1.json`。
Step Functions 支援高達 5 GB 的個別結果檔案。如果檔案大小超過 5 GB，Step Functions 會建立另一個檔案來寫入剩餘的執行結果，並將索引號碼附加至檔案名稱。例如，如果`SUCCEEDED_0.json`檔案大小超過 5 GB，Step Functions 會建立`SUCCEEDED_1.json`檔案來記錄剩餘的結果。
如果您未指定 匯出子工作流程執行結果，狀態機器執行會傳回子工作流程執行結果的陣列，如下列範例所示：
```
[
{
"statusCode": 200,
"inputReceived": {
"show_id": "s1",
"release_year": "2020",
"rating": "PG-13",
"type": "Movie"
}
},
{
"statusCode": 200,
"inputReceived": {
"show_id": "s2",
"release_year": "2021",
"rating": "TV-MA",
"type": "TV Show"
}
},
...
]
```
**注意**
如果傳回的輸出大小超過 256 KiB，狀態機器執行會失敗並傳回`States.DataLimitExceeded`錯誤。
## ResultWriter 的 IAM 政策
當您使用 Step Functions 主控台建立工作流程時，Step Functions 可以根據您工作流程定義中的資源自動產生 IAM 政策。產生的政策包含允許狀態機器角色叫用*分散式映射狀態*的 `[StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)` API 動作和存取AWS資源所需的最低權限，例如 Amazon S3 儲存貯體和物件，以及 Lambda 函數。
我們建議您在 IAM 政策中只包含必要的許可。例如，如果您的工作流程包含分散式模式中`Map`的狀態，請將您的政策範圍縮小到包含您的資料的特定 Amazon S3 儲存貯體和資料夾。
**重要**
如果您指定 Amazon S3 儲存貯體和物件或字首，以及*分散式映射狀態*輸入中現有鍵值對的[參考路徑](amazon-states-language-paths.md#amazon-states-language-reference-paths)，請務必更新工作流程的 IAM 政策。將政策範圍縮小至路徑在執行時間解析的儲存貯體和物件名稱。
下列 IAM 政策範例會使用 `[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)` API 動作，授予將子工作流程執行結果寫入 Amazon S3 儲存貯體中名為 *csvJobs* 的資料夾所需的最低權限。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-destination-bucket/csvJobs/*"
]
}
]
}
```
如果您要寫入子工作流程執行結果的 Amazon S3 儲存貯體是使用 AWS Key Management Service(AWS KMS)金鑰加密的，您必須在 IAM 政策中包含必要的AWS KMS許可。如需詳細資訊，請參閱[AWS KMS key 加密 Amazon S3 儲存貯體的 IAM 許可](iam-policies-eg-dist-map.md#multiupload-dmap-result-policy)。
# Step Functions 如何剖析輸入 CSV 檔案
**管理狀態和轉換資料**
了解如何[使用變數在狀態與使用 JSONata 轉換資料之間傳遞資料](workflow-variables.md)。 [ JSONata](transforming-data.md)
Step Functions 會根據下列規則剖析以文字分隔的檔案：
+ 分隔欄位的分隔符號由 *ReaderConfig* `CSVDelimiter`中的 指定。分隔符號預設為 `COMMA`。
+ Newlines 是分隔**記錄**的分隔符號。
+ 欄位視為字串。對於資料類型轉換，請使用 中的`States.StringToJson`內部 函數[ItemSelector （地圖）](input-output-itemselector.md)。
+ 不需要雙引號 (" ") 來括住字串。不過，以雙引號括住的字串可包含逗號和換行，而不做為記錄分隔符號。
+ 您可以重複雙引號來保留雙引號。
+ 反斜線 (\$1) 是逸出特殊字元的另一種方式。反斜線僅適用於其他反斜線、雙引號和設定的欄位分隔符號，例如逗號或縱線。反斜線後面接著任何其他字元會被無提示移除。
+ 您可以重複斜線來保留斜線。例如：
```
path,size
C:\\Program Files\\MyApp.exe,6534512
```
+ 逸出雙引號的反斜線 (`\"`) 只有在包含在組內時才有效，因此我們建議重複逸出雙引號：`""`。
+ 如果資料列中的欄位數目**小於** 標頭中的欄位數目，Step Functions 會提供缺少值**的空字串**。
+ 如果資料列中的欄位數目**超過**標頭中的欄位數目，Step Functions **會略過**其他欄位。
**剖析輸入 CSV 檔案的範例**
假設您已提供名為 的 CSV 檔案`myCSVInput.csv`，其中包含一列做為輸入。然後，您已將此檔案存放在名為 的 Amazon S3 儲存貯體中`amzn-s3-demo-bucket`。CSV 檔案如下所示。
```
abc,123,"This string contains commas, a double quotation marks (""), and a newline (
)",{""MyKey"":""MyValue""},"[1,2,3]"
```
下列狀態機器會讀取此 CSV 檔案，並使用 [ItemSelector （地圖）](input-output-itemselector.md)來轉換部分欄位的資料類型。
```
{
"StartAt": "Map",
"States": {
"Map": {
"Type": "Map",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "STANDARD"
},
"StartAt": "Pass",
"States": {
"Pass": {
"Type": "Pass",
"End": true
}
}
},
"End": true,
"Label": "Map",
"MaxConcurrency": 1000,
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"ReaderConfig": {
"InputType": "CSV",
"CSVHeaderLocation": "GIVEN",
"CSVHeaders": [
"MyLetters",
"MyNumbers",
"MyString",
"MyObject",
"MyArray"
]
},
"Parameters": {
"Bucket": "amzn-s3-demo-bucket",
"Key": "myCSVInput.csv"
}
},
"ItemSelector": {
"MyLetters.$": "$$.Map.Item.Value.MyLetters",
"MyNumbers.$": "States.StringToJson($$.Map.Item.Value.MyNumbers)",
"MyString.$": "$$.Map.Item.Value.MyString",
"MyObject.$": "States.StringToJson($$.Map.Item.Value.MyObject)",
"MyArray.$": "States.StringToJson($$.Map.Item.Value.MyArray)"
}
}
}
}
```
當您執行此狀態機器時，會產生下列輸出。
```
[
{
"MyNumbers": 123,
"MyObject": {
"MyKey": "MyValue"
},
"MyString": "This string contains commas, a double quote (\"), and a newline (\n)",
"MyLetters": "abc",
"MyArray": [
1,
2,
3
]
}
]
```