> ## 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-Hant/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-Hant/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.