Version 24.3.9111

• 概述
• 端口配置
  • 设置
    • 端口设置
    • 特殊设置
    • 示例请求
    • 文件命名策略
  • 通知
    • 端口邮件设置
    • 服务等级协议 (SLA) 配置
  • 用户
  • 服务器
    • 受信任的 IP 地址
    • 默认速率限制／用户
    • 跨域资源共享 (CORS)
    • 高级设置
    • 消息
    • 日志
    • 特殊设置
• 认证
  • 在基本身份认证中使用身份认证令牌
  • 在 HTTP 头部中使用认证令牌
  • 使用身份认证令牌作为查询字符串参数
• 接收数据
• 示例请求
• 自定义响应

Webhook 端口支持公开公共的 API 接口。

概述

Webhook 端口使数据能够通过 HTTP POST 和 PUT 进入知行之桥工作流。每个 Webhook 端口在应用程序中公开一个接口，外部客户端可以向该接口发送 XML 和 JSON 负载。这些负载将写入到 Receive 文件，并发送到工作流中下一连接的端口。

可以在 Webhook 端口中指定一个示例请求，以简化转换 POST 到接口的数据过程。当指定 XML 示例并将 Webhook 端口连接到工作流中的 XML Map 端口时，XML Map 端口可以自动检测发布到接口的 XML 文件的预期结构。然后，可以使用 XML Map 端口的可视设计器将该结构映射到任意的目标 XML 结构中。

端口配置

设置

端口设置

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

• 端口 Id 端口的静态、唯一标识符。
• 端口类型 显示端口类型及其用途的描述。
• 端口描述 一个可选字段，用于提供端口及其在流中的角色的自由格式描述。
• Webhook 接口 接口所在的生成的 URL（基于端口名）。

特殊设置

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

• 其他设置 允许在以分号分隔的列表中配置隐藏的端口设置，例如setting1=value1;setting2=value2。 正常的端口用例和功能不需要使用这些设置。

示例请求

一个 XML 或 JSON 模板，表示传入数据的预期结构。可以在下面的示例请求中查看更多详细信息。

文件命名策略

用于为端口输出的消息分配文件名的策略。 可以在文件名中动态使用宏来包含标识符和时间戳等信息。 有关详细信息，请参阅宏。

通知

与配置警报和服务等级协议 (SLA) 相关的设置。

端口邮件设置

在执行 SLA 之前，需要设置电子邮件警报以获取通知。 单击 配置通知 将打开一个新的浏览器窗口，转到 系统设置，可以在其中设置系统范围的警报。 有关详细信息，请参阅通知。

服务等级协议 (SLA) 配置

SLA 能够配置期望工作流中的端口发送或接收的数量，并设置期望满足该数量的时间范围。 知行之桥在不满足 SLA 时发送电子邮件警告用户，并将 SLA 标记为 有风险，这意味着如果很快不满足 SLA，则会将其标记为 已违反。 这使用户有机会介入并确定未满足 SLA 的原因，并采取适当的措施。 如果在风险时间段结束时仍未满足 SLA，则将 SLA 标记为违反，并再次通知用户。

要定义 SLA，请单击 添加预期数量条件。

• 如果端口具有单独的发送和接收操作，请使用单选按钮指定 SLA 所属的方向。
• 将 期待至少 设置为期望处理的最小交易数量（交易量），然后使用 每 字段指定时间范围。
• 默认情况下，SLA 每天都有效。 要更改此设置，请取消选中每日，然后选中想要的一周中的几天的框。
• 使用 将状态设置为“有风险” 来指示何时应将 SLA 标记为存在风险。
• 默认情况下，在违反 SLA 之前不会发送通知。 要更改此设置，请选中 发送“有风险”通知。

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

用户

用户选项卡可让：

• 创建用户及其关联的身份验证令牌
• 定义 POST 和/或 PUT 权限
• 指定每个用户每小时可以发出多少个请求
• 指定允许多少个并发请求

可以在此选项卡上添加、编辑和删除用户。

注意：此处的请求设置会覆盖 服务器 选项卡的 默认速率限制 部分中的设置。

服务器

受信任的 IP 地址

定义哪些 IP 地址受信任的设置。

{：。桌子}

• 添加 打开一个模式以输入新的 IP 地址范围。
• 编辑 打开一个模式来修改选定的 IP 地址范围。
• 删除 从列表中删除选定的 IP 地址范围。

以下限制适用：

• localhost 无法修改或从列表中删除。
• 任何超出定义范围的 IP 地址都会被拒绝。
• 支持范围。 例如，条目100.10.100.1-15表示允许100.10.100.1和100.10.100.15之间的 IP 地址。
• 支持无类域间路由 (CIDR) 表示法。 例如，条目100.10.100.0/24表示允许100.10.100.0和100.10.100.255之间的 IP 地址。
• 支持通配符模式。 例如，条目100.10.100.*表示允许以100.10.100开头的 IP 地址。

默认速率限制／用户

如果“用户”选项卡上未提供值，则限制允许的请求数量的设置。

• 每小时最大请求数 单个用户在一小时内可以发出的请求数的限制。
• 最大并发请求 用户可以发出的并发请求数的限制。

跨域资源共享 (CORS)

管理使用 CORS 来服务跨域资源的设置。

• 启用跨源资源共享 (CORS) 是否启用 CORS。 仅当选中此框时，其余选项才可用。
• 允许所有不带 ‘*’ 的域 如果启用，域来源不限于特定列表。
• Access-Control-Allow-Origin 要允许的以逗号分隔的域来源列表。 作为 HTTP 响应消息头包含在内。
• Access-Control-Allow-Credentials 跨域请求中是否允许用户凭据（例如 cookie）。 作为 HTTP 响应消息头包含在内。
• Access-Control-Allow-Methods 允许的以逗号分隔的方法列表。 作为 HTTP 响应消息头包含在内。
• Access-Control-Allow-Headers 允许的消息头的逗号分隔列表。 作为 HTTP 响应消息头包含在内。
• Access-Control-Max-Age 可以缓存 Access-Control 响应消息头值的最大持续时间（以秒为单位）。

高级设置

• 身份验证令牌 选中此项以允许端口在查询字符串参数中传递身份验证令牌以进行身份验证。 有关更多信息，请参阅使用身份验证令牌作为查询字符串参数。

消息

消息设置 确定端口如何搜索消息并在处理后管理它们。 可以将消息保存到你的 已发送 文件夹，或者可以根据 已发送 文件夹方案将它们保存，如下所述。

• 保存至 Sent 文件夹 选中此选项可将端口处理的文件复制到端口的已发送文件夹中。
• 已发送文件夹方案 端口根据选定的时间间隔对已发送文件夹中的文件进行分组。例如，选项每周（Weekly）指示端口每周创建一个新的子文件夹，并将本周发送的所有文件存储在该文件夹中。空白设置告诉端口将所有文件直接保存在“Sent”文件夹中。对于处理许多事务的端口，使用子文件夹可以帮助保持文件有序并提高性能。

日志

• 日志级别 端口生成的日志的详细程度。 当端口请求支持时，请将其设置为 Debug。
• 日志子文件夹方案 指端口根据选定的时间间隔对日志文件夹中的文件进行分组。 例如，Weekly 选项表示端口每周创建一个新子文件夹并将该周的所有日志存储在该文件夹中。 空白设置告诉端口将所有日志直接保存在 Logs 文件夹中。 对于处理大量事务的端口，使用子文件夹有助于保持日志井井有条并提高性能。
• 保留消息副本 选中此项可使已处理文件的日志条目包含文件本身的副本。 如果禁用此功能，端口可能无法从 输入 或 输出 选项卡下载文件的副本。

特殊设置

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

• 其他设置 允许在以分号分隔的列表中配置隐藏的端口设置，例如setting1=value1;setting2=value2。 正常的端口用例和功能不需要使用这些设置。

认证

可以授权用户使用身份验证令牌访问 API 资源，提供 HTTP 身份验证中的身份验证令牌，如下所示。可以在管理控制台的配置信息 > 安全性选项卡上管理 API 用户和允许的 IP 地址。

在调用 API 之前，还需要在配置信息 > 设置中允许特定的 IP 地址连接到 API。默认情况下，所有 IP 地址均受限制。

在基本身份认证中使用身份认证令牌

使用基本身份认证时，应将用户的身份认证令牌用作密码。

在 HTTP 头部中使用认证令牌

将 HTTP 头部 x-cdata-authtoken 与所需的认证令牌一起添加为 HTTP 请求的一部分。

使用身份认证令牌作为查询字符串参数

可以将认证令牌指定为 @authtoken 参数的值，该参数可以作为 HTTP 表单数据或查询参数的一部分提供。但是，默认情况下，应用程序不支持在查询字符串参数中传递认证令牌。可以通过打开 服务器 选项卡后勾选 允许在URL中使用。

接收数据

将数据上传到 Webhook 接口时，Web 请求的主体将作为输出文件写入 Receive 文件夹并发送到工作流中下一个连接的端口。这允许使用灵活的方法通过调用外部 API 来调用知行之桥工作流。

在 Webhook 端口中未验证上传到接口的数据，如有必要，稍后应在工作流中对其进行验证。

示例请求

示例请求字段允许指定对 Webhook 接口进行 API 调用的 XML 或 JSON 结构。

指定示例请求的主要好处是将 Webhook 端口连接到工作流中的 XML Map 端口。当 API 数据需要转换为其它格式（例如 EDI 报文或数据库插入）时，应使用 XML Map 端口。

XML Map 端口可以检测示例请求的 XML 结构，并将其用作 XML Map 设计器的源文件。然后，代表目标格式的 XML 结构应作为 XML Map 端口的目标文件上传，此时，可视化设计器可用于将源结构转换为目标结构。

自定义响应

通常，Webhook 端口接受带有请求已接受的令牌响应的发布数据，但可以使用Response事件自定义响应，其中_request、_httpheaders、_response和_message 特殊项目 可用。 指定后，端口期望通过_response项提供自定义响应。

例如，要将传入请求上的消息头显示为向下传递的消息上的消息头，Response事件中的 ArcScript 可能如下所示：

<arc:set attr="_message.header:MySpecialHeader" value="[_httpheaders.MyWebhookHeader]" />
<arc:set attr="_response.header:Content-Type" value="application/xml" />
<arc:set attr="_response.write" value="<Status>Successfully processed message with MySpecialHeader=[_message.header:MySpecialHeader]</Status>" />

使用上述 ArcScript 中的 响应（Response） 事件，客户端可以发送类似于以下内容的请求：

POST https://localhost/connector/Webhook1/webhook.rsb HTTP/1.1
content-type: application/xml
X-CData-Authtoken: 1s7U4w0a2P3l8v9W3l0q
MyWebhookHeader: Hello World!

<Items>
  <Webhook>Hello World!</Webhook>
</Items>

并收到以下回复：

HTTP/1.1 200 OK
Connection: close
Date: Tue, 31 Aug 2021 19:16:13 GMT
X-Frame-Options: SAMEORIGIN
Content-Type: application/xml
Content-Length: 81
Server: Jetty(9.4.z-SNAPSHOT)

<Status>Successfully processed message with MySpecialHeader=Hello World!</Status>