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

# ItemBatcher （地圖）
<a name="input-output-itembatcher"></a>

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

## 指定項目批次處理的欄位
<a name="input-output-itembatcher-subfields"></a>

若要批次項目，請指定要批次的項目數量上限、批次大小上限或兩者。您必須指定其中一個值來批次處理項目。

**每個批次的項目上限**  
指定每個子工作流程執行處理的項目數量上限。解譯器會將`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 表達式。