> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# connectorBatchGroupRead

> 遍历批处理组消息的各个成员，在执行调用主体时将每个成员公开为 _message。

遍历批处理组消息的各个成员，在执行调用主体时将每个成员公开为 `_message`。此操作仅在 [Script 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/script.md)模板中受支持。

## 必需的参数

* **messageId**：要遍历的批处理组消息的 Id。通常引用为 `[MessageId]`。

## 可选的参数

* **messageType**：读取批处理成员时使用的消息类型。可接受的值为 `Auto`、`Input`、`Output` 和 `Temp`。默认值为 `Auto`，但请阅读[始终将 messageType 设置为 Input](#始终将-messagetype-设置为-input) 了解最佳实践建议。`Output` 和 `Temp` 分别针对脚本的输出消息存储和临时消息存储；这两个值很少需要使用。

## 输出属性

对于每个批处理成员，调用主体中的 `_message` 上提供以下属性：

* **\_message.body**：批处理成员消息的内容。
* **\_message.header:\***：批处理成员的消息头。例如，`[_message.header:filename]` 返回 filename 消息头。

## 相关属性

* **\_message.isBatchGroup**：在 Script 上下文中的任何 `_message` 上均可用。如果当前消息是批处理组，则返回 `true`；如果是标准消息，则返回 `false`。可用于仅在传入消息为批处理组时才有条件地调用 `connectorBatchGroupRead`。

## Script 端口用法

### 始终将 messageType 设置为 Input

在 Script 端口中调用 `connectorBatchGroupRead` 时，请始终显式地将 `messageType` 设置为 `Input`：

```xml theme={null}
<arc:set attr="batchin.messageId" value="[MessageId]" />
<arc:set attr="batchin.messageType" value="Input" />

<arc:call op="connectorBatchGroupRead" in="batchin">
  ...
</arc:call>
```

如果省略 `messageType`，该操作会同时在输入消息以及脚本在当前运行中创建的所有输出消息中搜索该消息 Id。如果脚本在调用完成之前使用 `batchGroupKey` 推送了输出，则某个输出批处理组可能会被分配与输入相同的消息 Id。发生这种情况时，该操作无法确定您指的是哪条消息，并会失败，报出类似以下的错误：

```
The message <MessageId> is ambiguous between the Temp and the Input.
```

是否出现此错误取决于输出推送的顺序，因此脚本可能在测试时通过，却在处理真实数据时失败。

### 每次推送前清除 output 项

[arc:push](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/keyword-reference/op-arc-push.md) 不会清除输出属性；这些属性会延续到下一次推送。请在每次推送之前调用 `<arc:unset item="output" />`，以避免出现意外行为。

如果不清除，在一次推送中设置的值可能会影响下一次推送：

| 延续的属性 | 结果 |
| - | - |
| 在同时设置了 `isBatchGroup=true` 的推送中设置了 `output.data` 或 `output.filepath` | 错误：在批处理组的最终推送中，正文数据无效 |
| `output.batchGroupKey` | 本应作为独立消息的推送反而被添加到批处理组中 |
| `output.isBatchGroup` | 下一次推送会尝试再次最终确定该组，并导致失败 |
| `output.header:*` | 一个成员的消息头出现在下一个成员或批处理组消息上 |
| `output.filename` | 之后的消息可能会得到错误的名称 |

`arc:unset` 也会清除 `output.batchGroupKey`。在使用 `output.isBatchGroup=true` 最终确定批处理组的推送中，请在 `arc:unset` 之后重新设置 `output.batchGroupKey`。

### 以批处理组形式输出

要以批处理组的形式发送输出，请在每个成员的推送中设置 `output.batchGroupKey`。共享相同键的成员会被分为一组。如果没有执行显式的最终推送，Script 端口会在运行结束时自动创建该批处理组。

要定义组级属性（例如组的文件名或消息头），请执行显式的最终推送：将 `output.isBatchGroup` 设置为 `true`，并设置相同的 `batchGroupKey`。最终推送会在运行中的该时间点生成该组，而不是在运行结束时生成。

最终推送的约束：

* `output.batchGroupKey` 必须与一个已存在且非空的待处理组的键匹配。
* `output.data` 和 `output.filepath` 无效，并会返回错误，因为组的内容由其成员定义。`output.filename` 和其他消息元数据仍然有效。

### 生成顺序

* 常规输出消息按推送顺序生成。
* 显式的 `isBatchGroup=true` 推送会在运行中的该时间点生成其组。
* 所有剩余的隐式组会在运行结束时生成。

## 示例

### 将批处理成员作为常规消息读取

读取输入批处理组的每个成员，并将其作为常规输出消息生成：

```xml theme={null}
<arc:set attr="batchin.messageId" value="[MessageId]" />
<arc:set attr="batchin.messageType" value="Input" />

<arc:call op="connectorBatchGroupRead" in="batchin">
  <arc:unset item="output" />
  <arc:set attr="output.data" value="[_message.body]" />
  <arc:set attr="output.filename" value="[_message.header:filename]" />
  <arc:push item="output" />
</arc:call>
```

### 将成员重新组合为新的批处理组

读取每个成员，对其重命名，并将所有成员作为一个名为 `batch01` 的新批处理组生成：

```xml theme={null}
<arc:set attr="batchin.messageId" value="[MessageId]" />
<arc:set attr="batchin.messageType" value="Input" />

<arc:call op="connectorBatchGroupRead" in="batchin">
  <arc:unset item="output" />
  <arc:set attr="output.batchGroupKey" value="group1024" />
  <arc:set attr="output.data" value="[_message.body]" />
  <arc:set attr="output.filename" value="x-[_message.header:filename].txt" />
  <arc:push item="output" />
</arc:call>

<arc:unset item="output" />
<arc:set attr="output.batchGroupKey" value="group1024" />
<arc:set attr="output.isBatchGroup" value="true" />
<arc:set attr="output.filename" value="batch01" />
<arc:push item="output" />
```

如果省略最终推送（最后一个代码块），批处理组仍会在脚本结束时生成，并以其 `batchGroupKey` 命名。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.