核心功能
- 完整的 RESTful API 客户端，支持所有 HTTP 方法（GET、POST、PUT、PATCH 和 DELETE）
- 支持 Swagger 导入，可自动配置 API 并生成请求
- 支持高级身份验证，包括 OAuth 2.0、Bearer Token、AWS Signature 以及 Basic/Digest 认证
- 支持在 URL、标头和表单数据中使用 ArcScript 构建动态请求
- 灵活的正文类型，包括 raw、form-data、URL-encoded 和文件上传
概述
REST 端口提供简单接口，用于构建 REST 请求的标头、授权、正文和 HTTP 方法。请求正文可以在端口配置中静态设置，也可以根据端口处理的文件动态生成。操作
端口设置
REST 页面
与端口请求详细信息相关的设置。
认证
与 REST 服务认证相关的设置。请求详情
| 设置 | 说明 |
|---|---|
| 从 Swagger 导入 | 单击  图标可直接从 Swagger URL 导入 API 详细信息。 |
| 测试 | 测试当前配置，而不创建发送到工作流下游的消息或交易。单击测试会打开包含四个选项卡的窗口（更多信息请参见测试请求配置）： 响应正文：查看来自服务器的响应正文。 响应标头：查看服务器响应中包含的标头。 消息标头：查看测试输出中包含的消息标头。 日志：查看端口日志。 |
| 操作 | 端口应执行的操作。（有关三个选项的详细信息，请参见操作。） |
| 请求 URL | REST 请求的 HTTP 方法和目标 HTTP URL。可用方法选项包括：GET、POST、PUT、PATCH 和 DELETE。 |
| 正文类型 | 随 REST 请求提供的正文内容类型。当 HTTP 方法为 GET 时不可见。有关每个选项的说明，请参见正文类型。 |
| 标头 | 标头选项卡支持添加要包含在传出 REST 请求中的 HTTP 标头列表。标头以名称-值对指定。更多信息请参见静态请求。 |
| 正文 | 如果正文类型设置为 form-data 或 x-www-urlencoded，请使用正文选项卡提供一组构成请求正文的名称-值对（字段）。详情请参见正文类型。 |
设置页面
与端口核心配置相关的设置。配置
| 设置 | 描述 |
|---|---|
| 端口 Id | 端口的静态、唯一标识符。 |
| 端口类型 | 显示端口类型及其用途的描述。 |
| 端口描述 | 一个可选字段，用于提供端口及其在流中的角色的自由格式描述。 |
高级设置
高级页面
TLS 客户端认证
与需要双向 TLS 身份验证时的客户端身份验证相关的设置。
| 设置 | 描述 |
|---|---|
| 私有证书 | TLS 客户端身份验证期间提供的私有证书。 |
| 证书密码 | 访问 TLS 客户端证书所需的密码。 |
高级设置
不属于前述类别的设置。代理设置
这是一组用于识别连接所经代理并对其进行身份验证的设置。默认情况下，本节使用 安全设置 页面的 代理设置 部分中的全局设置。清除此复选框可为您的端口提供特定的设置。
| 设置 | 描述 |
|---|---|
| 代理类型 | 基于代理的防火墙使用的协议。 |
| 代理主机 | 基于代理的防火墙的名称或 IP 地址。 |
| 代理端口 | 基于代理的防火墙的 TCP 端口。 |
| 代理用户 | 用于通过基于代理的防火墙进行身份验证的用户名。 |
| 代理密码 | 用于对基于代理的防火墙进行身份验证的密码。 |
| 身份验证方案 | 保留默认值 None 或选择以下身份验证方案之一：Basic、Digest、Proprietary 或 NTLM。 |
日志
用于管理日志创建和存储的设置。
| 设置 | 描述 |
|---|---|
| 日志级别 | 指定要记录在端口日志目录中的信息类型：
|
| 日志文件夹结构 | 指示端口根据选定的时间间隔将日志文件夹中的文件分组。例如，Weekly 选项指示端口每周创建一个新的子文件夹，并将该周的所有日志存储在该文件夹中。空白设置告诉端口将所有日志直接保存在日志文件夹中。对于处理许多事务的端口，使用子文件夹有助于保持日志的有序性并提高性能。 |
| 保留消息副本 | 指示端口在日志目录中保存最新消息副本的切换。请注意，端口每个子文件夹只保留一个消息，并且端口在再次运行时会覆盖以前保存的消息。 |
其他设置
特殊设置适用于特定用例。
| 设置 | 描述 |
|---|---|
| 其他设置 | 允许在以分号分隔的列表中配置隐藏的端口设置，例如 setting1=value1;setting2=value2。正常的端口用例和功能不需要使用这些设置。 |
自动化
自动化设置
与端口自动处理文件相关的设置。性能
与端口资源分配相关的设置。
| 设置 | 描述 |
|---|---|
| 最大工作线程数 | 此端口上处理文件时从线程池中消耗的最大工作线程数。如果设置，则会覆盖 高级设置 页面的 性能设置 部分的默认设置。 |
| 最大文件数 | 分配给端口的每个线程发送的最大文件数。如果设置，则会覆盖 高级设置 页面的 性能设置 部分的默认设置。 |
告警选项卡
SLA 选项卡
事务选项卡
此选项卡列出与端口关联的所有消息。使用搜索栏查找特定消息，或单击漏斗图标应用筛选器。可以按时间、消息方向和/或状态进行筛选。 此选项卡上的选项因端口的操作类型而异：- 如果端口是 Trigger，请使用接收文件按钮启动工作流。
- 如果端口是 Transform 或 Terminal，请使用上传文件按钮将文件上传到工作流。
建立连接
与任何 REST 服务建立连接都需要有效的目标 URL。服务 URL 可以支持各种 HTTP 方法，你应根据特定 Web 服务操作或要检索的数据集配置方法。某些服务可能还需要身份验证或一组自定义标头才能使用该服务。 如果目标 URL 是 HTTPS URL，请将 TLS 服务器证书设置为标识服务器的公钥证书。若要隐式信任目标端点，请将该字段设置为Any Certificate。
认证方式
REST 端口支持多种身份验证类型，每种类型都有自己的要求：- Basic（纯文本）、Digest（加密）和 NTLM 需要用户名-密码身份验证。这些凭据会作为请求中的标头提供给 REST 服务。
- OAuth 身份验证需要在 REST 服务的 Web 门户或开发控制台中注册应用。应用注册中要包含的 Callback URL 会显示在 知行之桥 UI 中。选择适用于 REST 服务的 Grant Type，并根据 REST 服务 Web 门户或开发控制台中显示的详细信息指定其余设置。然后单击获取新的访问令牌以获取与服务交互所需的令牌。检索到初始令牌后，应用程序会在令牌即将过期时刷新它们。
- Bearer Token 身份验证需要来自服务 Web 门户或开发控制台的令牌。
- AWS Signature 身份验证用于对 Amazon 进行身份验证，需要配置 Amazon 提供的凭据：Access Key、Secret Key 等。
测试请求配置
你可以随时测试当前配置，而不创建发送到工作流下游的消息或交易。单击 REST 详情选项卡上的测试。下图显示了成功测试后的响应正文结果。
- 响应正文：以服务器返回的格式显示 REST 请求的输出。
- 响应标头：显示服务器返回响应中包含的响应标头。
- 消息标头：显示测试输出中包含的消息标头。
- 日志：显示测试日志。
正文类型
使用端口的请求详情选项卡指定正文的配置方式以及提供的信息类型。以下列表更详细地说明了每个选项。- none：REST 请求不提供正文。
- form-data：正文以一组名称-值对（字段）提供。使用 Name 旁边的下拉列表选择字段类型。
- Static：同时提供 Name 和 Value。
- XML：在 UI 中提供 Name。Value 会从端口处理的输入文件中动态读取。更多信息请参见动态表单数据。
- File：每个端口可以有一个正文字段设置为 File。这会使输入文件作为请求正文发送。由于端口使用输入文件本身作为表单数据，因此 Value 字段会变灰。
注意：File 选项与动态请求和其他文件请求不兼容。如果使用此选项，只能将其与静态字段结合使用。 - Header：使用 Value 字段指定从输入消息的哪个标头读取正文。
- ArcScript：提供的 Value 会渲染为 ArcScript，结果值会用于请求正文。
- x-www-urlencoded：正文的配置方式与 form-data 相同；但名称-值对会编码为 URL 查询字符串，而不是多部分表单数据。
- raw：正文设置为端口处理的输入文件内容。使用下拉列表选择正文的内容类型，或在标头部分将其指定为自定义标头。
静态请求
内容完全静态的 REST 请求（例如使用 HTTP GET 方法的请求）不需要输入文件，因为请求内容完全在端口 UI 中配置。只需在标头部分添加任何必要的名称-值对作为自定义标头，或在正文部分添加表单数据。 如果启用接收自动化，可以按计划自动发送静态请求。每个请求的响应会存储在输出文件夹中，或传递给工作流中的下一个端口。 如果启用发送自动化，到达端口输入文件夹的文件也会触发静态请求。输入文件的内容会被忽略，请求会根据 UI 中的配置发送。动态请求
REST 请求可以使用到达端口输入文件夹的文件中的数据动态填充。原始输入数据
如果将请求的正文类型设置为raw，输入文件的内容会作为 REST 请求正文发送。
使用内容类型下拉列表设置数据的特定内容类型。如果所需内容类型未列出，可以在标头部分添加 Content-Type 标头。
动态表单数据
如果将请求的正文类型设置为form-data 或 x-www-urlencoded，端口会从输入文件中查找特定值来填充请求。对于设置为 XML 的每个名称-值对，端口会扫描输入文件，查找与字段名称相同且使用特定 XML 结构的 XML 元素，如下所示：
CustomerID 的动态字段，并且输入文件包含如下所示的 XML，则 REST 端口会将 CustomerID 字段的值设置为 12354。
带有 XML 映射的动态模板
将 XML Map 端口与 REST 端口结合使用，可以轻松从其他 XML 数据结构构建动态请求。XML Map 端口会将自定义 XML 结构转换为 REST 端口期望的 XML 结构。 首先，为 REST 端口配置请求中应存在的一组动态（和静态）正文字段。接下来，在 知行之桥 工作流中将 XML Map 端口连接到 REST 端口，并保存工作流更改。这使 XML Map 端口能够检测 REST 端口期望在传入输入文件中出现哪些字段。 然后，在 XML Map 端口中，目标文件下拉列表会包含 REST 请求架构。选择它作为目标，并将源文件设置为自定义 XML 结构。这会填充 XML Map 映射编辑器，你可以将需要包含在 REST 请求中的数据从源结构拖放到目标结构。映射完成后，XML Map 端口会自动将与源文件匹配的文件转换为有效的 REST 请求结构。 有关使用 XML Map 端口的更多信息，请参见 XML Map 端口文档。URL
如果在端口配置窗格的高级页面上选择允许在 URL 中使用 ArcScript，即可对 ArcScript 中的表达式求值，以生成动态字符串作为 URL。例如，以下 URL 包含日期和时间：http://myendpoint.com/api?day=[_ | now('yyyyMMdd')]
此 URL 包含用于通过发送自动化触发的查询的传入消息标头：
http://myendpoint.com/api?customer=[_message.header:customerid]
最后，此 URL 使用从上次查询时间到当前时间戳的动态日期范围，并为第一次查询使用默认时间戳：
http://myendpoint.com/api?DateFrom=[_connector.lastruntimestamp | def('2025-01-01T00:00:00-04:00')]&DateTo=[_connector.currenttimestamp]
标头
如果在端口配置窗格的高级页面上选择允许在标头中使用 ArcScript，即可对 ArcScript 中的表达式求值，以生成动态字符串作为标头值。例如，以下标头包含日期和时间：Timestamp [_ | now('yyyyMMdd')]
以下标头包含用于通过发送自动化触发的查询的客户 ID：
Customer [_message.header:customerid]
响应事件
可以在 REST 端口中使用响应事件与从服务器接收的响应（包括正文、标头、Cookie 等）交互，并丰富端口生成的输出消息。可以在Response 事件中使用以下特殊项目。
响应事件 Example
此脚本读取从 REST 调用接收的 JSON 响应，解析出 JSON 中包含的访问令牌，并将其作为标头添加到 REST 端口创建的输出消息上：_response.body 访问服务器发送回知行之桥中 REST 端口的响应正文，并将其设置为 jsonDOMGet 操作的 text 属性。jsonDOMGet 的其他属性也会被填充，例如 map 属性，其中包含响应正文中所需令牌的 jsonpath。
2 调用 jsonDOMGet 操作。如果在响应 JSON 正文中找到令牌，则会通过 _message.header:access_token 语法将其作为消息标头添加到 REST 端口的输出消息。如果未找到令牌，则 access_token 标头的值会设置为静态字符串：Token not found!。
在 知行之桥 中查看来自 REST 端口的消息的输出消息详细信息时，结果如下所示：
