本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 Step Functions 工作流程的內嵌模式中使用映射狀態
<a name="state-map-inline"></a>

**管理狀態和轉換資料**  
了解如何[使用變數在狀態與使用 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)

## 本主題中的關鍵概念
<a name="key-concepts-inline-map"></a>

**內嵌模式**  
`Map` 狀態的有限並行模式。在此模式中，狀態的每個反覆運算都會在包含 `Map` 狀態的工作流程內容中`Map`執行。Step Functions 會將這些反覆運算的執行歷史記錄新增至父工作流程的執行歷史記錄。 `Map` 狀態預設會在內嵌模式中執行。  
此模式僅接受 JSON 陣列做為輸入，並支援最多 40 個並行反覆運算。

**內嵌映射狀態**  
`Map` 狀態設定為**內嵌**模式。

**映射工作流程**  
狀態針對每次反覆`Map`執行的一組步驟。

**映射狀態反覆運算**  
在 `Map` 狀態內定義的工作流程重複。

## 內嵌映射狀態欄位
<a name="map-state-inline-additional-fields"></a>

若要在工作流程中使用*內嵌映射狀態*，請指定一個或多個這些欄位。除了[常見狀態欄位之外，您還可以指定這些欄位](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)。

## 已棄用的欄位
<a name="map-state-inline-deprecated-fields"></a>

**注意**  
雖然您可以繼續包含使用下列欄位`Map`的狀態，但強烈建議您將 `Iterator` 取代為 `ItemProcessor`，並將 取代`Parameters`為 `ItemSelector`。

** `Iterator`**  
指定 JSON 物件，定義一組處理陣列中每個元素的步驟。

**`Parameters`**  
指定索引鍵/值對的集合，其中的值可以包含下列任何項目：  
+ 您在狀態機器定義中定義的靜態值。
+ 使用[路徑](amazon-states-language-paths.md)從輸入中選取的值。

## 內嵌映射狀態範例 (JSONPath)
<a name="inline-map-state-examples"></a>

請考慮下列在**內嵌**模式下執行之`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`
<a name="inline-map-state-example-params"></a>

假設上一個範例中的 `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`狀態輸入和輸出處理
<a name="inline-map-state-output"></a>

對於指定`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)