AS4 端口 - 知行之桥文档

AS4 端口支持使用 Applicability Statement 4 (AS4) 协议发送和接收消息。

核心功能

现代基于 SOAP 的 B2B 消息传递，支持多种配置文件（ENTSOG、e-SENS、BDEW 和 eDelivery）
具有令牌认证和证书管理的高级安全功能
支持推送和拉取两种消息模式
支持通过服务和操作定义处理业务协议
全面支持消息属性和自定义请求头
已获得 Drummond Group 认证

概述

AS4 连接需要在两个位置进行配置。首先在 AS4 配置文件页面配置本地 AS4 参与方标识符和私钥证书。然后，为单个交易伙伴在各个 AS4 端口中配置专用连接设置。当输入文件由 AS4 端口处理时，它会被打包并发送到指定的交易伙伴。当通过 AS4 接收文件时，会尝试将文件路由到特定的 AS4 端口。应用程序使用 AS4 消息中的 AS4 参与方标识符来确定应由哪个 AS4 端口接收该文件。文件路由到 AS4 端口后，会放入该端口的交易 Tab，或传递到工作流中下一个已连接的端口。 AS4 端口支持共享连接。这意味着在一个端口中创建的连接和配置也会显示在设置 > 连接 Tab 中，以便在其他 AS4 端口中重复使用。

配置文件配置

必须先配置 AS4 配置文件，才能与各个 AS4 端口建立连接。单击导航栏上的配置文件，然后单击 AS4 Tab。

AS4 配置文件 Tab

个人 ID

用于标识本地配置文件的设置。

设置	说明
参与方标识符	你的 AS4 标识符。发送的消息必须寻址到此标识符，传出消息也使用此值标识消息发起方。标识符区分大小写。
参与方标识符类型	参与方标识符的可选类型声明。如果指定，请提供该标识符所属的域。

个人证书

与私有解密和签名证书相关的设置。

设置	说明
私钥证书	用于解密传入消息并签名传出消息的证书。切勿与外部方共享此证书。单击创建证书按钮生成可用于 AS4 交易的自签名证书；同时还会生成一个同名、扩展名为 `.cer` 的对应公钥证书。
证书密码	访问私钥证书所需的密码。

轮转证书

设置	说明
轮转私钥证书	一个辅助私钥证书；如果使用私钥证书解密失败，可用它解密传入消息。仅在更换证书且需要重叠期以接收使用旧证书或新证书加密的传入消息时，才使用此设置。轮转证书绝不会用于签名传出消息；发送给仍在使用旧证书的交易伙伴时，这可能导致签名验证问题。
轮转私钥证书密码	访问轮转私钥证书所需的密码。

日志

应用程序 URL

与从公网访问相关的设置和显示值。

设置	说明
接收 URL	侦听传入 AS4 消息的 URL。请与所有交易伙伴共享此 URL。

其他

端口配置

配置全局 AS4 配置文件设置后，可在工作流页面为每个交易伙伴创建并配置单独的 AS4 端口。

设置 Tab

配置

设置	说明
端口 ID	端口的静态唯一标识符。
端口类型	显示端口名称及其功能说明。
端口描述	可选字段，用于自由描述端口及其在工作流中的作用。
连接	可用 AS4 连接列表。选择现有连接，或单击创建添加新连接。有关添加连接页面中选项的说明，请参阅建立连接。

连接信息

与指定交易伙伴连接参数相关的设置。

设置	说明
消息发送安全性	是否签名和/或加密传出的 AS4 消息。强烈建议使用签名和加密。
消息接收安全性	是否要求传入的 AS4 消息包含签名和/或加密。如果收到的消息缺少必需的安全参数，将引发错误。
压缩	是否压缩传出消息的负载。
消息分区通道	AS4 交换应通过的通道。如果未指定通道，则会隐式分配默认消息分区通道（MPC）。发送或接收拉取请求时，MPC 很重要，因为只有分配的 MPC 中排队的消息才会作为拉取请求的响应返回。

回执

与发送 AS4 消息时请求回执相关的设置。

设置	说明
启用回执	是否应返回回执以响应传入 AS4 消息，以及是否期望对传出的 AS4 消息返回回执。
传输	回执是作为传出 AS4 消息的直接响应返回（同步），还是稍后通过单独连接返回（异步）。除非 AS4 消息非常大（常见阈值为 50MB），导致处理消息并传递同步回执可能使连接超时时长紧张，否则建议使用同步回执。

业务协议详情

与 AS4 业务协议共享详情相关的设置。配置前应与交易伙伴确认这些值。

设置	说明
服务	接受消息的业务流程。
服务操作	业务流程中正在执行的操作或活动。
服务类型	为服务提供上下文的可选限定符。
发送方角色	消息来源方的角色。根据伙伴协议，发送和接收 AS4 请求时这些角色可以颠倒，也可以保持不变。此值用于生成的 AS4 SOAP 信封的 `PartyInfo` 元素中。
接收方角色	消息交付目标方的角色。根据伙伴协议，发送和接收 AS4 请求时这些角色可以颠倒，也可以保持不变。此值用于生成的 AS4 SOAP 信封的 `PartyInfo` 元素中。

高级设置

设置	说明
本地文件命名方案	为端口输出的消息分配文件名的方案。可以在文件名中动态使用宏，以包含标识符、时间戳等信息。更多信息，请参阅宏。

高级 Tab

消息属性

可以提供一组以名称-值对形式指定的自定义消息属性，作为传出消息的一部分包含在内。在 UI 中设置名称-值对，等同于在消息到达 AS4 端口之前对消息执行 <arc:set attr="Header:AS4-MessageProperty" value="Name=Value" />。可以根据消息内容动态覆盖消息属性，或指定 string 以外的类型。为此，请使用类似以下脚本添加消息头：

<arc:set attr="Header:AS4-MessageProperty" value="PModeName=http://example.org/pmode;Country=LU" />
<arc:set attr="Header:AS4-MessagePropertyType" value="PModeName=string;Country=string" />

AS4-MessagePropertyType 中指定的名称必须与 AS4-MessageProperty 中使用的名称匹配。多个属性用分号分隔。例如，以下示例在上述脚本基础上扩展了一个 integer 属性：

<arc:set attr="Header:AS4-MessageProperty" value="PModeName=http://example.org/pmode;Country=LU;MessageCount=5" />
<arc:set attr="Header:AS4-MessagePropertyType" value="PModeName=string;Country=string;MessageCount=integer" />

其他设置

先前类别中未包含的设置。

设置	说明
附加 XML 文件	XML 负载应作为 MIME 附件打包到 SOAP 消息中，还是直接包含在 SOAP 正文中。
重复消息操作	当端口收到包含此前见过的 Message Id 的 AS4 消息时，应如何处理。端口通过_记住_在重复间隔指定分钟数内接收的 Message Id 来检测重复消息。选项：继续 — 像处理其他文件一样处理重复文件。忽略 — 忽略传入文件，且不将其写入接收文件夹。失败 — 引发错误且不处理该文件。
重复间隔	具有相同 Message Id 的消息被视为重复的分钟数。如果设置为 0，Message Id 将一直存储到服务器重启。
拉取 URL	发送拉取请求的 URL 端点。仅当它与伙伴 URL 不同时才需要。
回执 URL	发送回执的 URL 端点。仅当它与伙伴 URL 不同时才需要。
处理延迟	放入交易 Tab 的文件延迟处理的时间（秒）。这是一个旧设置。最佳实践是使用文件端口来管理本地文件系统，而不是使用此设置。

代理设置

消息

日志

其他

自动化 Tab

自动化设置

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

设置	说明
发送	到达端口的文件是否会自动作为 AS4 消息发送。
重试间隔（分钟）	发送失败后重试前等待的分钟数。当服务器未响应发送尝试，或返回否定响应表示未收到文件时，将触发重试。
最大尝试次数	端口处理输入文件的最大次数。是否成功取决于服务器成功确认以及回执验证（同步请求回执时）。如果设置为 0，端口将无限期重试该文件。
重发间隔（分钟）	重新发送未确认消息前等待的分钟数。当服务器收到文件，但未在预期时间范围内提供异步回执时，将触发重发。
最大尝试次数（异步）	请求异步回执时，端口处理输入文件的最大次数。是否成功取决于服务器成功确认后，异步回执是否在重发间隔内返回。如果未返回成功的服务器确认，则改用最大尝试次数。如果设置为 0，端口将无限期重发该文件。
接收	端口是否应自动发出拉取请求，以从交易伙伴接收消息。
间隔	自动拉取请求之间的间隔。
整点后分钟数	小时计划的分钟偏移量。仅当上述间隔设置为_每小时_时适用。
时间	尝试发生的具体时间。仅当上述间隔设置为_每天_、_每周_或_每月_时适用。
日期	尝试发生的日期。仅当上述间隔设置为_每周_或_每月_时适用。
分钟数	尝试下载前等待的分钟数。仅当上述间隔设置为_分钟_时适用。
Cron 表达式	表示 cron 表达式的五段字符串，用于确定尝试发生的时间。仅当上述间隔设置为_高级_时适用。

性能

警报 Tab

SLA Tab

建立连接

创建新连接时，首先提供一个名称，然后完成以下设置。 用于识别并连接到特定 AS4 交易伙伴的设置。

设置	说明
参与方标识符	目标交易伙伴专用的 AS4 参与方标识符。此值用于传出请求的报头中以指示预期接收者，也用于将传入的 AS4 消息路由到相应的 AS4 端口。标识符区分大小写。
参与方标识符类型	参与方标识符的可选类型声明。如果指定，请提供该标识符所属的域。
URL	发送传出 AS4 消息的交易伙伴公共端点。
协议	管理交换的共享 AS4 协议。在 ENTSOG 配置文件中，此项为必需。
连接超时（秒）	端口在抛出超时错误之前等待连接响应的时长（秒）。
配置文件	AS4 交换中使用的 AS4 配置文件。配置文件有助于确定共享配置设置，以确保伙伴之间兼容。可用配置文件包括：`Standard`、`ENTSOG`、`e-SENS`、`BDEW`、`ENTSOG V4` 和 `eDelivery V2`。如果使用 BDEW，则需要一些额外配置。详情请参阅配置 BDEW 配置文件。多个高级设置（包括加密算法、签名算法、安全令牌格式和 SSL 启用协议）允许选择 `Auto` 值。使用 `Auto` 时，端口会根据配置文件设置自动为每个设置选择适当的值。如有需要，仍可手动覆盖这些值。
加密证书	发送消息时用于 AS4 加密的公钥证书。该证书必须与交易伙伴的私钥证书配对，交易伙伴在共享 AS4 配置详情时应提供公钥证书。
验证证书	接收消息时用于验证 AS4 签名的公钥证书。此字段通常不是必需的；大多数 AS4 参与方使用同一个私钥证书进行签名和解密。如果未指定此值，应用程序将使用加密证书验证签名。
TLS 服务器证书	用于验证 TLS/SSL 服务器身份的公钥证书。如果交易伙伴未提供 TLS 服务器证书，可以将此设置留空，以允许底层 OS/JVM 执行证书验证；也可以将其设置为 `Any Certificate`，以无条件信任目标服务器的身份。
轮转验证证书	一个辅助证书；如果使用验证证书验证失败，可用它验证消息签名。仅在更换证书且需要重叠期时使用此设置。

高级连接设置

单击高级 Tab 设置以下连接选项。

令牌认证

与使用和要求令牌认证相关的设置。

设置	说明
令牌认证（接收）	传入 AS4 消息是否必须包含认证令牌。如果启用，传入消息必须包含与此选项下设置的用户名和密码字段匹配的用户名凭据。
令牌认证（发送）	传出 AS4 消息是否应包含认证令牌。如果启用，传出消息将包含与此选项下设置的用户名和密码字段匹配的用户名凭据。
密码类型	用户名令牌应采用纯文本格式还是加密摘要格式。

备用本地配置文件

此特定 AS4 端口中用于覆盖配置文件页面 AS4 配置的设置。设置备用本地配置文件后，可以为某些交易伙伴使用不同的本地证书和标识符。

设置	说明
参与方标识符	你的 AS4 标识符。覆盖“配置文件”页面上的参与方标识符。
参与方标识符类型	你的 AS4 标识符类型（可选）。覆盖“配置文件”页面上的参与方标识符类型。
私钥证书	用于解密传入消息并签名传出消息的证书。覆盖“配置文件”页面上的私钥证书。
私钥证书密码	访问本地私钥证书所需的密码。
证书主题	指定证书库中本地证书的唯一名称（DN），用于签名或解密消息。

TLS 客户端认证

需要双向 TLS 认证时，与客户端认证相关的设置。

设置	说明
使用配置文件设置	是否使用“配置文件”页面上配置的私钥证书作为客户端认证的 TLS 证书。
私钥证书	TLS 客户端认证期间提供的私钥证书。仅当不使用“配置文件”页面中的同一私钥证书时适用。
私钥证书密码	访问 TLS 客户端证书所需的密码。
证书主题	指定证书库中本地证书的唯一名称（DN），用于 TLS 认证。

其他设置

先前类别中未包含的设置。

设置	说明
协议引用 P-Mode	共享 AS4 协议的处理模式属性。如果使用此项，请提供 `PMode.Id` 参数。
接收协议引用 P-Mode	共享 AS4 接收协议的处理模式属性。如果使用此项，请提供 `PMode.Id` 参数。
协议引用类型	共享 AS4 协议的引用类型属性。双方应协商确定此值的含义。
加密算法	如果需要消息加密，应使用哪种加密算法。
安全令牌格式	指定在加密和签名时包含在消息中的安全令牌格式。选项： Auto（根据配置文件自动选择）。 X.509（DN 格式的主题）。 Binary（Base64 编码的公钥）。 KeyIdentifier（X.509 Subject-Key-Identifier 格式）。 BinaryPKIPath（Base64 编码的 X509 公钥证书有序列表）。
签名安全令牌格式	指定签名时使用的安全令牌格式（可选）。如果设置此值，则签名时将使用该值，而不是安全令牌格式的值。选项： Auto（根据配置文件自动选择）。 X.509（DN 格式的主题）。 Binary（Base64 编码的公钥）。 KeyIdentifier（X.509 Subject-Key-Identifier 格式）。 BinaryPKIPath（Base64 编码的 X509 公钥证书有序列表）。
签名算法	签名传出消息时使用的算法。相应回执也会请求使用同一算法。设置为 `Auto` 时，端口会根据选定配置文件自动选择适当的值。
启用的 TLS 协议	建立传出连接时支持的 TLS/SSL 协议列表。最佳实践是仅使用 TLS 协议。SSL v2 和 SSL v3 被认为存在漏洞，只有在伙伴不支持更高版本时才应使用。请注意，TLS v1.3 尚未被普遍采用，如果目标服务器不支持，可能会被拒绝。
签名证书	用于签名传出消息的私钥证书。如果设置此项，将使用该证书签名传出的 AS4 消息，而不是使用 AS4 配置文件中配置的私钥证书。
签名证书密码	访问和使用与签名证书关联的私钥所需的密码。
RSA 哈希算法	RSA 签名操作中用于创建消息摘要的加密哈希算法（例如 SHA-256）。
引用哈希算法	引用中使用的加密哈希算法（例如 SHA-256），用于确保单个消息部分的完整性。
标准化颁发者主题	允许标准化证书颁发者和主题唯一名称的格式，以实现一致的证书验证。默认值为 `false`。
密钥加密算法	用于加密保护消息负载的对称会话密钥的算法（例如 RSA-OAEP 或 RSA-v1.5）。
MGF1 哈希算法	密钥加密期间作为 RSA-OAEP 填充一部分，在掩码生成函数 1（MGF1）中使用的哈希算法。
OAEP 参数	最佳非对称加密填充（OAEP）中使用的可选参数，用于在 RSA 加密期间提供额外随机化。
转换回执	在签名前对回执和确认消息应用 XML 规范化或其他转换的设置。默认值为 `true`。
签名拉取请求	是否对发送的 AS4 拉取请求消息进行数字签名，以从交易伙伴服务器检索消息。
启用引用令牌类型	是否在消息头中包含安全令牌引用信息，以指定如何识别证书和密钥。
接收方密钥	消息接收方的公钥或证书，用于加密消息负载以进行机密传输。
密钥派生方法	AS4 安全处理中用于从共享密钥或密钥协商协议派生加密密钥的算法。

配置 BDEW 配置文件

BDEW（Bundesverband der Energie- und Wasserwirtschaft，即德国能源和水工业联合会）AS4 配置文件是由德国能源和水务行业定义的消息规范。配置 AS4 端口使用 BDEW 配置文件时，必须先添加以下消息头，然后才能将消息传递给端口。

<arc:set attr="output.header:AS4-DataProperty#" value="[Filename]; BDEWDocumentType=MSCONS" />
<arc:set attr="output.header:AS4-DataProperty#" value="[Filename]; BDEWDocumentDate=202205011630" />
<arc:set attr="output.header:AS4-DataProperty#" value="[Filename]; BDEWDocumentNo=1234567AB" />
<arc:set attr="output.filepath" value="[filepath]" />
<arc:push item="output" />

个人配置文件配置

AS4 配置文件包含交易伙伴用于识别你的关键信息。它在“配置文件”页面的 AS4 Tab 中配置。首先，请指定以下信息：

参与方标识符
个人证书

参与方标识符

与电子邮件交换中的电子邮件地址类似，它用于标识 AS4 传输中的伙伴。将参与方标识符设置为能有意义地标识你或你的组织的值。此处设置的值会在发起的 AS4 传输头部中发送。参与方标识符是共享配置文件信息时与交易伙伴交换的信息之一。交易伙伴应在其 AS4 系统中使用此值，以便处理来自该标识符的请求。

个人证书

私钥证书用于签名传出消息并解密传入消息。AS4 配置文件使用 PKCS#12 格式（.pfx 或 .p12 文件）的私钥证书。

在私钥证书下拉菜单中单击上传证书，从磁盘选择现有证书。
单击创建证书创建新的自签名证书。这会创建一个新的私钥证书以及同名的公钥证书（.cer 文件）。

接收 URL

此值基于设置 > 高级中的基础 URL 和默认的侦听端点生成。请与交易伙伴共享此值，以便他们能够成功向发送 AS4 消息。

交易伙伴设置

交易伙伴负责提供连接其 AS4 端点所需的特定设置。每个 AS4 端口都必须配置为单一交易伙伴关系。以下 AS4 配置选项为必需：

交易伙伴标识符
伙伴 URL
交易伙伴证书
使用回执
服务和服务操作

交易伙伴标识符

交易伙伴提供其参与方标识符，这是其配置文件中用于在 AS4 传输中标识组织的部分。该标识符用于传出请求的头部，以指示预期接收者。

此值区分大小写，因此配置新的交易伙伴时，请确保大小写正确。

伙伴 URL

伙伴 URL 是交易伙伴的 AS4 系统侦听传入消息的公共端点。收到交易伙伴提供的 URL 后，请使用 Web 浏览器测试该 URL，以检测任何网络或连接问题。在某些情况下，如果交易伙伴使用不同 URL 推送 AS4 传输、拉取 AS4 传输以及返回异步回执，可能会提供多个 URL。请在“高级” Tab 的拉取 URL 和回执 URL 下配置其他 URL。

交易伙伴证书

每个 AS4 端口都必须配置目标交易伙伴的公钥证书。交易伙伴会提供加密和验证与其交换的 AS4 消息所需的证书。接受 X.509 公钥证书（扩展名为 .cer、.der 或 .pem 的文件）。通常，交易伙伴会提供一个证书，应将其配置在加密证书字段中。如果交易伙伴提供多个证书，则必须说明每个证书的用途。如果伙伴提供完整证书链（例如从商业证书颁发机构获取），则只需配置叶子证书（证书链中的最后一个证书）。有时可能需要单独的公钥证书来验证伙伴的数字签名。在这种情况下，请在设置 Tab > 交易伙伴证书 > 验证证书中设置签名验证证书。如果交易伙伴要求 TLS/SSL 连接，他们可以提供其 TLS 服务器的公钥证书。应在 TLS 服务器证书下设置该证书。或者，可以将此字段设置为 Any Certificate，以隐式信任目标 TLS 服务器的身份。

使用回执

请求回执可确保 AS4 消息的不可否认性；换句话说，消息成功送达后不可被否认。因此，强烈建议启用使用回执字段。请务必提前与交易伙伴就回执使用达成一致。默认情况下，回执会同步传递，也就是作为 AS4 消息的直接响应返回。异步回执则稍后通过单独连接传递。除非 AS4 消息非常大，导致处理并传递同步回执可能使连接超时时长紧张，否则建议使用同步回执。

服务和服务操作

服务、服务操作和其他业务协议详情应与交易伙伴沟通确认。这些值有助于定义与所交换 AS4 消息关联的业务逻辑，以及各方应如何解读这些消息。

从 SMP 导入

如果交易伙伴具有服务元数据发布者（SMP）配置文件，可以在设置 Tab > 交易伙伴信息中单击从 SMP 导入按钮导入这些设置。随后出现的提示需要提供用于获取 SMP 配置文件的 SML 域、参与者 ID 和 Scheme，以及文档 ID 和 Scheme。端口设置会自动填充从 SMP 配置文件读取的值。

发送和接收文件

配置 AS4 配置文件和特定于伙伴的 AS4 端口后，即可安全地发送和接收文件。

发送文件

在 AS4 端口中，交易 Tab 显示应发送到目标交易伙伴的文件。如果在自动化 Tab 上启用了发送自动化，到达端口交易 Tab 的文件会自动封装并发送。展开与已传输文件关联的行，即可访问所有传输的日志文件。 创建测试文件按钮可生成一组简单的测试文件，以发送给交易伙伴。

重发和重试

当预期交易伙伴返回异步回执，但其未在重发间隔时长内（默认为 60 分钟）返回时，将触发 AS4 重发。随后应用程序会尝试重新发送该传输。应用程序将继续重发消息，直到收到回执或**最大尝试次数（异步）**用尽为止。当交易伙伴的 HTTP 响应表明服务器未收到传输（响应不是肯定的 200 OK 状态）时，将触发重试。这可能表示网络或连接问题，且通常是暂时性的。应用程序每隔重试间隔分钟重试一次传输，直到传输被接收或最大尝试次数用尽为止。

接收文件

在 AS4 端口中，交易 Tab 显示应用程序已接收并路由到该端口的文件（基于传入 AS4 消息中的 AS4 标识符）。展开每个文件行可显示该传输的可用日志列表。这些文件可在端口的交易 Tab 中查看。如果端口连接到工作流中的其他端口，文件会自动从 AS4 端口的交易 Tab 移动到工作流中下一个端口的交易 Tab。

​核心功能

​概述

​配置文件配置

​AS4 配置文件 Tab

​个人 ID

​个人证书

​轮转证书

​日志

​应用程序 URL

​其他

​端口配置

​设置 Tab

​配置

​连接信息

​回执

​业务协议详情

​高级设置

​高级 Tab

​消息属性

​其他设置

​代理设置

​消息

​日志

​其他

​自动化 Tab

​自动化设置

​性能

​警报 Tab

​SLA Tab

​建立连接

​高级连接设置

​令牌认证

​备用本地配置文件

​TLS 客户端认证

​其他设置

​配置 BDEW 配置文件

​个人配置文件配置

​参与方标识符

​个人证书

​接收 URL

​交易伙伴设置

​交易伙伴标识符

​伙伴 URL

​交易伙伴证书

​使用回执

​服务和服务操作

​从 SMP 导入

​发送和接收文件

​发送文件

​重发和重试

​接收文件

​宏

​示例

核心功能

概述

配置文件配置

AS4 配置文件 Tab

个人 ID

个人证书

轮转证书

日志

应用程序 URL

其他

端口配置

设置 Tab

配置

连接信息

回执

业务协议详情

高级设置

高级 Tab

消息属性

其他设置

代理设置

消息

日志

其他

自动化 Tab

自动化设置

性能

警报 Tab

SLA Tab

建立连接

高级连接设置

令牌认证

备用本地配置文件

TLS 客户端认证

其他设置

配置 BDEW 配置文件

个人配置文件配置

参与方标识符

个人证书

接收 URL

交易伙伴设置

交易伙伴标识符

伙伴 URL

交易伙伴证书

使用回执

服务和服务操作

从 SMP 导入

发送和接收文件

发送文件

重发和重试

接收文件

宏

示例