本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

**管理状态和转换数据**  
了解如何[使用变量在状态之间传递数据](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)
《The AWS Step Functions Workshop》**中的 [Distributed map and related resources](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 个项目，而第十二批包含其余 30 个项目。  
或者，您也可以将每个批次的最大项目指定为*分布式 Map 状态*输入中现有键值对的[参考路径](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** 的状态，您可以直接向 BatchInput 提供 JSONata 表达式，或者在 JSON 对象或数组中使用 JSONata 表达式。