核心功能
- 完整的 RESTful API 客户端，支持所有 HTTP 方法（GET、POST、PUT、PATCH 和 DELETE）
- 支持 Swagger 导入，可自动配置 API 并生成请求
- 支持高级身份验证，包括 OAuth 2.0、Bearer Token、AWS Signature、API Key 以及 Basic/Digest 认证
- 支持在 URL、标头和表单数据中使用 Script 构建动态请求
- 灵活的正文类型，包括 raw、form-data、URL-encoded 和文件上传
概述
REST 端口提供简单接口，用于构建 REST 请求的标头、授权、正文和 HTTP 方法。请求正文可以在端口配置中静态设置，也可以根据端口处理的文件动态生成。操作
端口配置
设置选项卡
与端口核心配置相关的设置。配置
高级设置
REST 详情选项卡
与端口请求详细信息相关的设置。
| 设置 | 说明 |
|---|---|
| REST 详情 | 选择端口应执行的操作。（有关三个选项的详细信息，请参见操作。） |
| 从 Swagger 导入 | 单击  图标可直接从 Swagger URL 导入 API 详细信息。 |
| 测试 | 测试当前配置，而不创建发送到工作流下游的消息或交易。单击测试会打开一个包含其他选项卡的窗口（更多信息请参见测试请求配置）。 |
| 请求 URL | REST 请求的 HTTP 方法和目标 HTTP URL。可用方法选项包括：GET、POST、PUT、PATCH 和 DELETE。 |
| 允许在 URL 中使用 Script | 勾选此项可在发出查询前对 URL 中的 Script 表达式求值。选择此项后，会显示  按钮，使你能够使用 Script 构建动态请求 URL。详情请参见使用 Script 编辑器构建请求 URL 和标头。 |
| 正文类型 | 随 REST 请求提供的正文内容类型。当 HTTP 方法为 GET 时不可见。有关每个选项的说明，请参见正文。 |
| 内容类型 | 原始数据传输使用的内容类型。仅当正文类型设置为 raw 时可见。 |
查询参数
使用此选项卡向请求 URL 添加查询参数。以名称-值对形式提供参数，并可选择添加说明。单击保存以使用参数更新 URL。
api.example.com 请求 URL 会变为：https://api.example.com/orders?status=pending&limit=50
单击右侧的省略号可设置另外两个选项：批量编辑视图和隐藏说明列。
认证
使用此选项卡配置 API 请求的身份验证凭据。标头
此选项卡使你能够添加要包含在传出 REST 请求中的 HTTP 标头列表。标头也以名称-值对指定。更多信息请参见静态请求和动态请求。单击右侧的省略号可访问另外三个选项：批量编辑视图、允许在标头中使用 Script 和显示自动生成的标头。有关使用 Script 编辑器的详细信息，请参见使用 ArcScript 编辑器构建请求 URL 和标头。正文
如果正文类型设置为form-data 或 x-www-urlencoded，请使用正文选项卡提供构成请求正文的一组名称-值对（字段）。以下列表更详细地说明了每个选项。
- none：REST 请求不提供正文。
- form-data：正文以一组名称-值对（字段）提供。使用 Name 旁边的下拉列表选择字段类型。
- Static：同时提供 Name 和 Value。
- XML：在 UI 中提供 Name。Value 会从端口处理的输入文件中动态读取。更多信息请参见动态表单数据。
- File：每个端口可以有一个正文字段设置为 File。这会使输入文件作为请求正文发送。由于端口使用输入文件本身作为表单数据，因此 Value 字段会变灰。
- Header：使用 Value 字段指定从输入消息的哪个标头读取正文。
- Script：提供的 Value 会渲染为 Script，结果值会用于请求正文。
- x-www-urlencoded：正文的配置方式与 form-data 相同；但名称-值对会编码为 URL 查询字符串，而不是多部分表单数据。
- raw：正文设置为端口处理的输入文件内容。使用下拉列表选择正文的内容类型，或在标头部分将其指定为自定义标头。
form-data 和 x-www-form-urlencoded 正文类型提供内容类型。
选项
与请求相关的其他设置。高级选项卡
认证
高级设置
_不属于前述类别的设置。代理设置
日志
其他设置
自动化选项卡
自动化设置
与端口自动处理文件相关的设置。性能
告警选项卡
SLA 选项卡
交易选项卡
此选项卡列出与端口关联的所有消息。使用搜索栏查找特定消息，或单击漏斗图标应用筛选器。可以按时间、消息方向和/或状态进行筛选。 此选项卡上的选项因端口的操作类型而异：- 如果端口是 Trigger，请使用接收文件按钮启动工作流。
- 如果端口是 Transform 或 Terminal，请使用上传文件按钮将文件上传到工作流。
建立连接
与任何 REST 服务建立连接都需要有效的目标 URL。服务 URL 可以支持各种 HTTP 方法，你应根据特定 Web 服务操作或要检索的数据集配置该方法。某些服务可能还需要身份验证或一组自定义标头才能使用该服务。 认证选项卡的凭据部分使你能够指定连接凭据。可从以下选项中选择：- 来自连接：选择先前配置的 共享连接，或单击连接字段旁边的加号以创建连接。
- 无凭据适用于公共 API，或通过查询参数或标头处理身份验证的情况。如果目标 URL 是 HTTPS URL，请将 TLS 服务器证书设置为标识服务器的公钥证书。若要隐式信任目标端点，请将该字段设置为
Any Certificate。
创建连接
若要创建新连接，请选择来自连接，然后单击连接字段旁边的加号。- 输入唯一的连接名称。
- 类型始终设置为 REST。
- 选择你的身份验证方案。详情请参见认证方式。
认证方式
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 等。
- API Key 身份验证需要一个键值对，然后必须指定该键应作为标头还是作为查询参数添加。
测试请求配置
你可以随时测试当前配置，而不创建发送到工作流下游的消息或交易。单击 REST 详情选项卡上的测试。下图显示了成功测试 Trigger 端口后的响应正文结果。
- 响应正文：以服务器返回的格式显示 REST 请求的输出。
- 响应标头：显示服务器返回响应中包含的响应标头。
- 消息标头：显示测试输出中包含的消息标头。
- 日志：显示测试日志。
- 只有在请求正文中定义了 XML 字段时，XML 选项卡才会填充，如下图所示。
- 如果勾选了允许在 URL 中使用 Script 或允许在标头中使用 Script，请使用标头选项卡提供可能在脚本上下文中使用的消息标头（有关这些选项的详情，请参见使用 Script 编辑器构建请求 URL 和标头）。如果你的请求配置了作为
form-data或x-www-form-urlencoded正文元素的标头，标头名称会显示在此处，你可以提供用于测试的值。 - 日志选项卡包含上次测试的结果。
静态请求
内容完全静态的 REST 请求（例如使用 HTTP GET 方法的请求）不需要输入文件，因为请求内容完全在端口 UI 中配置。只需在标头部分添加任何必要的名称-值对作为自定义标头，或在正文部分添加表单数据。 如果启用接收自动化，可以按计划自动发送静态请求。每个请求的响应会存储在输出文件夹中，或传递给工作流中的下一个端口。 如果启用发送自动化，到达端口交易文件夹的文件也会触发静态请求。输入文件的内容会被忽略，请求会根据 UI 中的配置发送。动态请求
REST 请求可以使用到达端口交易文件夹的文件中的数据动态填充。原始输入数据
如果将请求的正文类型设置为raw，输入文件的内容会作为 REST 请求正文发送。
使用内容类型下拉列表设置数据的特定内容类型。如果所需内容类型未列出，可以在标头部分添加 Content-Type 标头。
动态表单数据
如果将请求的正文类型设置为form-data 或 x-www-urlencoded，端口会从输入文件中查找特定值来填充请求。对于设置为 XML 的每个名称-值对，端口会扫描输入文件，查找与字段名称相同且使用特定 XML 结构的 XML 元素，如下所示：
CustomerID 的动态字段，并且输入文件包含如下所示的 XML，则 REST 端口会将 CustomerID 字段的值设置为 12354。
使用 XML Map 构建动态模板
将 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 端口文档。动态标头
还可以对 Script 中的表达式求值，以生成动态字符串作为标头值。有关详情和示例，请参见标头。使用 Script 编辑器构建请求 URL 和标头
可以使用如下所示的 Script 编辑器构建请求 URL 和标头。下图显示的是请求 URL 编辑器，但标头值编辑器的工作方式相同。
http://myendpoint.com/api?day=[_ | now('yyyyMMdd HH:mm:ss')]
此 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]
可以将表达式直接添加到 URL，也可以使用编辑器编写它们。
选择允许在标头中使用 Script，以便在发出查询前对标头中的 Script 表达式求值。例如，以下标头包含日期和时间：
Timestamp [_ | now('yyyyMMdd')]
此标头包含用于通过发送自动化触发的查询的客户 ID：
Customer [_message.header:customerid]
消息标头
消息标头帮助 跟踪数据在工作流中的进度。所有已跟踪标头都会显示在编辑器的消息标头选项卡上，你可以在表达式中引用它们。 还可以使用编辑器中的添加消息标头字段并提供现有标头的名称，在表达式中包含其他消息标头。这些标头不必是已跟踪标头。保管库
使用 Vault 选项卡可将全局设置保管库中的项目添加到表达式。如果你在整个工作流的不同位置重复使用某些值，这会很有用。你可以在保管库中定义这些值，然后在表达式开头引用它们。请注意，如果希望映射使用保管库中项目的_值_，需要在方括号内引用它；否则编辑器会将项目_名称_解释为字面量。格式化器
格式化器支持操作不同 xpath 返回的值。在表达式中，格式化器用管道字符 (|) 分隔，并从左到右求值。例如：[xpath('City') | toupper | substring(0,3)]
在此示例中，返回 City xpath 的值之前，所有字符串字符都会转换为大写字符，并在结果中返回前三个字符的子字符串。例如，如果源文档有以下值：
<City>Durham</City>
结果表达式返回以下内容：
DUR
格式化器列在格式化器选项卡上。单击列表中的格式化器可将其添加到表达式。
响应事件
可以在 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 端口的消息的输出消息详细信息时，结果如下所示：
