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

# EDIFACT 端口

> 知行之桥EDIFACT 端口的配置和使用指南。

EDIFACT 端口可以从 XML 生成 EDIFACT 文档，也可以将 EDIFACT 文档转换为 XML。

## 核心功能

* **EDIFACT 与 XML 格式的双向转换**：支持两种格式之间的完整互转。
* **全面的交换头验证与生成**：确保报文结构的合规性。
* **支持多个 EDIFACT 版本**：具有自动架构检测功能。
* **交换确认与功能性确认支持**：实现消息收发的闭环确认。

## 概览

接收 EDIFACT 文档时，EDIFACT 端口会验证 EDIFACT 交换头并将 EDIFACT 文档转换为 XML。这作为一个暂存步骤非常有用，因为 XML 是 知行之桥 在流程中处理数据的主要格式。EDIFACT 端口会自动读取输入文件以确定合适的 EDIFACT 架构，然后根据该架构解析文档。

生成 EDIFACT 文档时，EDIFACT 端口会将 XML 转换为 EDIFACT 文档语法并应用相应的交换头。在流程的其他位置获取并转换 XML 数据后，这通常是创建 EDIFACT 文档的最后一步。

> [!NOTE]
>
> 启用 **Test Indicator** 设置可以避免交换头验证。

EDIFACT 端口还可以自动为传入的 EDIFACT 文档生成确认。有关更多信息，请参阅 [EDIFACT ACK](#edifact-ack)。

## 先决条件

开始之前，请确保已为需要处理的文档类型安装正确的架构。EDIFACT 端口原生支持以下架构定义：4.1、D03A、D04A、D07A、D96A、D96B、D97A、D99A 和 D99B。你可以在 知行之桥 安装目录的 `app_data/edifact_schemas` 目录中找到它们。如果需要其他架构，可以联系我们免费下载额外的架构文件。

下载并解压 zip 存档后，将整个文件夹放入 `app_data/edifact_schemas` 目录下命名合适的子目录中。

## 端口配置

本节包含所有可配置的端口属性。

### 设置

#### 转换配置

*与端口核心操作相关的设置。*

| 设置 | 描述 |
| - | - |
| **端口 Id** | 端口的静态、唯一标识符。 |
| **端口类型** | 显示端口名称及其用途描述。 |
| **端口描述** | 一个可选字段，用于提供端口及其在流程中角色的自由格式描述。 |
| **转换类型** | 端口是将 EDIFACT 文档转换为 XML，还是从 XML 生成 EDIFACT 文档。 |
| **动态处理交易伙伴** | 启用后，端口会自动从 EDI 交易中识别并跟踪交易伙伴关系。禁用后，必须手动定义伙伴关系。有关更多信息，请参阅 [EDI 交易伙伴选项卡](#edi-交易伙伴选项卡)。 |

#### EDI 交易伙伴

| 设置 | 描述 |
| - | - |
| **交易伙伴方标识 (UNB2.1)** | EDIFACT 通信中标识发送方的唯一 Id。生成 EDIFACT 文档时，此项应为本方标识。仅在未勾选 **动态处理交易伙伴** 时适用。 |
| **个人标识 (UNB3.1)** | EDIFACT 通信中标识接收方的唯一 Id。生成 EDIFACT 文档时，此项应为交易伙伴方的标识。仅在未勾选 **动态处理交易伙伴** 时适用。 |

#### 交换头配置

*与 EDIFACT 交换头相关的设置。从 XML 生成 EDIFACT 文档时，这些设置用于生成文档头。解析 EDIFACT 文档时，这些设置用于验证传入文档。*

| 设置 | 描述 |
| - | - |
| **语法标识符 (UNB1.1)** | 标识 EDIFACT 文档使用的字符集。 |
| **语法版本 (UNB1.2)** | 与 **语法标识符** 结合使用，用于确定 EDIFACT 文档中使用的语法。根据此处的选择，其他交换设置选项会在[高级页面](#高级页面)上显示或隐藏。 |
| **交易伙伴方代码限定符 (UNB2.2)** | **发送方标识** 的限定符，用于为该值提供上下文（例如 EAN 位置编号）。 |
| **个人代码限定符 (UNB3.2)** | **接收方标识** 的限定符，用于为该值提供上下文（例如 EAN 位置编号）。 |
| **测试指示器 (UNB11)** | 交换处于测试模式还是生产模式。勾选后，接收文档时不会验证交换头。 |
| **功能组** | 勾选此项可自动将发送方和接收方标识符添加到 **高级页面** 上的[功能组配置](#功能组配置)。 |

#### ACK

*与生成和请求确认相关的设置。*

| 设置 | 描述 |
| - | - |
| **技术性 ACK（CONTRL）** | 接收时是否返回技术性 CONTRL ACK，发送时是否请求技术性 CONTRL ACK。技术性确认用作交换的回执。 |
| **功能性 ACK（CONTRL）** | 接收时是否返回功能性 CONTRL ACK，发送时是否请求功能性 CONTRL ACK。功能性确认用于指示接收的交换已被接受或拒绝。 |

### 示例文件选项卡

*上传示例文件可以方便地在任何连接的 CSV Map 或 XML Map 端口中进行映射。*

使用 **示例文件** 选项卡生成用于 [CSV Map](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/map.md) 或 [XML Map](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/xml-map/xml-map.md) 端口的源或目标 XML 模板。单击 **添加示例文件**。

1. 如果您已有反映数据预期格式和结构的示例文件，请选择 **文件上传** 并浏览到您的文件。或者，选择 **手动创建** 直接在应用程序中创建文件。如果您选择 **手动创建**，请为示例文件命名。单击 **下一步**。

2. 如果您浏览到现有文件，**查看文件** 选项卡将填充其内容。如果您选择手动创建文件，请在此选项卡上输入示例数据。单击 **下一步**。

3. **翻译和预览** 选项卡显示将示例数据转换为 XML 的预览。当您对示例满意时，单击 **添加**。

### 高级页面

#### EDI 分隔符

*指定用于分隔元素、段等内容的字符。*

| 设置 | 描述 |
| - | - |
| **数据元素分隔符** | 分隔文档中各个数据元素的字符。 |
| **组件元素分隔符** | 分隔文档中复合数据结构内元素的字符。 |
| **段终止符** | 指示文档中段结尾的字符。 |
| **释放字符** | “释放”（转义）下一个字符、覆盖其通常含义的字符。只要保留字符前面带有释放字符，它就可以作为数据出现在文档中。 |
| **重复元素分隔符** | 标识元素值重复的字符。 |
| **后缀** | 追加到 **段终止符** 后，用于区分段。 |

#### 交换头配置

*与 EDIFACT 交换头相关的其他设置。这些选项会根据“设置”选项卡上指定的 **语法版本** 显示或隐藏。*

| 设置 | 描述 |
| - | - |
| **服务代码列表目录版本号 (UNB1.3)** | 进一步指定 EDIFACT 文档中使用的语法。仅适用于 EDIFACT 语法版本 4。 |
| **字符编码 (UNB1.4)** | 指定字符的编码方式（例如 ASCII 或 UTF-8）。仅适用于 EDIFACT 语法版本 4。 |
| **反向路由地址 (UNB2.3)** | 发送方系统中可选的地址，用于接收响应交换。仅适用于版本 4 之前的 EDIFACT 语法版本。 |
| **交易伙伴方内部 ID (UNB2.3)** | 额外的发送方标识，用于促进响应交换的内部路由。仅适用于 EDIFACT 语法版本 4。 |
| **交易伙伴方内部子标识 (UNB2.4)** | 需要子级标识时，进一步标识发送方。仅适用于 EDIFACT 语法版本 4。 |
| **路由地址 (UNB3.3)** | 接收方系统中可选的地址，用于指定交换的路由。仅适用于版本 4 之前的 EDIFACT 语法版本。 |
| **个人内部标识 (UNB3.3)** | 额外的接收方标识，用于促进接收交换的内部路由。仅适用于 EDIFACT 语法版本 4。 |
| **个人内部子标识 (UNB3.4)** | 需要子级标识时，进一步标识接收方。仅适用于 EDIFACT 语法版本 4。 |
| **交易伙伴方密码 (UNB6.1)** | 用于访问接收方系统的引用或密码。 |
| **交易伙伴方密码限定符 (UNB6.2)** | **交易伙伴方密码** 的限定符（如果适用），用于提供上下文。 |
| **应用参考编号 (UNB7)** | 标识交换中的消息所涉及的应用程序组。 |
| **处理优先级代码 (UNB8)** | 请求交换处理优先级的代码。 |
| **通信协议 (UNB10)** | 定义控制交换的通信协议类型。 |

#### 功能组配置

*与 EDIFACT 文档功能组头相关的设置。这些可选标识符可以帮助将相似的交换分组在一起，或促进组织内的子地址。*

| 设置 | 描述 |
| - | - |
| **应用交易伙伴方标识 (UNG2.1)** | 标识发送文档的应用程序（例如部门、分支机构或计算机系统）。 |
| **应用个人标识 (UNG2.1)** | 标识文档预期的目标应用程序。 |

#### 高级设置

*前面类别中未包含的设置。*

| 设置 | 描述 |
| - | - |
| **批处理** | 一个交换可以包含多个事务。未勾选时，端口会为交换中的每个事务创建单独的输出文件。勾选后，端口会将所有事务分组到单个输出文件中。仅当 **转换类型** 为 EDI 到 XML 时适用。 |
| **使用引用 Id** | 勾选后，将 EDIFACT 转换为 XML 时，会使用引用 Id 命名 XML 元素。仅当 **转换类型** 为 EDI 到 XML 时适用。例如：`<_143>value</_143>`。如果未勾选，则使用引用标识符命名 XML 元素：`<BEG03>value</BEG03>`。 |
| **编码** | 指定字符编码（例如 ASCII 或 UTF-8）。 |
| **扩展限定符值** | 勾选后，包含 EDI 限定符的 XML 元素会包含子元素，其中包含限定符代码和值。例如： `<N101>`   `<Code>ST</Code>`   `<Value>Ship To</Value>` `</N101>` |
| **功能性 ACK** | 默认情况下，所有功能性确认（997、999）都会路由到流程图中选择的端口，且 XML 转换不会显示在 **交易** 选项卡中。勾选此项后，转换后的确认也会包含在 **交易** 选项卡中。除了新的 EDI 文档之外，这还允许将功能性确认集成到目标源中。 |
| **将描述生成为** | 将 EDIFACT 转换为 XML 时，可以提供 EDIFACT 段和元素的描述作为 EDIFACT 数据的上下文。使用此下拉列表选择是否将此上下文添加为 XML 注释或 XML 属性。 |
| **本地文件方案** | 用于为端口输出的消息分配文件名的方案。可以在文件名中动态使用宏，以包含标识符和时间戳等信息。有关更多信息，请参阅[宏](#宏)。 |
| **嵌套循环** | 勾选后，端口会检测 EDI 数据中嵌入层次关系的 EDI 结构，并生成以父子关系表示这些层次关系的 XML。有关更多信息，请参阅[主-明细层级：转换 CPS 和 HYN 循环](#主-明细层级：转换-cps-和-hyn-循环)。 |
| **处理延迟** | 放置在 **交易** 选项卡中的文件在处理前延迟的时间（以秒为单位）。这是旧版设置。最佳做法是[使用 File 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/flows/designing-a-flow.md#与本地文件系统交互)来管理本地文件系统，而不是使用此设置。 |
| **严格架构验证** | 当检测到重复次数超过允许数量、缺少必需的元素或段、限定符和代码值无效、不允许的元素长度以及元素值无效时，端口应忽略、警告还是失败。选择 Disable 会关闭架构验证检查。 |
| **跟踪 UNB2.1** | 是否将 UNB2.1 值作为跟踪消息头添加到已处理的消息。 |
| **跟踪 UNB3.1** | 是否将 UNB3.1 值作为跟踪消息头添加到已处理的消息。 |
| **跟踪事务类型** | 是否将事务类型作为跟踪消息头添加到已处理的消息。 |
| **验证标识符** | 勾选此项以确保转换文档中的标识符与端口配置中的标识符匹配。 |
| **重复文件操作** | 当端口收到控制号此前已见过的消息（重复消息）时，端口应如何处理。设置为 `Ignore` 时，端口会静默跳过重复消息并继续处理。设置为 `Warn` 时，端口会处理文件但返回警告。设置为 `Fail` 时，端口不接受该文件并返回错误。 |
| **上传架构** | 用于上传架构并将其安装到端口的 Schema 文件夹。如果架构已存在，系统会询问是否要覆盖它。 |
| **重置状态** | EDI 端口会跟踪已使用的控制号并递增该数字，以确保未来运行不会重复数据。使用此按钮可在不更改任何配置设置的情况下将计数器重置为初始状态。 |

#### 消息

*消息设置确定端口如何搜索消息并在处理后管理它们。*

**注意：**以下设置已弃用，默认处于隐藏状态。只有先前已启用这些设置或将其配置为非默认值的端口才会显示它们。若要保留成功处理的文件副本，请在工作流中右键单击该端口，选择**显示成功路径**，然后将成功路径连接到 [File 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/file.md)。

<table><thead><tr><th>设置</th><th>描述</th></tr></thead>
<tbody><tr><td>**保存到已发送文件夹**（已弃用）</td>
<td>将端口处理的文件复制到 Sent 文件夹。默认禁用。保存到 Sent 文件夹中的文件不受[静态加密](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/encryption-at-rest.md)保护。</td></tr>
<tr><td>**已发送文件夹方案**（已弃用）</td>
<td>按所选时间间隔对 **Sent** 文件夹中的文件进行分组。仅在启用**保存到已发送文件夹**时适用。</td></tr></tbody></table>

#### 日志

*用于管理日志创建和存储的设置。*

<table><thead><tr><th>设置</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**日志级别**</td>
<td>指定要记录在端口日志目录中的信息类型：
<ul><li>**None** - 不创建任何日志。</li>
<li>**Error** - 仅当端口遇到错误时才创建日志。</li>
<li>**Warning** - 仅当端口发出警告时才创建日志。</li>
<li>**Info** - 记录工作流的一般信息，包括任何错误和警告（如果适用）。</li>
<li>**Debug** - 记录成功和失败工作流的详细调试信息。</li>
<li>**Trace** - 记录成功和失败工作流的详细跟踪信息。</li></ul>
\*\*请注意：\*\***Debug** 和 **Trace** 级别的日志可能会记录敏感信息，包括消息内容和 SSL 证书。尽管连接属性（例如密码）被屏蔽了，但在与您的组织外部共享它们之前，请查看此级别的日志以避免泄漏敏感信息。</td></tr>
<tr><td>**日志文件夹结构**</td>
<td>指示端口根据选定的时间间隔将日志文件夹中的文件分组。例如，**Weekly** 选项指示端口每周创建一个新的子文件夹，并将该周的所有日志存储在该文件夹中。空白设置告诉端口将所有日志直接保存在日志文件夹中。对于处理许多事务的端口，使用子文件夹有助于保持日志的有序性并提高性能。</td></tr>
<tr><td>**保留消息副本**</td>
<td>指示端口在日志目录中保存最新消息副本的切换。请注意，端口每个子文件夹只保留一个消息，并且端口在再次运行时会覆盖以前保存的消息。</td></tr></tbody></table>

#### 杂项

*特殊设置适用于特定用例。*

<table><thead><tr><th>设置</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**其他设置**</td>
<td>允许在以分号分隔的列表中配置隐藏的端口设置，例如 `setting1=value1;setting2=value2`。正常的端口用例和功能不需要使用这些设置。</td></tr></tbody></table>

### EDI 交易伙伴选项卡

默认情况下，端口 **设置** 页面上的 **动态处理交易伙伴** 复选框是启用的。这意味着端口会自动从 EDI 事务中识别并跟踪交易伙伴关系。在这种情况下，不需要手动配置交易伙伴，因为端口会在许可限制范围内动态管理所有交易伙伴，并在达到限制时发出通知。端口根据其处理的文件跟踪标识符，这意味着可能可以使用单个端口来处理所有交易伙伴。

![Dynamically process partners setting](https://docs.kasoftware.com/26.4/images/edi_dynamically_process_partners.png)

仅当知行之桥正在动态处理交易伙伴时，**EDI 交易伙伴** 选项卡才会被启用。该选项卡会填充端口识别出的每个关系的交易伙伴标识符和个人标识符，以及该交易伙伴最后一次处理文件的日期。在 **EDI 交易伙伴** 选项卡中，可以通过将鼠标悬停在交易伙伴上并点击垃圾桶图标，删除最后处理日期超过 30 天的交易伙伴。

![EDI Partners tab](https://docs.kasoftware.com/26.4/images/edi_edifact_partners_tab.png)

启用此设置后，端口识别出的所有交易伙伴关系都会自动跟踪以用于许可计量。它们会出现在 **设置 > 许可** 页面的 [端口使用情况](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/license-settings.md#connector-usage) 部分。在此处，您可以查看交易伙伴标识符和个人标识符、关联的端口以及日期信息。

![EDI partner licenses](https://docs.kasoftware.com/26.4/images/edi_partner_licenses.png)

如果禁用此设置，则必须在 **设置** 页面的 **交易伙伴标识符** 和 **个人标识符** 字段中显式配置交易伙伴关系，如下图所示。

![Dynamically process partners disabled](https://docs.kasoftware.com/26.4/images/edi_shared_partner_config_disabled.png)

手动定义的交易伙伴关系也会出现在 **设置 > 许可** 页面的 [端口使用情况](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/license-settings.md#connector-usage) 部分。

### 自动化

#### 自动化设置

*与端口自动处理文件相关的设置。*

| 设置 | 描述 |
| - | - |
| **发送** | 指示端口在文件准备就绪时自动发送文件的开关。 |
| **重新发送间隔** | 收到负 ACK 的文件重新发送前端口等待的间隔。例如，如果交易伙伴收到文件但其中有问题并返回负 ACK，此设置指定再次发送文件前等待多长时间。 |
| **最大尝试次数（异步）** | 请求功能性 ACK 时端口处理输入文件的最大次数。是否成功取决于在 **重新发送间隔** 内是否返回功能性 ACK。如果未返回成功的功能性 ACK，端口会重新发送文件，直到达到 **最大尝试次数**。如果设置为 0，端口会无限期重新发送文件。 |

#### 性能

*与端口资源分配相关的设置。*

<table><thead><tr><th>设置</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**最大工作线程数**</td>
<td>此端口上处理文件时从线程池中消耗的最大工作线程数。如果设置，则会覆盖 [高级设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/advanced-settings.md) 页面的 [性能设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/performance-settings.md) 部分的默认设置。</td></tr>
<tr><td>**最大文件数**</td>
<td>分配给端口的每个线程发送的最大文件数。如果设置，则会覆盖 [高级设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/advanced-settings.md) 页面的 [性能设置](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/performance-settings.md) 部分的默认设置。</td></tr></tbody></table>

### 警报

*与配置通知相关的设置。*

在执行服务级别协议 (SLA) 之前，需要设置电子邮件通知以接收通知。默认情况下，知行之桥 使用 [通知](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/alerts.md) 选项卡上的全局设置。要为此端口使用其他设置，请启用 **覆盖全局设置**。

默认情况下，错误通知处于启用状态，这意味着每当出现错误时都会发送电子邮件。要关闭错误通知，请取消选中 **启用** 复选框。

输入 **主题**（必填）。勾选**允许在主题中使用 ArcScript**，即可在**主题**字段中使用 ArcScript。选中后会显示 **ArcScript 编辑器**按钮（![ArcScript 编辑器按钮](https://docs.kasoftware.com/26.4/images/rest_arcscript_editor.png)）。

（可选）输入以逗号分隔的**收件人**电子邮件地址列表。

### SLA

*与配置服务级别协议 (SLA) 相关的设置。*

SLA 允许配置预期流程中端口发送或接收的数据量，并设置预期达到该数据量的时间范围。当 SLA 未达到时，知行之桥 会发送电子邮件警告用户，并将 SLA 标记为 *存在风险*，这意味着如果 SLA 未能尽快达到，则会被标记为 *已违反*。这让用户有机会介入并确定 SLA 未达到的原因，并采取适当的措施。如果在风险时间段结束时仍未达到 SLA，则会将 SLA 标记为已违反，并再次通知用户。

SLA 转换为 *存在风险* 或 *已违反* 状态时，也会写入[应用程序日志](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/activity.md#应用程序日志)，这意味着应用性能监控 (APM) 和日志采集工具也可以针对这些状态发出警报。

要定义 SLA，请启用 **预期数据量**，然后点击 **设置** 选项卡。

![SLA Empty](https://docs.kasoftware.com/26.4/images/sla_empty.png)
<ul><li>如果端口具有单独的发送和接收操作，请使用单选按钮指定 SLA 适用的方向。</li>
<li>在窗口的 **预计至少** 部分中：
<ul><li>设置预计处理的最小事务数量（交易量）</li>
<li>使用 **每个** 字段指定时间范围</li>
<li>指示 SLA 生效的时间。如果选择 **开始于**，请填写日期和时间字段。</li>
<li>勾选希望 SLA 生效的星期几对应的复选框。如有必要，请使用下拉菜单选择 **每天**。</li></ul></li>
<li>在窗口的 **将状态设置为“有风险”** 部分中，指定应将 SLA 标记为有风险的时间。
<ul><li>默认情况下，只有在违反 SLA 的情况下才会发送通知。要更改此设置，请勾选 **发送“有风险”通知**。</li></ul></li></ul>

以下示例显示了为端口配置的 SLA，该端口预计在周一至周五每天接收 1000 个文件。如果尚未收到 1000 个文件，则会在时间段结束前 1 小时发送风险通知。

![SLA Configuration Example](https://docs.kasoftware.com/26.4/images/sla_defined.png)

> [!NOTE]
>
> 如果有必要，可以关闭 SLA 通知。这在维护窗口期间非常有用。点击导航栏上的 **设置**，然后跳转到 **通知 > 通用通知**。点击平板和铅笔图标进行编辑，并取消勾选 **SLA 通知** 设置。

## 转换类型

以下部分详细介绍 EDIFACT 到 XML 以及 XML 到 EDIFACT 的转换过程。

### EDIFACT 转换为 XML

将 **转换类型** 设置为 *EDI to XML* 会指示端口将传入的 EDIFACT 文档解析为 XML。端口首先读取文档中交换和功能组部分的所有头信息，并根据配置的端口设置进行验证（除非勾选 **Test Indicator**）。然后，端口解析文档中使用的具体 EDIFACT 架构，并从磁盘上的 `edifact_schemas` 文件夹加载架构（可以从联系我们免费下载额外的架构文件）。端口使用该架构生成表示文档 EDIFACT 结构的 XML，用文档中的值填充 XML，并根据 **Generate Descriptions As** 的值，以 XML 注释或 XML 元素属性的形式为每个值提供上下文。

若要使用一组测试 EDIFACT 文档查看此过程，请导航到 EDIFACT 端口的 **交易** 选项卡（**转换类型** 设置为 *EDI to XML*），然后选择 **More > Create Test Files**。系统会自动生成发票、采购订单、采购订单确认和发货通知的 EDIFACT 文档，并将其放入 **交易** 目录。端口处理这些测试文件后，导航到 **交易** 选项卡即可查看生成的 XML。

EDIFACT 文档转换为 XML 后，可以通过多种方式转换和处理这些数据。通常，EDIFACT 数据需要存储在数据库或其他后端应用系统中。由于 知行之桥 使用 XML 表示对这些后端系统的 `inserts`，因此存储 EDIFACT 数据就变成了将一个 XML 结构映射到另一个 XML 结构。这通常通过可视化设计器驱动的 [XML Map 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/xml-map/xml-map.md)完成。

### XML 转换为 EDIFACT

将 **转换类型** 设置为 *XML to EDI* 会指示端口从文档的 XML 表示生成 EDIFACT 文档。端口从 XML 解析出的数据构造 EDIFACT 消息后，会根据配置的端口设置添加功能组和交换头。

若要使用一组测试 XML 文件查看此过程，请导航到 EDIFACT 端口的 **交易** 选项卡（**转换类型** 设置为 *XML to EDI*），然后选择 **More > Create Test Files**。系统会自动生成表示发票、采购订单、采购订单确认和发货通知的 XML 文件，并将其放入 **交易** 目录。端口处理这些测试文件后，导航到 **交易** 选项卡即可查看生成的 EDIFACT 文档。

### 打印视图

在端口的 **交易** 选项卡上查看 EDIFACT 文档时，可以以打印预览格式或原始数据格式进行查看。默认情况下，文档以预览格式显示，如下图所示：

![EDIFACT print preview](https://docs.kasoftware.com/26.4/images/edifact_print_preview.png)

预览格式以易于阅读的布局显示数据。使用右上角的 **原始视图**（Raw View）开关可以查看未格式化的文档。

## 与 XML Map 端口结合使用

EDIFACT 端口执行两项操作之一：接收 XML 输入或生成 XML 输出。为确保输入和输出文件具有正确的 XML 结构，我们强烈建议在生成出站 EDIFACT 文档时将 [XML Map 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/xml-map/xml-map.md) 用作流程中的上一步，或在接收入站 EDIFACT 文档时将其用作流程中的下一步。下面描述的 **上传测试文件** 功能使 XML Map 端口和 EDIFACT 端口之间的交互变得简单。

### 上传测试文件

按照以下步骤生成输入文件的 XML 模板：

1. 在端口的 **交易** 选项卡中，单击 **更多** 下拉菜单，然后单击 **上传测试文件**。

2. 导航到磁盘上要建模为 XML 的文件，选择它，然后单击 **OK**。

3. 将 EDIFACT 端口连接到流中的 XML Map 端口。此连接可以在任一方向进行——入站到 XML Map 端口，或从 XML Map 端口出站。

XML Map 端口会自动检测测试文件的结构。根据您放置 EDIFACT 端口的位置，该文件将出现在 XML Map 端口的 **源文件** 或 **目标文件** 下拉菜单中。

> [!NOTE]
>
> XML Map 端口需要源模板和目标模板，因此必须根据数据来源结构或应转换为的结构来设置剩余模板。例如，如果需要将 EDIFACT 文档中的数据插入数据库，则 XML Map 端口中的另一个模板将是数据库插入的 XML 模型。有关在两个模板文件之间创建映射的更多信息，请参阅 XML Map 端口的 [使用映射编辑器](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/xml-map/xml-map-designer.md)。

## EDIFACT ACK

以下部分详细介绍两种 EDIFACT 确认（ACK），以及 知行之桥 如何期待、处理和生成 ACK。

### 技术性 ACK 与功能性 ACK

技术性 ACK 有时称为交换 ACK，表示双方之间发生了交换，但不一定表示已交换任何单个消息。它们作为发送方的回执，指示 EDIFACT 消息已成功接收，但不说明处理消息内容时是否存在任何问题。

功能性 ACK 表示接收方已处理交换。它们可以报告已接受、带问题接受或拒绝接收的文档。它们既作为交换已成功接收的回执，也表示该交换已被完整处理。

### 期待 ACK、处理 ACK 和生成 ACK

#### 期待 ACK

在 XML 到 EDI 模式下运行的 EDIFACT 端口可以配置为期望消息返回技术性 ACK 和/或功能性 ACK。当在设置选项卡的 [ACK](#ack) 部分勾选 **Technical acknowledgment (CONTRL)** 和 **Functional acknowledgment (CONTRL)** 中的一个或两个时，端口会在适当的 ACK 返回并处理之前，将传输保持为 Pending ACK 状态。这意味着可以使用端口状态来确定接收方是否已确认收到交换。

当需要确认的 EDI 消息未收到确认时，会在消息中添加一个 Pending-Timeout 标头。在等待 ACK 期间，消息处于 *Pending* 状态。如果在规定时间内未收到 ACK，则会将消息状态更改为 *Error* 的日期和时间填充到 Pending-Timeout 标头中。当收到 ACK 并将消息更新为 *Success* 时，会添加一个包含空字符串值的新标头。

下图显示了 知行之桥 期望发票文档返回 ACK 时涉及的逻辑流程：

!\[EDIFACT 接收 ACK(/26.4/images/edifact-ack-receive.png)

在上图中，XML 到 EDI 模式下的 EDIFACT 端口生成要交换的文档 **(1)**，并在文档传输给交易伙伴期间将其保持为 Pending ACK 状态。交易伙伴根据其业务逻辑处理传输，并按照配置的交换参数创建确认 **(2)**。确认返回后，会根据下一节中的信息进行处理 **(3)**。

#### 处理 ACK

在典型流程中，EDIFACT ACK 会到达以 EDI 到 XML 模式运行的 EDIFACT 端口。可以将此 EDIFACT 端口配置为自动将收到的任何确认路由到最初生成被确认文档的 EDIFACT 端口。通过在 Flows 画布上将 EDI 到 XML 模式下 EDIFACT 端口底部的灰点拖到 XML 到 EDI 模式下的 EDIFACT 端口，即可直观配置 EDIFACT 端口之间的 ACK 路由。

XML 到 EDI 模式下的 EDIFACT 端口收到路由的 ACK 后，会将 ACK 与原始消息配对，并将其状态从 Pending ACK 更改为 Sent。

#### 生成 ACK

当 EDI 到 XML 模式下的 EDIFACT 端口收到消息并生成相应的 XML 时，可以自动为收到的消息生成 CONTRL 确认。为此，请在设置选项卡的 [ACK](#ack) 部分勾选 **Technical acknowledgment (CONTRL)** 和/或 **Functional acknowledgment (CONTRL)**。这些确认必须路由到另一个 EDIFACT 端口（XML 到 EDI 模式）以完成 ACK。ACK 被路由到的端口会应用交换头，并像任何其他 EDIFACT 消息一样将 ACK 传递到流程中的下一个端口。若要正确路由 ACK，请将 EDI 到 XML 模式下 EDIFACT 端口底部的灰点拖到 XML 到 EDI 模式下的 EDIFACT 端口。

下图显示了为收到的发票文档创建 ACK 时涉及的逻辑流程：

!\[EDIFACT 创建 ACK(/26.4/images/edifact-ack-create.png)

如上图所示，在交易伙伴发送需要确认的消息后 **(1)**，解析该文档的 EDI 到 XML 模式 EDIFACT 端口会自动生成 ACK **(2)**。此 ACK 是一个 XML 文件，包含与该交易相关的事务信息。然后，此 XML 确认会路由回 XML 到 EDI 模式的 EDIFACT 端口 **(3)**，以便在将 ACK 发送回交易伙伴之前应用交换头（以及任何其他 EDI 方协议设置）。

## 主-明细层级：转换 CPS 和 HYN 循环

在 EDI 文档中，大多数层次关系由 EDI 段的顺序表示。某些 EDI 结构（如 DESADV 文档中的 CPS 循环和 PRICAT 文档中的 HYN 循环）不遵循此约定，而是将层次关系嵌入 EDI 元素数据本身。这会使将 EDI 数据转换为 XML 时保留这些层次关系变得困难。

EDIFACT 端口通过[高级页面](#高级页面)上的 **嵌套循环** 设置，支持在 CPS 和 HYN 段中保留层次关系。启用后，端口会解析 CPS 和 HYN 段中的元素，以确定哪些段在层次关系中“属于”其他段。这些层次关系会在输出 XML 中体现为父子关系；换句话说，此设置会将 EDI 内容隐含的层次结构转换为 XML 结构表示的层次结构。

本节说明 CPS 和 HYN 数据中如何编码层次结构，以及勾选 **嵌套循环** 时如何将此层次结构转换为 XML。

### CPS 和 HYN 层级

所有 CPS 和 HYN 段都有两个有助于建立层次结构的值：

* Id 值，用于标识当前段（此值存储在 CPS01 或 HYN01，即 CPS 或 HYN 段中的第一个元素）
* 父 Id 值，用于标识当前段的层次父级（此值存储在 CPS02 或 HYN02，即 CPS 或 HYN 段中的第二个元素）

例如，假设某个段的 Id 值为 “2”。如果下一个段在层次关系中应“属于”此前的段，则下一个段的父 Id 也应为 “2”。

如果段的父 Id 为 “0”，则该段没有父级（位于层次结构顶层）。

### 将 CPS 和 HYN 层级转换为 XML

勾选 **嵌套循环** 时，EDIFACT 端口会自动处理 CPS 和 HYN 层次结构到 XML 层次结构的转换。端口解析 CPS 和 HYN 段中的 Id 和父 Id 值，并确保生成的 XML 元素适当地嵌套在表示其父元素的元素中。

换句话说，如果 `segmentA` 的父 Id 值等于 `segmentB`，则生成的 XML 会将 `segmentA` 作为 `segmentB` 的子级。这样，在转换 EDI 数据时，层次关系会保留在 XML 结构中。

## 宏

在文件命名策略中使用宏可以提高组织效率和对数据的上下文理解。通过将宏合并到文件名中，可以动态地包含相关信息，例如标识符、时间戳和消息头信息，从而为每个文件提供有价值的上下文。这有助于确保文件名反映对组织重要的详细信息。

知行之桥 支持这些宏，它们都使用以下语法：`%Macro%`。

<table><thead><tr><th>宏</th><th>描述</th></tr></thead>
<tbody><tr><td>ConnectorID</td><td>替换为端口的 ConnectorID。</td></tr>
<tr><td>ConnectorName</td><td>替换为端口名称。可用于在文件名或路径中包含连接名称，例如按生成备份文件的数据库连接标记文件。</td></tr>
<tr><td>Ext</td><td>替换为端口当前正在处理的文件的文件扩展名。</td></tr>
<tr><td>Filename</td><td>替换为端口当前正在处理的文件的文件名（包括扩展名）。</td></tr>
<tr><td>FilenameNoExt</td><td>替换为端口当前正在处理的文件的文件名（不带扩展名）。</td></tr>
<tr><td>MessageId</td><td>计算端口输出的消息的 MessageId。</td></tr>
<tr><td>RegexFilename:*pattern*</td><td>将正则表达式模式应用于端口当前正在处理的文件的文件名。</td></tr>
<tr><td>Header:*headername*</td><td>替换为端口正在处理的当前消息的目标消息头（`headername`）的值。</td></tr>
<tr><td>LongDate</td><td>以常规格式计算系统的当前日期时间（例如，2024 年 1 月 24 日星期三）。</td></tr>
<tr><td>ShortDate</td><td>以 yyyy-MM-dd 格式计算系统的当前日期时间（例如 2024-01-24）。</td></tr>
<tr><td>DateFormat:*format*</td><td>以指定格式（`format`）计算系统的当前日期时间。有关可用的日期时间格式，请参阅 [示例日期格式](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#date-formats-with-literal-characters)。</td></tr>
<tr><td>Vault:*vaultitem*</td><td>计算指定保管库项目的值。</td></tr></tbody></table>

### 示例

某些宏（例如 %Ext% 和 %ShortDate%）不需要参数，但其他宏则需要。所有带有参数的宏都使用以下语法：`%Macro:argument%`

以下是带有参数的宏的一些示例：

<ul><li>%Header:headername%：其中 `headername` 是消息上消息头的名称。</li>
<li>%Header:mycustomheader% 解析为输入消息上设置的 `mycustomheader` 消息头的值。</li>
<li>%Header:ponum% 解析为输入消息上设置的 `ponum` 消息头的值。</li>
<li>%RegexFilename:pattern%：其中 `pattern` 是正则表达式模式。例如，`%RegexFilename:^([\w][A-Za-z]+)%` 匹配并解析为文件名中的第一个单词，并且不区分大小写（`test_file.xml` 解析为 `test`）。</li>
<li>%Vault:vaultitem%：其中 `vaultitem` 是 [vault](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/global-settings-vault.md) 中项目的名称。例如，`%Vault:companyname%` 解析为存储在保管库中的 `companyname` 项的值。</li>
<li>%DateFormat:format%：其中 `format` 是可接受的日期格式（有关详细信息，请参阅 [示例日期格式](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#sample-date-formats)）。例如，`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%` 解析为文件上的日期和时间戳。</li></ul>

还可以创建更复杂的宏，如以下示例所示：

<ul><li>将多个宏组合在一个文件名中：`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%%EXT%`</li>
<li>包括宏之外的文本：`MyFile_%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%`</li>
<li>在宏中包含文本：`%DateFormat:'DateProcessed-'yyyy-MM-dd_'TimeProcessed-'HH-mm-ss%`</li></ul>

## EDIFACT 操作

除了 知行之桥 提供的[操作](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/operations/operations.md)之外，端口还可以提供将功能扩展到 ArcScript 的操作。这些端口操作可以像任何其他 ArcScript 操作一样调用，但必须通过 `connector.rsc` 端点调用并包含身份验证令牌。

以下操作特定于 EDIFACT 端口的功能。

### edifactScan

从 EDIFACT 文档的头中扫描头值。

#### 必需参数

* **file**：EDIFACT 文件的路径。

#### 可选参数

* **format**：文件格式。默认值为 EDIFACT。

#### 输出属性

* **InterchangeSyntaxIdentifier**：所使用语法版本的 Id（UNB1.1）。
* **InterchangeSyntaxVersion**：所使用语法规则的版本。值范围为 1 到 5，数字越大支持越高级的字符集（UNB1.2）。
* **InterchangeSenderIdQualifier**：发送方 Id 的交换限定符（UNB2.2）。
* **InterchangeSenderId**：交换发送方 Id（UNB2.1）。
* **InterchangeReceiverIdQualifier**：接收方 Id 的交换限定符（UNB3.2）。
* **InterchangeReceiverId**：交换接收方 Id（UNB3.1）。
* **DocumentType**：文档类型或交易集标识符代码（UNH2.1）。

## 常见错误

以下是常见错误、原因以及建议的解决方案列表。

### 错误：Schema file not found (\[schema major version] \[schema document type])

**原因**

知行之桥 解析 EDIFACT 文件时，首先会扫描文件以获取 EDI 版本和文档类型，从而确定解析时使用的架构。应用程序包含大量 JSON 格式的 EDIFACT 架构。它们存储在应用程序目录中的 `schemas` 文件夹（位于 `data` 文件夹旁）。

此错误表示应用程序找不到与文件报告的主版本和文档类型匹配的架构文件。

如果错误消息中缺少 \[schema major version] 或 \[schema document type] 值，则 EDI 文档不包含主版本或文档类型。

否则，此错误表示合适的文档架构未包含在 知行之桥 自动包含的架构定义集中。

**解决方案**

如果 EDI 文件不包含架构主版本或文档类型，请联系交易伙伴（或 EDI 文档的其他来源），并告知他们必须在消息头中包含这些值。

否则，请从我们的免费下载页面找到合适的架构版本。下载架构文件夹并将其放在以下路径：

`[application_directory]\schemas\edifact_schemas\[major_version]\`

### 错误：The segment at line \[line number] with tag \[segment name] is not in a valid position in the specified schema (\[schema major version] \[schema document type]). This may indicate that the input file contains segments that are out of order.

**原因**

知行之桥 解析 EDIFACT 文件时，首先会扫描文件以获取 EDI 版本和文档类型，从而确定解析时使用的架构。应用程序包含大量 JSON 格式的 EDIFACT 架构，存储在根安装目录的 `www\app_data` 文件夹中。

此错误表示解析器在文件中遇到了一个 EDI 段，该段与相关文档架构中定义的段顺序不匹配。这可能表示以下几种问题：

* 交易伙伴生成的 EDI 文件不正确
* EDI 文件使用的架构版本与文件中指示的版本不同
* EDI 文件使用自定义架构生成

**解决方案**

如果 EDI 文件使用自定义架构生成，请将自定义架构文件（JSON 格式）放入 知行之桥 读取 EDI 架构的文件夹中。端口会按以下顺序检查位置来搜索架构：

1. 位于磁盘上的端口文件夹内（例如，`<ConnectorDirectory>/Resources/Schemas/`）
2. 如果一个架构由多个端口使用，知行软件建议使用如下文件夹结构：`<ApplicationDirectory>/schemas/<type>_schemas/<major version>`。在此示例中，`<type>` 应为 `edifact`。

如果 EDI 文件不是使用自定义架构生成，则有两种方法可解决合作伙伴生成的 EDI 文件与用于解析它的 EDI 架构之间的差异。

1. 手动编辑相应的 EDI 架构文件（位于上述文件路径）以调整段顺序，使其与合作伙伴的 EDI 文件匹配。错误消息会指示文件中段与架构定义发生分歧的行。沿着 JSON 中的段顺序定义追踪，直到找到分歧点，然后重新排列 JSON 中的段，使其与合作伙伴提供的文件匹配。
2. 联系交易伙伴了解 EDI 文件。确认该文件是根据文件报告的主版本生成的，并说明文件中段的顺序无法识别。

使用哪种方法取决于你对特定文档类型 EDI 段的熟悉程度（以便根据合作伙伴的文件正确编辑 JSON 架构）以及合作伙伴的灵活性（是否会根据你告知的错误调整 EDI 文件）。


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